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 d'exercices des utilisateurs à l'aide du type de données de session exercise. Une session sert de conteneur qui regroupe les métadonnées d'activité, les événements de mise en pause et de reprise, les tours ou les temps intermédiaires, ainsi que les métriques récapitulatives.

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

Types de données acceptés

L'API accepte 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 Opérations
disponibles
Champ d'application
Exercice
dataType : exercise
paramètre de filtre : exercise
Type d'enregistrement : Session

Appareils compatibles

list, get, reconcile, create, update, batchDelete .activity_and_fitness.readonly
.activity_and_fitness.writeonly

Bien que les sessions d'entraînement utilisent le type de données exercise comme conteneur, les accessoires connectés enregistrent également des données de télémétrie détaillées et à haute fréquence pendant une session. Dans l'API Google Health, ces types de données de télémétrie intrajournalières précises sont en lecture seule et ne peuvent pas être créés ni modifiés directement via leurs propres points de terminaison REST. Lorsque vous écrivez une séance d'entraînement via l'API REST, transmettez les métriques d'entraînement agrégées dans l'objet metricsSummary du point de données exercise.

Le tableau suivant met en correspondance les champs récapitulatifs de exercise.metricsSummary avec les types de données de télémétrie intrajournalière en lecture seule correspondants que vous pouvez interroger pour la période de cet entraînement :

Champ de résumé (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 (lecture seule) Champ de filtre (?filter=) Champ d'application OAuth en lecture requis
caloriesKcal Énergie active dépensée active-energy-burned active_energy_burned.interval.start_time activity_and_fitness.readonly
distanceMillimeters Distance distance distance.interval.start_time activity_and_fitness.readonly
steps Étapes steps steps.interval.start_time activity_and_fitness.readonly
averageHeartRateBeatsPerMinute Fréquence cardiaque heart-rate heart_rate.sample_time.physical_time health_metrics_and_measurements.readonly
activeZoneMinutes Minutes en zone active active-zone-minutes active_zone_minutes.interval.start_time activity_and_fitness.readonly

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.

Séances d'entraînement

Enregistrez 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 (comme les actions de mise en pause et de reprise) et fournit des métriques récapitulatives (comme la distance globale, le nombre de pas 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 séance d'entraînement. Lorsqu'il est créé via l'API REST, le serveur renseigne le nom à afficher localisé pour exerciseType, par exemple "Run" pour RUNNING.
  • Durée d'activité (activeDuration) : durée d'activité réelle de l'entraînement, à l'exclusion des intervalles de pause. La mise en forme standard utilise le format Duration (par exemple, "1800s"). Sur le serveur, activeDuration est calculé à partir de la session interval moins les intervalles PAUSE/RESUME ou AUTO_PAUSE/AUTO_RESUME dans exerciseEvents.

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 précision élevée 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 moyenne de déplacement 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 temps intermédiaires

Pour les entraînements impliquant des tours (comme la course sur piste ou la natation en piscine) synchronisés à partir d'appareils compatibles, splitSummaries segmente la session par tour ou par temps de passage.

Chaque division contient :

  • Un startTime et un endTime spécifiques.
  • Un activeDuration représentant le temps au tour réel.
  • 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 précisément la durée active, suivez les transitions d'état (comme les événements de pause manuels ou automatiques) à l'aide de exerciseEvents.

Chaque événement contient le code temporel (eventTime) et le type :

  • START / STOP : indique les codes temporels de début et de fin de l'enregistrement explicite par l'utilisateur.
  • PAUSE / RESUME : indique quand la session a été mise en pause ou reprise manuellement.
  • AUTO_PAUSE/AUTO_RESUME : indique les mises en pause/reprises automatiques basées sur les capteurs.

Écrire une séance d'entraînement

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

Exemple de représentation REST

L'exemple suivant montre comment écrire une séance 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",
    "platform": "GOOGLE_WEB_API"
  },
  "exercise": {
    "interval": {
      "startTime": "2026-04-20T08:00:00Z",
      "startUtcOffset": "0s",
      "endTime": "2026-04-20T08:35:00Z",
      "endUtcOffset": "0s"
    },
    "exerciseType": "RUNNING",
    "activeDuration": "1800s",
    "metricsSummary": {
      "caloriesKcal": 380.0,
      "distanceMillimeters": 5000000.0,
      "steps": "6200",
      "averageHeartRateBeatsPerMinute": "148",
      "averagePaceSecondsPerMeter": 0.36
    },
    "exerciseEvents": [
      {
        "eventTime": "2026-04-20T08:15:00Z",
        "eventUtcOffset": "0s",
        "exerciseEventType": "PAUSE"
      },
      {
        "eventTime": "2026-04-20T08:20:00Z",
        "eventUtcOffset": "0s",
        "exerciseEventType": "RESUME"
      }
    ]
  }
}

Réponse

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4.DataPoint",
    "name": "users/999298779973222220/dataTypes/exercise/dataPoints/3054085373369111216",
    "dataSource": {
      "recordingMethod": "ACTIVELY_MEASURED",
      "application": {
        "googleWebClientId": "438076457939-example.apps.googleusercontent.com"
      },
      "platform": "GOOGLE_WEB_API"
    },
    "exercise": {
      "interval": {
        "startTime": "2026-04-20T08:00:00Z",
        "startUtcOffset": "0s",
        "endTime": "2026-04-20T08:35:00Z",
        "endUtcOffset": "0s"
      },
      "exerciseType": "RUNNING",
      "metricsSummary": {
        "caloriesKcal": 380,
        "distanceMillimeters": 5000000,
        "steps": "6200",
        "averagePaceSecondsPerMeter": 0.36,
        "averageHeartRateBeatsPerMinute": "148"
      },
      "exerciseMetadata": {},
      "displayName": "Run",
      "activeDuration": "1800s",
      "exerciseEvents": [
        {
          "eventTime": "2026-04-20T08:15:00Z",
          "eventUtcOffset": "0s",
          "exerciseEventType": "PAUSE"
        },
        {
          "eventTime": "2026-04-20T08:20:00Z",
          "eventUtcOffset": "0s",
          "exerciseEventType": "RESUME"
        }
      ],
      "updateTime": "2026-04-20T08:35:10.123456Z",
      "createTime": "2026-04-20T08:35:10.123456Z"
    }
  }
}

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 d'itinéraire GPS sous la forme d'un 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), qui est la norme du secteur.

Exporter l'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 des en-têtes demandant 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 emplacement requis

Pour utiliser la fonctionnalité de suivi des itinéraires et de la position GPS, votre application doit demander les champs d'application OAuth suivants :

  • À lire : https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly
  • Écriture : https://www.googleapis.com/auth/googlehealth.activity_and_fitness.writeonly
  • À lire : https://www.googleapis.com/auth/googlehealth.location.readonly

Consignes

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

Durée active et 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 évite que les intervalles de pause ne faussent vos métriques.

Par exemple, si un utilisateur commence un entraînement à 8h00 et le termine à 8h35, la durée totale écoulée de l'entraînement est de 2 100 secondes. Si l'utilisateur a mis l'entraînement en pause pendant cinq minutes (300 secondes) et que vous incluez les événements PAUSE et RESUME dans exerciseEvents, la durée active est de "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.

Calcul de la vitesse et de l'allure

L'API Google Health utilise des formules standards pour calculer la vitesse et l'allure :

  • Vitesse = distance / time(hour)
  • Allure = time(seconds) / distance

L'en-tête Accept-Language spécifié dans la requête détermine l'unité de distance.

Demander la position de manière anticipée

Si votre application cartographie les itinéraires d'entraînement, demandez les autorisations d'accéder à la position 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 la position lorsqu'ils examinent des exercices GPS.

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

Synchroniser à l'aide de webhooks

Abonnez-vous au type de données exercise pour avertir votre backend à l'aide de webhooks lorsque de nouvelles données d'entraînement sont disponibles. Cela vous permet de déclencher automatiquement des expériences post-entraînement.

Lorsque votre serveur reçoit une notification de webhook, celle-ci contient l'healthUserId et l'intervalle de temps civil (civilIso8601TimeInterval) de l'entraînement mis à jour. Votre serveur doit accuser réception de la notification immédiatement avec 204 No Content, traiter la charge utile de manière asynchrone et interroger le point de terminaison exercise rapproché à l'aide d'un filtre exercise.interval.civil_start_time (notez que exercise n'est compatible qu'avec le filtrage par civil_start_time) :

GET https://health.googleapis.com/v4/users/healthUserId/dataTypes/exercise/dataPoints:reconcile?filter=exercise.interval.civil_start_time >= "2026-04-20T08:00:00" AND exercise.interval.civil_start_time < "2026-04-20T10:00:00"

Pour en savoir plus sur la configuration des abonnements, consultez Abonnements aux webhooks.

Maintenir des métriques cohérentes

Pour offrir une expérience d'entraînement complète, incluez des métriques récapitulatives lors de l'écriture de sessions exercise et interrogez les points de terminaison de télémétrie en lecture seule à l'aide de filtres de période lors de l'affichage des graphiques détaillés.

Écrire les métriques récapitulatives de l'entraînement (chemin d'écriture)

Lorsque vous importez ou écrivez un entraînement terminé dans l'API Google Health, incluez les métriques de télémétrie agrégées de l'entraînement (steps, caloriesKcal, distanceMillimeters, averageHeartRateBeatsPerMinute et averagePaceSecondsPerMeter) dans l'objet metricsSummary du point de données exercise :

  • POST https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints

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

Pour créer des tableaux de bord ou des graphiques d'entraînement pour une session spécifique, interrogez les points de terminaison de télémétrie rapprochés pour la période de cet entraînement :

  1. Récupérez la session d'entraînement à partir du point de terminaison exercise à l'aide d'un filtre civil_start_time pour obtenir ses interval et metricsSummary :

    GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints:reconcile?filter=exercise.interval.civil_start_time >= "2026-04-20T00:00:00" AND exercise.interval.civil_start_time < "2026-04-21T00:00:00"
  2. Utilisez les valeurs interval.startTime et interval.endTime de la session pour interroger les points de terminaison de télémétrie pour cette période physique.

  3. Si exerciseMetadata.hasGps est défini sur true, appelez exportExerciseTcx pour télécharger les coordonnées de l'itinéraire.