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é :
| Type de données | Opérations disponibles |
Champ d'application |
|---|---|---|
|
Exercice
dataType :
exerciseparamètre de filtre : exercise
Type d'enregistrement : Session
Appareils compatibles
|
list, get, reconcile, create, update, batchDelete | .activity_and_fitness.readonly.activity_and_fitness.writeonly |
Types de données de télémétrie associés
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,BIKINGouAEROBIC_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é pourexerciseType, par exemple"Run"pourRUNNING. - 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 formatDuration(par exemple,"1800s"). Sur le serveur,activeDurationest calculé à partir de la sessionintervalmoins les intervallesPAUSE/RESUMEouAUTO_PAUSE/AUTO_RESUMEdansexerciseEvents.
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
startTimeet unendTimespécifiques. - Un
activeDurationreprésentant le temps au tour réel. - Un
metricsSummarylimité à ce segment. - Un
splitTypepour définir les limites de division (par exemple,DISTANCE,DURATIONouMANUAL).
É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 :
Récupérez la session d'entraînement à partir du point de terminaison
exerciseà l'aide d'un filtrecivil_start_timepour obtenir sesintervaletmetricsSummary: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"
Utilisez les valeurs
interval.startTimeetinterval.endTimede la session pour interroger les points de terminaison de télémétrie pour cette période physique.Si
exerciseMetadata.hasGpsest défini surtrue, appelezexportExerciseTcxpour télécharger les coordonnées de l'itinéraire.