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 metadatos de actividad, eventos de pausa y reanudación, vueltas o splits, y 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   filter parámetro	Tipo de registro	Operaciones disponibles	Alcance	Compatibilidad con webhook	Compatibilidad con ceros verdaderos
Ejercicio   exercise   exercise	Sesión	list, get, reconcile, create, update, batchDelete	.activity_and_fitness.readonly .activity_and_fitness.writeonly

Tipos de datos de telemetría relacionados

Si bien las sesiones de entrenamiento usan el tipo de datos exercise como contenedor, los monitores 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 propios tipos de datos respectivos.

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 para el tipo de datos exercise, incluidos ejemplos de representación de REST, manejo de rutas de GPS y lineamientos de integración.

Sesiones de entrenamiento

Escribe actividades o entrenamientos diarios como puntos de datos de sesión 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 general, 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:

• Hora de la sesión (interval): La hora de inicio y la hora de finalización de la sesión de entrenamiento general, junto con los desplazamientos de zona horaria activos en esos puntos.
• Tipo de actividad (exerciseType): La categoría de actividad realizada (como RUNNING, WALKING, BIKING o AEROBIC_WORKOUT). Especifica el tipo exacto de entrenamiento físico.
• Nombre visible (displayName): Un nombre fácil de usar para la sesión de entrenamiento (por ejemplo, "Carrera de senderismo por la tarde").
• Duración activa (activeDuration): 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 durante toda la duración de la sesión de ejercicio:

• caloriesKcal: Total de calorías activas 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: Total de pasos dados durante el ejercicio.
• averageHeartRateBeatsPerMinute: Frecuencia cardíaca promedio del usuario durante los minutos de actividad de la sesión.
• activeZoneMinutes: Minutos acumulativos en zona activa obtenidos durante el entrenamiento.
• averageSpeedMillimetersPerSecond: Velocidad de movimiento promedio en milímetros por segundo.
• averagePaceSecondsPerMeter: Ritmo promedio durante los minutos de actividad de la sesión, medido en segundos por metro.
• elevationGainMillimeters: Desnivel acumulado total durante la sesión.

Vueltas y splits

Para los entrenamientos que incluyen vueltas (como carreras en pista o natación en piscina), usa splitSummaries.

Cada split contiene lo siguiente:

• Un startTime y un endTime específicos.
• Un activeDuration que representa el tiempo real de la vuelta.
• Un metricsSummary con alcance solo para 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: Indica las marcas de tiempo límite de cuándo el usuario inició o detuvo explícitamente el registro.
• PAUSE / RESUME: Indica cuándo se pausó o reanudó la sesión de forma manual.
• AUTO_PAUSE / AUTO_RESUME: Indica las pausas o reanudaciones automáticas basadas en sensores.

Escribe 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 tipos de datos exercise. Usa el extremo de 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 de GPS y seguimiento de ubicación

La API guarda resúmenes básicos de sesiones directamente en el punto de datos exercise, pero controla el historial de ubicaciones detallado y las coordenadas de la ruta de GPS como una transmisión separada.

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

Exporta la 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 de HTTP con Content-Type: application/tcx+xml y encabezados 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>

Importante: Debes agregar `?alt=media` a la URL de la solicitud para descargar el archivo TCX sin procesar. De lo contrario, el servidor responde con un sobre JSON estándar.

Permisos y ubicación obligatorios

Para usar la función de rutas de GPS y seguimiento de ubicación, tu app debe solicitar los siguientes permisos de OAuth:

• Lectura: https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly
• Escritura: https://www.googleapis.com/auth/googlehealth.activity_and_fitness.writeonly
• Lectura: https://www.googleapis.com/auth/googlehealth.location.readonly

Lineamientos

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

Duración activa versus total

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

Por ejemplo, si un usuario comienza un entrenamiento a las 08:00 y termina a las 08:35, el entrenamiento tiene 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 asigna rutas de entrenamiento, solicita permisos de ubicación y el permiso location de Google Health, además del permiso de actividad y estado físico. Explica a los usuarios por qué tu app requiere el permiso de 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. Explica a tus usuarios que este permiso es necesario para renderizar superposiciones de rutas y exportar archivos de seguimiento de GPS (TCX). Si un usuario otorga el permiso de actividad, pero rechaza el permiso de ubicación, exportExerciseTcx muestra un error de autorización, aunque aún puedes acceder a los agregados de sesiones 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, 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 exercise punto de datos desde el /users/me/dataTypes/exercise/dataPoints extremo. Para obtener detalles sobre cómo configurar suscripciones, consulta Suscripciones de webhook.

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 exercise general. 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, los pasos por minuto o los intervalos de quema de calorías) 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

Nota: Escribir métricas dentro de los puntos de datos de la sesión de ejercicio no propaga automáticamente los resúmenes agregados de la actividad diaria del usuario (como los recuentos de pasos diarios generales o los gráficos de calorías). Para mantener la coherencia de estas estadísticas de resumen, escribe los puntos de datos sin procesar de forma explícita.

Consulta 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. Consulta 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 el interval.startTime y interval.endTime del entrenamiento. Realiza llamadas GET secundarias a las colecciones de telemetría para 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 las rutas de GPS: Si los metadatos de la sesión indican que hay datos de GPS presentes (exerciseMetadata.hasGps es true), invoca el exportExerciseTcx método auxiliar para descargar las coordenadas de la ruta.