Développer des expériences d'entraînement avec l'API Google Health

L'API Google Health suit les séances d'entraînement et l'historique des exercices des utilisateurs à l'aide du type de données de session exercise. Une session fait office de conteneur qui regroupe les métadonnées d'activité, les événements de pause et de reprise, les tours ou les intervalles, ainsi que les métriques récapitulatives.

Découvrez comment lire, écrire et structurer les entraînements dans votre application pour offrir la meilleure expérience possible à vos utilisateurs.

Types de données acceptés

L'API est compatible avec le type de données suivant pour le suivi des entraînements et des sessions d'activité :

Tableau : Types de données d'entraînement de l'API Google Health
Type de données
  dataType
  filter paramètre		 Type d'enregistrement
 Opérations disponibles
 Champ d'application Compatibilité avec les webhooks
 Compatibilité avec les vrais zéros
Exercice
  exercise
  exercise 		Session list, get, reconcile, create, update, batchDelete activity_and_fitness

Bien que les sessions d'entraînement utilisent le type de données exercise comme conteneur, les trackers d'entraînement classiques écrivent et lisent des données de télémétrie détaillées à haute fréquence pendant la session. Ces mesures (telles que la fréquence cardiaque ou le nombre de pas) doivent être lues ou écrites à l'aide de leurs propres types de données.

Le tableau suivant mappe les champs de l'objet metricsSummary du type de données exercise aux types de données de télémétrie brutes correspondants de l'API Google Health :

Champ récapitulatif (metricsSummary) Nom du type de données de télémétrie intrajournalière ID du type de données de télémétrie de l'API
caloriesKcal Énergie active brûlée active-energy-burned
distanceMillimeters Distance distance
steps Étapes steps
averageHeartRateBeatsPerMinute Fréquence cardiaque heart-rate
activeZoneMinutes Minutes en zone active active-zone-minutes

Les sections suivantes fournissent des détails techniques sur le type de données exercise, y compris des exemples de représentation REST, la gestion des itinéraires GPS et des consignes d'intégration.

Sessions d'entraînement

Écrivez les activités quotidiennes ou les entraînements en tant que points de données de session exercise. Chaque point de données décrit la session globale, détaille les intervalles d'événements (tels que les actions de pause et de reprise) et fournit des métriques récapitulatives (comme la distance totale, les étapes et la fréquence cardiaque moyenne).

Attributs de session

Lorsque vous structurez un point de données d'exercice, vérifiez les composants principaux suivants :

  • Heure de la session (interval) : heure de début et de fin de la session d'entraînement globale, ainsi que les décalages de fuseau horaire actifs à ces moments-là.
  • Type d'activité (exerciseType) : catégorie d'activité effectuée (par exemple, RUNNING, WALKING, BIKING ou AEROBIC_WORKOUT). Spécifiez le type exact d'entraînement physique.
  • Nom à afficher (displayName) : nom convivial de la session d'entraînement (par exemple, "Course à pied en sentier l'après-midi").
  • Durée active (activeDuration) : durée active réelle de l'entraînement, à l'exclusion des intervalles de pause. Le format standard utilise le format Duration (par exemple, "1800s").

Métriques récapitulatives

L'objet imbriqué metricsSummary contient les métriques totales et moyennes calculées sur toute la durée de la session d'exercice :

  • caloriesKcal: total des calories actives brûlées pendant l'entraînement, mesuré en kilocalories (kcal).
  • distanceMillimeters: distance totale parcourue, mesurée en millimètres pour maintenir une haute précision entre les unités.
  • steps : nombre total de pas effectués pendant l'exercice.
  • averageHeartRateBeatsPerMinute: fréquence cardiaque moyenne de l'utilisateur pendant les minutes actives de la session.
  • activeZoneMinutes: nombre cumulé de minutes en zone active gagnées pendant l'entraînement.
  • averageSpeedMillimetersPerSecond: vitesse de déplacement moyenne en millimètres par seconde.
  • averagePaceSecondsPerMeter: allure moyenne pendant les minutes actives de la session, mesurée en secondes par mètre.
  • elevationGainMillimeters : dénivelé positif total pendant la session.

Tours et intervalles

Pour les entraînements qui impliquent des tours (comme les courses sur piste ou la natation en piscine), utilisez splitSummaries.

Chaque intervalle contient les éléments suivants :

  • Un startTime et un endTime spécifiques.
  • Une activeDuration représentant le temps réel du tour.
  • Un metricsSummary limité à ce segment.
  • Un splitType pour définir les limites de division (par exemple, DISTANCE, DURATION ou MANUAL).

Événements d'exercice

Pour calculer avec précision la durée active, suivez les transitions d'état (comme les événements de pause manuelle ou automatique) à l'aide de exerciseEvents.

Chaque événement contient l'horodatage (eventTime) et le type :

  • START / STOP : indique les horodatages limites du moment où l'utilisateur a explicitement démarré ou arrêté l'enregistrement.
  • PAUSE / RESUME : indique quand la session a été mise en pause ou reprise manuellement.
  • AUTO_PAUSE / AUTO_RESUME : indique les pauses/reprises automatiques déclenchées par le capteur.

Écrire une session d'entraînement

Pour créer, mettre à jour ou importer une session d'entraînement, écrivez un point de données dans la collection de types de données exercise. Utilisez le point de terminaison des points de données create.

Exemple de représentation REST

L'exemple suivant montre comment écrire une session d'entraînement à l'aide d'une méthode POST :

Requête

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
        }
      }
    ]
  }
}

Réponse

{
  "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
          }
        }
      ]
    }
  }
}

Itinéraires GPS et suivi de la position

L'API enregistre les résumés de session de base directement dans le point de données exercise, mais gère l'historique détaillé des positions et les coordonnées de l'itinéraire GPS en tant que flux distinct.

Pour télécharger les données d'itinéraire détaillées d'une session en extérieur, appelez la méthode personnalisée exportExerciseTcx. Ce point de terminaison renvoie l'itinéraire au format Training Center XML (TCX) standard du secteur.

Exporter un itinéraire GPS

Requête

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

Réponse

Une charge utile HTTP avec Content-Type: application/tcx+xml et en-têtes indiquant au navigateur d'enregistrer le fichier.

<?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>

Champs d'application et position requis

Pour lire ou écrire des données pour les itinéraires GPS et le suivi de la position, demandez les champs d'application OAuth suivants dans le jeton d'accès de votre application :

  • Accès en lecture : https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly
  • Accès en écriture : https://www.googleapis.com/auth/googlehealth.activity_and_fitness.writeonly
  • Accès en lecture : https://www.googleapis.com/auth/googlehealth.location.readonly

Si un champ d'application requis est manquant dans les en-têtes d'autorisation, l'API Google Health renvoie une erreur d'autorisation.

Consignes

Lorsque vous intégrez le suivi des entraînements dans votre application, suivez ces consignes de conception et d'implémentation.

Durée active par rapport à la durée totale

Pour calculer les métriques de vitesse ou d'allure, utilisez toujours activeDuration plutôt que la différence entre startTime et endTime. Cela empêche les intervalles de pause de fausser vos métriques.

Par exemple, si un utilisateur commence un entraînement à 8h00 et le termine à 8h35, la durée totale écoulée est de 2 100 secondes. Si l'utilisateur a mis l'entraînement en pause pendant 5 minutes (300 secondes), définissez activeDuration sur "1800s" (2 100 - 300). L'API utilise la durée active pour calculer les moyennes, en divisant la distance totale par 1 800 secondes au lieu de 2 100.

Demander la position tôt

Si votre application mappe les itinéraires d'entraînement, demandez les autorisations de localisation et le champ d'application Google Health location en plus du champ d'application d'activité et de remise en forme. Expliquez aux utilisateurs pourquoi votre application nécessite le champ d'application de localisation lors de l'examen des exercices GPS.

Lorsque votre application demande le champ d'application de localisation (https://www.googleapis.com/auth/googlehealth.location.readonly), Google OAuth affiche une invite de consentement à l'utilisateur. Expliquez à vos utilisateurs que cette autorisation est nécessaire pour afficher les superpositions d'itinéraire et exporter les fichiers de suivi GPS (TCX). Si un utilisateur accorde le champ d'application d'activité, mais refuse l'autorisation d'accéder à la position, exportExerciseTcx renvoie une erreur d'autorisation, mais vous pouvez toujours accéder aux agrégats de session dans metricsSummary.

Synchronisation en temps réel à l'aide de webhooks

Abonnez-vous au type de données exercise pour informer votre backend à l'aide de webhooks lorsque de nouvelles données d'entraînement sont disponibles. Vous pouvez ainsi déclencher des expériences post-entraînement en temps réel.

Lorsque votre serveur reçoit une notification de webhook, il contient le healthUserId et l'intervalle de temps physique spécifique de l'entraînement. Votre serveur doit traiter la notification de manière asynchrone, puis demander le nouveau exercise point de données à partir du /users/me/dataTypes/exercise/dataPoints point de terminaison. Pour en savoir plus sur la configuration des abonnements, consultez Abonnements aux webhooks.

Maintenir des métriques cohérentes

Pour offrir une expérience sportive complète, votre application doit synchroniser les points de données de télémétrie à haute fréquence avec la session exercise globale. Cela garantit que les totaux quotidiens, les tendances historiques et les graphiques détaillés de l'utilisateur restent parfaitement alignés.

Synchroniser la télémétrie et les sessions (chemin d'écriture)

Lorsque vous importez ou écrivez un entraînement terminé dans l'API Google Health, implémentez un modèle d'écriture en plusieurs étapes :

  1. Écrivez la session : enregistrez l'événement récapitulatif en publiant un point de données sur POST /users/me/dataTypes/exercise/dataPoints.
  2. Écrivez des intervalles de séries temporelles : écrivez simultanément les points de données granulaires enregistrés pendant l’entraînement (par exemple, les pas par minute ou les intervalles de calories brûlées) dans leurs collections respectives :
    • POST /users/me/dataTypes/steps/dataPoints
    • POST /users/me/dataTypes/active-energy-burned/dataPoints
    • POST /users/me/dataTypes/heart-rate/dataPoints

Interroger des données détaillées pour les graphiques (chemin de lecture)

Lorsque vous affichez des tableaux de bord d'entraînement historiques ou des graphiques de performances pour une session d'entraînement spécifique, interrogez la télémétrie granulaire à l'aide de la fenêtre temporelle de la session :

  1. Interrogez les résumés de session : appelez /users/me/dataTypes/exercise/dataPoints pour récupérer les détails généraux de l'entraînement et le metricsSummary final.
  2. Récupérez les métriques du graphique : inspectez interval.startTime et interval.endTime de l'entraînement. Effectuez des appels GET secondaires aux collections de télémétrie pour cette fenêtre temporelle spécifique :
    • GET /users/me/dataTypes/heart-rate/dataPoints?startTime=2026-04-20T08:00:00Z&endTime=2026-04-20T08:35:00Z
  3. Récupérez les itinéraires GPS : si les métadonnées de la session indiquent que des données GPS sont présentes (exerciseMetadata.hasGps est true), appelez la méthode d'assistance exportExerciseTcx pour télécharger les coordonnées de l'itinéraire.
Précédent
Calories et énergie