Desarrolla experiencias de entrenamiento con la API de Google Health

La API de Google Health hace un seguimiento de las sesiones de entrenamiento y el historial de ejercicios del usuario con el tipo de datos de sesión exercise. Una sesión actúa como un contenedor que agrupa los metadatos de actividad, los eventos de pausa y reanudación, las vueltas o los tramos, y las métricas de resumen.

Comprende cómo leer, escribir y estructurar entrenamientos en tu aplicación para brindar la mejor experiencia a tus usuarios.

Tipos de datos admitidos

La API admite el siguiente tipo de datos para hacer un seguimiento de los entrenamientos y las sesiones de actividad:

Tabla: Tipos de datos de entrenamientos de la API de Google Health
Tipo de datos
  dataType Parámetro
  filter		 Record
type		 Operaciones
disponibles		 Alcance Compatibilidad con webhook
 Compatibilidad con True zeros
Ejercicio
  exercise
  exercise 		Sesión list, get, reconcile, create, update, batchDelete activity_and_fitness

Si bien las sesiones de entrenamiento usan el tipo de datos exercise como contenedor, los dispositivos de seguimiento de entrenamiento típicos escriben y leen telemetría detallada y de alta frecuencia durante la sesión. Estas mediciones (como la frecuencia cardíaca o el recuento de pasos) se deben leer o escribir con sus respectivos tipos de datos.

En la siguiente tabla, se asignan los campos dentro del objeto metricsSummary del tipo de datos exercise a los tipos de datos de telemetría sin procesar correspondientes de la API de Google Health:

Campo de resumen (metricsSummary) Nombre del tipo de datos de telemetría intradía ID del tipo de datos de telemetría de la API
caloriesKcal Energía activa quemada active-energy-burned
distanceMillimeters Distancia distance
steps Pasos steps
averageHeartRateBeatsPerMinute Frecuencia cardíaca heart-rate
activeZoneMinutes Minutos en zona activa active-zone-minutes

En las siguientes secciones, se proporcionan detalles técnicos sobre el tipo de datos exercise, incluidos ejemplos de representación de REST, control de rutas de GPS y lineamientos de integración.

Sesiones de entrenamiento

Escribe las actividades o los entrenamientos diarios como puntos de datos de la sesión de exercise. Cada punto de datos describe la sesión general, detalla los intervalos de eventos (como las acciones de pausa y reanudación) y proporciona métricas de resumen (como la distancia total, los pasos y la frecuencia cardíaca promedio).

Atributos de la sesión

Cuando estructures un punto de datos de ejercicio, verifica los siguientes componentes principales:

  • Tiempo de sesión (interval): Hora de inicio y hora de finalización de la sesión de entrenamiento general, junto con los desfases de zona horaria activos en esos momentos.
  • Tipo de actividad (exerciseType): Es la categoría de actividad realizada (como RUNNING, WALKING, BIKING o AEROBIC_WORKOUT). Especifica el tipo exacto de entrenamiento físico.
  • Display Name (displayName): Es un nombre fácil de usar para la sesión de entrenamiento (por ejemplo, "Carrera por la tarde en el sendero").
  • Duración activa (activeDuration): Es el tiempo activo real del entrenamiento, sin incluir los intervalos en pausa. El formato estándar usa el formato Duration (por ejemplo, "1800s").

Métricas de resumen

El objeto anidado metricsSummary contiene métricas totales y promedio calculadas para toda la duración de la sesión de ejercicio:

  • caloriesKcal: Son las calorías activas totales quemadas durante el entrenamiento, medidas en kilocalorías (kcal).
  • distanceMillimeters: Distancia total recorrida, medida en milímetros para mantener una alta precisión en todas las unidades.
  • steps: Pasos totales realizados durante el ejercicio.
  • averageHeartRateBeatsPerMinute: Es la frecuencia cardíaca promedio del usuario durante los minutos de actividad de la sesión.
  • activeZoneMinutes: Minutos en zona activa acumulados durante el entrenamiento.
  • averageSpeedMillimetersPerSecond: Velocidad de movimiento promedio en milímetros por segundo.
  • averagePaceSecondsPerMeter: Es el ritmo promedio durante los minutos de actividad de la sesión, medido en segundos por metro.
  • elevationGainMillimeters: Es el desnivel acumulado total durante la sesión.

Vueltas y parciales

Para los entrenamientos que incluyen vueltas (como correr en pista o nadar en piscina), usa splitSummaries.

Cada división contiene lo siguiente:

  • Un startTime y un endTime específicos.
  • Un activeDuration que representa el tiempo de vuelta real.
  • Es un metricsSummary que solo se aplica a ese segmento.
  • Un splitType para definir los límites de división (como DISTANCE, DURATION o MANUAL).

Eventos de ejercicio

Para calcular con precisión la duración activa, haz un seguimiento de las transiciones de estado (como los eventos de pausa manual o automática) con exerciseEvents.

Cada evento contiene la marca de tiempo (eventTime) y el tipo:

  • START / STOP: Indican las marcas de tiempo de límite de cuándo el usuario inició o detuvo explícitamente la grabación.
  • PAUSE / RESUME: Indica cuándo se pausó o reanudó la sesión de forma manual.
  • AUTO_PAUSE / AUTO_RESUME: Indica las pausas y reanudaciones automáticas controladas por el sensor.

Cómo escribir una sesión de entrenamiento

Para crear, actualizar o importar una sesión de entrenamiento, escribe un punto de datos en la colección de tipo de datos exercise. Usa el extremo de los puntos de datos create.

Ejemplo de representación de REST

En el siguiente ejemplo, se muestra cómo escribir una sesión de entrenamiento con un método POST:

Solicitud

POST https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints
Authorization: Bearer access-token
Content-Type: application/json

{
  "dataSource": {
    "recordingMethod": "ACTIVELY_MEASURED"
  },
  "exercise": {
    "interval": {
      "startTime": "2026-04-20T08:00:00Z",
      "startUtcOffset": "0s",
      "endTime": "2026-04-20T08:35:00Z",
      "endUtcOffset": "0s"
    },
    "exerciseType": "RUNNING",
    "displayName": "Morning Trail Run",
    "activeDuration": "1800s",
    "metricsSummary": {
      "caloriesKcal": 380.0,
      "distanceMillimeters": 5000000.0,
      "steps": "6200",
      "averageSpeedMillimetersPerSecond": 2777.78,
      "averagePaceSecondsPerMeter": 360.0,
      "averageHeartRateBeatsPerMinute": "148",
      "activeZoneMinutes": "30"
    },
    "exerciseMetadata": {
      "hasGps": true
    },
    "exerciseEvents": [
      {
        "eventTime": "2026-04-20T08:15:00Z",
        "eventUtcOffset": "0s",
        "exerciseEventType": "PAUSE"
      },
      {
        "eventTime": "2026-04-20T08:20:00Z",
        "eventUtcOffset": "0s",
        "exerciseEventType": "RESUME"
      }
    ],
    "splitSummaries": [
      {
        "startTime": "2026-04-20T08:00:00Z",
        "startUtcOffset": "0s",
        "endTime": "2026-04-20T08:15:00Z",
        "endUtcOffset": "0s",
        "splitType": "DISTANCE",
        "metricsSummary": {
          "distanceMillimeters": 2500000.0,
          "caloriesKcal": 190.0
        }
      }
    ]
  }
}

Respuesta

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4main.DataPoint",
    "name": "users/me/dataTypes/exercise/dataPoints/morning-trail-run-123456",
    "dataSource": {
      "recordingMethod": "ACTIVELY_MEASURED",
      "application": {
        "packageName": "com.example.workoutapp"
      },
      "platform": "GOOGLE_WEB_API"
    },
    "exercise": {
      "interval": {
        "startTime": "2026-04-20T08:00:00Z",
        "startUtcOffset": "0s",
        "endTime": "2026-04-20T08:35:00Z",
        "endUtcOffset": "0s"
      },
      "exerciseType": "RUNNING",
      "displayName": "Morning Trail Run",
      "activeDuration": "1800s",
      "metricsSummary": {
        "caloriesKcal": 380.0,
        "distanceMillimeters": 5000000.0,
        "steps": "6200",
        "averageSpeedMillimetersPerSecond": 2777.78,
        "averagePaceSecondsPerMeter": 360.0,
        "averageHeartRateBeatsPerMinute": "148",
        "activeZoneMinutes": "30"
      },
      "exerciseMetadata": {
        "hasGps": true
      },
      "exerciseEvents": [
        {
          "eventTime": "2026-04-20T08:15:00Z",
          "eventUtcOffset": "0s",
          "exerciseEventType": "PAUSE"
        },
        {
          "eventTime": "2026-04-20T08:20:00Z",
          "eventUtcOffset": "0s",
          "exerciseEventType": "RESUME"
        }
      ],
      "splitSummaries": [
        {
          "startTime": "2026-04-20T08:00:00Z",
          "startUtcOffset": "0s",
          "endTime": "2026-04-20T08:15:00Z",
          "endUtcOffset": "0s",
          "activeDuration": "900s",
          "splitType": "DISTANCE",
          "metricsSummary": {
            "distanceMillimeters": 2500000.0,
            "caloriesKcal": 190.0
          }
        }
      ]
    }
  }
}

Rutas GPS y seguimiento de la ubicación

La API guarda resúmenes básicos de las sesiones directamente en el punto de datos exercise, pero controla el historial de ubicaciones detallado y las coordenadas de la ruta del GPS como un flujo separado.

Para descargar los datos de ruta detallados de una sesión al aire libre, llama al método personalizado exportExerciseTcx. Este extremo devuelve la ruta en el formato XML del Centro de entrenamiento (TCX) estándar de la industria.

Cómo exportar una ruta de GPS

Solicitud

GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints/exercise-data-point-id:exportExerciseTcx?alt=media
Authorization: Bearer access-token

Respuesta

Una carga útil HTTP con encabezados Content-Type: application/tcx+xml y Content-Type: application/tcx+xml que indican al navegador que guarde el archivo.

<?xml version="1.0" encoding="UTF-8"?>
<TrainingCenterDatabase xmlns="http://www.garmin.com/xmlschemas/TrainingCenterDatabase/v2">
  <Activities>
    <Activity Sport="Running">
      <Id>2026-04-20T08:00:00Z</Id>
      <Lap StartTime="2026-04-20T08:00:00Z">
        <TotalTimeSeconds>1800</TotalTimeSeconds>
        <DistanceMeters>5000</DistanceMeters>
        <Calories>380</Calories>
        <Intensity>Active</Intensity>
        <TriggerMethod>Manual</TriggerMethod>
        <Track>
          <Trackpoint>
            <Time>2026-04-20T08:00:00Z</Time>
            <Position>
              <LatitudeDegrees>37.7749</LatitudeDegrees>
              <LongitudeDegrees>-122.4194</LongitudeDegrees>
            </Position>
            <AltitudeMeters>15.0</AltitudeMeters>
            <DistanceMeters>0.0</DistanceMeters>
          </Trackpoint>
        </Track>
      </Lap>
    </Activity>
  </Activities>
</TrainingCenterDatabase>

Permisos y ubicación obligatorios

Para leer o escribir datos de rutas de GPS y seguimiento de la ubicación, solicita los siguientes permisos de OAuth en el token de acceso de tu aplicación:

  • Acceso de lectura: https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly
  • Acceso de escritura: https://www.googleapis.com/auth/googlehealth.activity_and_fitness.writeonly
  • Acceso de lectura: https://www.googleapis.com/auth/googlehealth.location.readonly

Si falta un alcance requerido en los encabezados de autorización, la API de Google Health devuelve un error de autorización.

Lineamientos

Cuando integres el seguimiento de entrenamiento en tu app, sigue estos lineamientos de diseño y de implementación.

Duración activa en comparación con la duración total

Para calcular las métricas de velocidad o ritmo, siempre usa activeDuration en lugar de la diferencia entre startTime y endTime. Esto evita que los intervalos pausados sesguen tus métricas.

Por ejemplo, si un usuario comienza un entrenamiento a las 08:00 y lo finaliza a las 08:35, el entrenamiento tendrá una duración total transcurrida de 2,100 segundos. Si el usuario pausó el entrenamiento durante 5 minutos (300 segundos), establece activeDuration en "1800s" (2,100 - 300). La API usa la duración activa para calcular los promedios, dividiendo la distancia total por 1,800 segundos en lugar de 2,100.

Solicita la ubicación con anticipación

Si tu app muestra rutas de entrenamiento en un mapa, solicita permisos de ubicación y el alcance location de Google Health, además del alcance de actividad y entrenamiento. Explícales a los usuarios por qué tu app requiere el alcance de la ubicación cuando revisan los ejercicios de GPS.

Cuando tu app solicita el permiso de ubicación (https://www.googleapis.com/auth/googlehealth.location.readonly), Google OAuth muestra un mensaje de consentimiento al usuario. Explícales a los usuarios que este permiso es necesario para renderizar las superposiciones de rutas y exportar archivos de registros GPS (TCX). Si un usuario otorga el alcance de actividad, pero rechaza el permiso de ubicación, exportExerciseTcx devuelve un error de autorización, aunque aún puedes acceder a los agregados de sesión en metricsSummary.

Sincronización en tiempo real con webhooks

Suscríbete al tipo de datos exercise para notificar a tu backend con webhooks cuando haya nuevos datos de entrenamiento disponibles. Esto te permite activar experiencias posteriores al entrenamiento en tiempo real.

Cuando tu servidor recibe una notificación de webhook, esta contiene el healthUserId y el intervalo de tiempo físico específico del entrenamiento. Tu servidor debe procesar la notificación de forma asíncrona y, luego, solicitar el nuevo punto de datos exercise al extremo /users/me/dataTypes/exercise/dataPoints. Para obtener detalles sobre cómo configurar suscripciones, consulta Suscripciones a Webhooks.

Mantén métricas coherentes

Para proporcionar una experiencia de entrenamiento completa, tu app debe sincronizar los puntos de datos de telemetría de alta frecuencia junto con la sesión general de exercise. Esto garantiza que los totales diarios, las tendencias históricas y los gráficos de detalles del usuario permanezcan completamente alineados.

Sincroniza la telemetría y las sesiones (ruta de escritura)

Cuando importes o escribas un entrenamiento completado en la API de Google Health, implementa un patrón de escritura de varios pasos:

  1. Escribe la sesión: Registra el evento de resumen publicando un punto de datos en POST /users/me/dataTypes/exercise/dataPoints.
  2. Escribe intervalos de series temporales: Escribe de forma simultánea los puntos de datos detallados registrados durante el entrenamiento (por ejemplo, intervalos de pasos o calorías quemadas minuto a minuto) en sus respectivas colecciones:
    • POST /users/me/dataTypes/steps/dataPoints
    • POST /users/me/dataTypes/active-energy-burned/dataPoints
    • POST /users/me/dataTypes/heart-rate/dataPoints

Consultar datos detallados para gráficos (ruta de lectura)

Cuando renderices paneles históricos de entrenamiento o gráficos de rendimiento para una sesión de entrenamiento específica, consulta la telemetría detallada con el período de la sesión:

  1. Consultar los resúmenes de la sesión: Llama a /users/me/dataTypes/exercise/dataPoints para recuperar los detalles generales del entrenamiento y el metricsSummary final.
  2. Recupera las métricas del gráfico: Inspecciona los valores de interval.startTime y interval.endTime del entrenamiento. Realiza llamadas secundarias a GET para las recopilaciones de telemetría de ese período específico:
    • GET /users/me/dataTypes/heart-rate/dataPoints?startTime=2026-04-20T08:00:00Z&endTime=2026-04-20T08:35:00Z
  3. Recupera rutas de GPS: Si los metadatos de la sesión indican que hay datos de GPS (exerciseMetadata.hasGps es true), invoca el método auxiliar exportExerciseTcx para descargar las coordenadas de la ruta.
Anterior
Calorías y energía