Cómo grabar un entrenamiento

En este documento, se describe cómo registrar un entrenamiento con la API de REST de Fitness.

Importante: Si deseas conocer las prácticas recomendadas para administrar datos del usuario, consulta Uso responsable de Google Fit.

Paso 1: Configura un proyecto

Debes configurar un proyecto en la Consola de APIs de Google y activar el acceso a la API de REST de Fitness, como se describe en Cómo comenzar.

Paso 2: Autentica tu app

Tu app debe autenticar las solicitudes a la API de Fitness con un token de acceso. Para obtener el token de acceso, tu app incluye credenciales específicas del cliente y un permiso de acceso, como se describe en Cómo autorizar solicitudes.

Paso 3: Crea una fuente de datos

Una fuente de datos representa una fuente de datos del sensor de un tipo en particular. Todos los datos insertados en el almacén de entrenamiento debe estar asociado a una fuente de datos. Puedes crear fuentes de datos una vez y volver a usarlas en sesiones futuras.

Para crear una fuente de datos, envía una solicitud HTTP autenticada con estos parámetros:

Método HTTP

POST

Recurso

https://www.googleapis.com/fitness/v1/users/me/dataSources

El ID de usuario me hace referencia al usuario cuyo token de acceso autoriza la solicitud.

Cuerpo de la solicitud

{
"name": "example-fit-heart-rate",
"dataStreamId":
    "raw:com.google.heart_rate.bpm:1234567890:Example Fit:example-fit-hrm-1:123456",
"dataType": {
    "field": [{
        "name": "bpm",
        "format": "floatPoint"
    }],
    "name": "com.google.heart_rate.bpm"
},
"application": {
    "packageName": "com.example.fit.someapp",
    "version": "1.0"
},
"device": {
    "model": "example-fit-hrm-1",
    "version": "1",
    "type": "watch",
    "uid": "123456",
    "manufacturer":"Example Fit"
},
"type": "raw"
}

Esta solicitud crea una fuente de datos que representa un monitor de frecuencia cardíaca que proporciona datos de fitness de tipo com.google.heart_rate.bpm. Debes especificar el ID de la fuente de datos, y puede ser cualquier valor. El ID de la fuente de datos de este ejemplo sigue una convención de nombres razonable que puedes adoptar. El componente del dispositivo es opcional si los datos solo los genera una app.

Si la solicitud se realiza correctamente, la respuesta es un código de estado 200 OK.

Para obtener más información sobre las fuentes de datos, consulta la referencia de la API para el Recurso Users.dataSources.

Paso 4: Agrega datos

Usas conjuntos de datos para insertar datos en la tienda de fitness. Un conjunto de datos es un conjunto de datos puntos de una única fuente de datos limitada por tiempo.

Para crear un conjunto de datos y agregarle puntos, envía una solicitud HTTP autenticada con estos parámetros:

Método HTTP

PATCH

Recurso

https://www.googleapis.com/fitness/v1/users/me/dataSources/
raw:com.google.heart_rate.bpm:1234567890:Example%20Fit:example-fit-hrm-1:123456/datasets/1411053997000000000-1411057556000000000

La URL incluye el ID de la fuente de datos y las horas de inicio y finalización del conjunto de datos en nanosegundos.

Cuerpo de la solicitud

{
"minStartTimeNs": 1411053997000000000,
"maxEndTimeNs": 1411057556000000000,
"dataSourceId":
  "raw:com.google.heart_rate.bpm:1234567890:Example Fit:example-fit-hrm-1:123456",
"point": [
{
  "startTimeNanos": 1411053997000000000,
  "endTimeNanos": 1411053997000000000,
  "dataTypeName": "com.google.heart_rate.bpm",
  "value": [
    {
      "fpVal": 78.8
    }
  ]
},
{
  "startTimeNanos": 1411055000000000000,
  "endTimeNanos": 1411055000000000000,
  "dataTypeName": "com.google.heart_rate.bpm",
  "value": [
    {
      "fpVal": 89.1
    }
  ]
},
{
  "startTimeNanos": 1411057556000000000,
  "endTimeNanos": 1411057556000000000,
  "dataTypeName": "com.google.heart_rate.bpm",
  "value": [
    {
      "fpVal": 62.45
    }
  ]
}
]
}

Esta solicitud crea un conjunto de datos con tres datos de frecuencia cardíaca en una hora para los datos fuente en el paso anterior.

Nota: En el caso de los datos que tienen varios valores (como la ubicación), el orden de los valores debe coincidir con la definición del tipo de datos.

Si la solicitud se realiza correctamente, la respuesta es un código de estado 200 OK.

Para obtener más información sobre los conjuntos de datos, consulta la referencia de la API para el Recurso Users.dataSources.datasets.

Genera marcas de tiempo válidas

Las marcas de tiempo del ejemplo anterior están en nanosegundos. Para generar marcas de tiempo válidas, puedes usar la siguiente secuencia de comandos de Python:

from datetime import datetime, timedelta
import calendar

def date_to_nano(ts):
    """
    Takes a datetime object and returns POSIX UTC in nanoseconds
    """
    return calendar.timegm(ts.utctimetuple()) * int(1e9)

if __name__ == '__main__':
    print 'Current time is %d' % date_to_nano(datetime.now())
    print 'Time 1 hour ago was %d' % date_to_nano(datetime.now() +
       timedelta(hours=-1))

Paso 5: Crea una sesión

Ahora que insertaste los datos en la tienda de entrenamiento, puedes insertar una sesión para proporcionar metadatos adicionales para este entrenamiento. Las sesiones representan un intervalo de tiempo durante el cual los usuarios realizar una actividad física.

Si quieres crear una sesión para este entrenamiento, envía una solicitud HTTP autenticada con estos parámetros:

Método HTTP

PUT

Recurso

https://www.googleapis.com/fitness/v1/users/me/sessions/sessionId

El sessionId es arbitrario y debe ser único para todas las sesiones asociadas con el usuario autenticado.

Cuerpo de la solicitud

{
"id": "example-fit-1411053997",
"name": "Example Fit Run on Sunday Afternoon",
"description": "Example Fit Running Session",
"startTimeMillis": 1411053997000,
"endTimeMillis": 1411057556000,
"application": {
"name": "Foo Example App",
"version": "1.0"
},
"activityType": 8
}

Elige un nombre de sesión que sea legible y descriptivo, ya que es posible que lo usen otras apps para resumir la sesión. Las horas de inicio y finalización de las sesiones se expresan en milisegundos. (no nanosegundos). Usa el mismo nombre de paquete para tus sesiones y fuentes de datos. Esto hace que para que los datos sean más coherentes y garantiza que la atribución de datos se vincule con tu app.

El intervalo de tiempo especificado en esta sesión cubre los datos de frecuencia cardiaca insertados anteriormente, Google Fit asocia esos datos con esta sesión.

Para obtener más información sobre las sesiones, consulta la referencia de la API para la Recurso Users.sessions.

Paso 6: Crea segmentos de actividad

Los segmentos de actividad te ayudan a representar diferentes actividades dentro de una sesión. Un segmento de actividad es un segmento de tiempo que abarca una sola actividad. Por ejemplo, si un usuario sale a correr durante una hora, puedes crear un segmento de actividad de tipo running (8) para toda la hora. Si un usuario corre durante 25 minutos, se toma un descanso durante 5 y, luego, corre otra mitad. por hora, puedes crear tres segmentos de actividad consecutivos de los tipos running, unknown y running, respectivamente.

Crear un segmento de actividad es igual que agregar cualquier otro dato. Para crear segmentos de actividad, primero crea una fuente de datos de segmentos de actividad, luego crea un conjunto de datos y agrégale puntos de datos de segmentos de actividad.

En el siguiente ejemplo, se crean tres segmentos (en ejecución, en reposo y en ejecución) en los mismos períodos que las lecturas de la frecuencia cardíaca, suponiendo que ya creaste un segmento de actividad fuente de datos y el ID de la fuente de datos es "raw:com.google.activity.segment:1234567890:Example Fit:example-fit-hrm-1:123456":

Método HTTP

PATCH

Recurso

https://www.googleapis.com/fitness/v1/users/me/dataSources/
raw:com.google.activity.segment:1234567890/datasets/1411053997000000000-1411057556000000000

Cuerpo de la solicitud

{
"minStartTimeNs": 1411053997000000000,
"maxEndTimeNs": 1411057556000000000,
"dataSourceId":
  "raw:com.google.activity.segment:1234567890",
"point": [
{
  "startTimeNanos": 1411053997000000000,
  "endTimeNanos": 1411053997000000000,
  "dataTypeName": "com.google.activity.segment",
  "value": [
    {
      "intVal": 8
    }
  ]
},
{
  "startTimeNanos": 1411055000000000000,
  "endTimeNanos": 1411055000000000000,
  "dataTypeName": "com.google.activity.segment",
  "value": [
    {
      "intVal": 4
    }
  ]
},
{
  "startTimeNanos": 1411057556000000000,
  "endTimeNanos": 1411057556000000000,
  "dataTypeName": "com.google.activity.segment",
  "value": [
    {
      "intVal": 8
    }
  ]
}
]
}

Estos datos de segmentos de actividad se agregan a una fuente de datos que se creó específicamente para controlar los segmentos de actividad. Podrías crear una nueva fuente de datos para cada conjunto de segmentos, pero deberías reutilizar una dedicada a un tipo particular de sesión, como correr.

Las sesiones especifican un tipo de actividad, que debe coincidir con la actividad general en la que participa el usuario. Incluso si un usuario se toma un descanso mientras corre, el entrenamiento general sigue siendo una carrera. En general, el tipo de actividad de la sesión coincidirá con el tipo de segmento de actividad dominante.

Utilice el tipo de actividad unknown (4) para indicar que un usuario está descansando, ya que es posible que no lo haga. sepa lo que está haciendo el usuario: puede estar quieto o estirándose, bebiendo agua, etcétera. Si sabes que el usuario no se está moviendo, puedes usar inmóvil (3).

Para obtener una lista detallada de los tipos de actividades, consulta Tipos de actividad.

Resumen

En este instructivo, creaste fuentes de datos para tipos de datos y segmentos de actividad, insertaste puntos de datos en la tienda de fitness, creaste segmentos de actividad para representar las diferentes actividades que se realizan durante un entrenamiento y, además, insertaste una sesión que abarca todo el entrenamiento.

Google Fit asocia los datos que insertaste y cualquier otro dato disponible para ese intervalo de tiempo con una sesión que representa el entrenamiento del usuario.