Cette page présente les conventions de l'API REST, ainsi qu'un index des tâches courantes de l'API Google Health et des exemples pour chacune d'elles.
Conventions de l'API REST
L'API Google Health suit les normes des propositions d'amélioration de l'API Google (AIP), en particulier AIP-127 (transcodage HTTP et gRPC) et AIP-131 à AIP-135 (méthodes standards). Ces normes définissent comment les données sont mappées d'un message proto à une requête HTTP.
Paramètres de requête
Les paramètres de requête sont utilisés lorsque les données font partie de l'URL. Cela concerne principalement les requêtes GET (récupération d'une ressource) ou LIST (filtrage/pagination), mais également les opérations DELETE.
- Emplacement : ajouté à l'URL après un
?. - Syntaxe : paires clé-valeur séparées par
&. - Mappage : chaque champ du message de requête qui ne fait pas partie du modèle de chemin d'URL est mappé sur un paramètre de requête.
- Idéal pour : les types simples (chaînes, entiers, énumérations) et les champs répétés.
Exemple de syntaxe :
GET https://health.googleapis.com/v4/users/me/dataTypes/data-type/dataPoints?page_size=10&filter=data_type.interval.start_time >= "2025-10-01T00:00:00Z"
Corps de la requête
Le corps de la requête est utilisé lorsque les données modifient l'état d'une ressource ou sont trop volumineuses pour une URL. Le corps est généralement une représentation JSON de la ressource elle-même. Il est généralement utilisé pour les opérations POST, PATCH et PUT.
- Emplacement : dans la charge utile HTTP (non visible dans l'URL).
- Syntaxe : formatée en tant qu'objet JSON.
- Mappage : défini dans l'annotation
google.api.http.body: "*"signifie que l'intégralité du message est le corps.body: "resource_name"signifie que seul un champ spécifique du proto est le corps.
- Idéal pour : les objets complexes, les messages imbriqués et les données sensibles.
Exemple de syntaxe :
POST https://health.googleapis.com/v4/users/me/dataTypes/data-type/dataPoints:rollUp
Content-Type: application/json
{
"range": {
"startTime": "2025-11-05T00:00:00Z",
"endTime": "2025-11-13T00:00:00Z"
},
"windowSize": "3600s"
}Cas hybride
Dans une méthode Update conforme à AIP-134 ou une opération PATCH, les deux sont utilisés.
L'URL contient le nom de la ressource, le corps contient les données de la ressource mises à jour, et un paramètre de requête (généralement update_mask) spécifie les champs à modifier.
PATCH https://health.googleapis.com/v4/projects/project-id/subscribers/subscriber-id
Content-Type: application/json
{
"endpointUri": "https://myapp.com/new-webhooks/health"
}
Aperçu des principales différences
| Fonctionnalité | Paramètres de requête | Corps de la requête |
|---|---|---|
| Conseils AIP | Utilisé pour les opérations de recherche, de filtrage et de lecture. | Utilisé pour les opérations d'écriture. |
| Visibilité | Visible dans l'historique du navigateur et les journaux du serveur. | Masqué dans l'URL. |
| Complexité | Limité aux structures plates ou répétées. | Compatible avec les objets JSON profondément imbriqués. |
| Encodage | Doit être encodé au format URL (par exemple, les espaces deviennent %20). |
Encodage JSON standard. |
Dates
Toutes les dates de l'API Google Health sont affichées au format YYYY-MM-DD. L'API Nutrition est compatible avec la norme ISO-8601 pour les valeurs de date, avec les conditions suivantes :
- Année à quatre chiffres
YYYY - Valeurs d'année comprises entre 0000 et 9999
- Aucune application des restrictions de date de début impliquées par la norme ISO-8601 ou une autre époque
En-têtes
L'exécution des points de terminaison de l'API Google Health nécessite l'utilisation des en-têtes et du jeton d'accès appropriés. L'en-tête suivant est recommandé pour les requêtes GET et POST :
Authorization: Bearer access-token Accept: application/json
Index des tâches de l'API
Cette section fournit un index des tâches courantes de l'API Google Health et des exemples pour chacune d'elles.
Obtenir l'ID utilisateur Fitbit ou Google
Une fois qu'un utilisateur a donné son consentement via Google OAuth 2.0, la réponse du jeton ne contient pas l'ID utilisateur Fitbit ou Google. Pour obtenir l'ID utilisateur, appelez le
getIdentity point de terminaison. getIdentity
renvoie à la fois l'ancien ID utilisateur Fitbit et l'ID utilisateur Google.
Nous vous recommandons d'appeler le point de terminaison getIdentity et de stocker les deux ID utilisateur dès qu'un nouvel utilisateur donne son consentement via OAuth. Cela assure la compatibilité ascendante et descendante de votre intégration.
Exemple :
Requête
GET https://health.googleapis.com/v4/users/me/identity Authorization: Bearer access-token Accept: application/json
Réponse
{
"name": "users/me/identity",
"legacyUserId": "A1B2C3",
"healthUserId": "111111256096816351"
}Obtenir des données intrajournalières ou détaillées collectées tout au long d'une journée
Utilisez le list
point de terminaison pour un type de données spécifique afin d'obtenir des données intrajournalières ou détaillées collectées tout au long de la journée dans les
intervalles compatibles pour ce type de données.
Exemple :
Requête
GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints Authorization: Bearer access-token Accept: application/json
Réponse
{
"dataPoints": [
{
"dataSource": {
"recordingMethod": "PASSIVELY_MEASURED",
"device": {
"manufacturer": "",
"displayName": "Charge 6"
},
"platform": "FITBIT"
},
"steps": {
"interval": {
"startTime": "2026-03-04T07:05:00Z",
"startUtcOffset": "0s",
"endTime": "2026-03-04T07:06:00Z",
"endUtcOffset": "0s",
"civilStartTime": {
"date": {
"year": 2026,
"month": 3,
"day": 4
},
"time": {
"hours": 7,
"minutes": 5
}
},
"civilEndTime": {
"date": {
"year": 2026,
"month": 3,
"day": 4
},
"time": {
"hours": 7,
"minutes": 6
}
}
},
"count": "40"
}
},
...
],
"nextPageToken": "Xm5h-6L0viZxIlRuWjx5bmvy98zj85uG34tuMn16mu2pntsnZI32iqhq"
}Filtrer les données par heure de début civile d'un intervalle
Utilisez le point de terminaison list avec un paramètre filter pour filtrer les données par heure civile ou par intervalle.
Exemple :
Requête
GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints?filter=steps.interval.civil_start_time >= "2026-03-04T00:00:00" Authorization: Bearer access-token Accept: application/json
Réponse
{
"dataPoints": [
{
"dataSource": {
"recordingMethod": "PASSIVELY_MEASURED",
"device": {
"manufacturer": "",
"displayName": "Charge 6"
},
"platform": "FITBIT"
},
"steps": {
"interval": {
"startTime": "2026-03-04T07:05:00Z",
"startUtcOffset": "0s",
"endTime": "2026-03-04T07:06:00Z",
"endUtcOffset": "0s",
"civilStartTime": {
"date": {
"year": 2026,
"month": 3,
"day": 4
},
"time": {
"hours": 7,
"minutes": 5
}
},
"civilEndTime": {
"date": {
"year": 2026,
"month": 3,
"day": 4
},
"time": {
"hours": 7,
"minutes": 6
}
}
},
"count": "40"
}
...
],
"nextPageToken": "Xm5h-6L0viZxIlRuQjp5bml1bZ4ve2dhNmZvMnt4Yn7qIGQhbHN3YQ"
}Filtrer les données par heure physique d'une observation d'échantillon
Utilisez le point de terminaison list avec un paramètre filter pour filtrer les données par heure physique d'une observation d'échantillon.
Exemple :
Requête
GET https://health.googleapis.com/v4/users/me/dataTypes/body-fat/dataPoints?filter=body_fat.sample_time.physical_time >= "2026-03-01T00:00:00Z" Authorization: Bearer access-token Accept: application/json
Réponse
{
"dataPoints": [
{
"name": "users/2515055256096816351/dataTypes/body-fat/dataPoints/1234567890",
"dataSource": {
"recordingMethod": "UNKNOWN",
"application": {
"packageName": "",
"webClientId": "",
"googleWebClientId": "google-web-client-id"
},
"platform": "GOOGLE_WEB_API"
},
"-->bodyFat<--": {
"sampleTime": {
"physicalTime": "2026-03-10T10:00:00Z",
"utcOffset": "0s",
"civilTime": {
"date": {
"year": 2026,
"month": 3,
"day": 10
},
"time": {
"hours": 10
}
}
},
"percentage": 20
}
}
"nextPageToken": ""
}Filtrer les données par sources de données telles que les objets connectés
Utilisez le reconcile
point de terminaison pour obtenir
des données pour une "famille de sources de données" spécifique. Pour ce faire, spécifiez le paramètre dataSourceFamily en tant que paramètre de requête.
Le tableau suivant décrit les options dataSourceFamily compatibles :
| Option | Description |
|---|---|
users/me/dataSourceFamilies/all-sources |
Valeur par défaut. Inclut les données de toutes les sources de données disponibles. |
users/me/dataSourceFamilies/google-wearables |
Inclut les données des appareils de suivi Google et Fitbit (tels que les bracelets d'activité Fitbit et la Pixel Watch). Exclut les données enregistrées manuellement. |
users/me/dataSourceFamilies/google-sources |
Inclut les données Google first party, telles que les données des appareils de suivi et les données enregistrées manuellement. |
Voici un exemple de filtrage du sommeil enregistré par le bracelet d'activité pour le lendemain du 3 mars 2026 :
Requête
GET https://health.googleapis.com/v4/users/me/dataTypes/sleep/dataPoints:reconcile?dataSourceFamily=users/me/dataSourceFamilies/google-wearables&filter=sleep.interval.civil_end_time >= "2026-03-03" Authorization: Bearer access-token Accept: application/json
Réponse
{
"dataPoints": [
{
"name": "users/2515055256096816351/dataTypes/sleep/dataPoints/2724123844716220216",
"dataSource": {
"recordingMethod": "DERIVED",
"device": {
"displayName": "Charge 6"
},
"platform": "FITBIT"
},
"sleep": {
"interval": {
"startTime": "2026-03-03T20:57:30Z",
"startUtcOffset": "0s",
"endTime": "2026-03-04T04:41:30Z",
"endUtcOffset": "0s"
},
"type": "STAGES",
"stages": [
{
"startTime": "2026-03-03T20:57:30Z",
"startUtcOffset": "0s",
"endTime": "2026-03-03T20:59:30Z",
"endUtcOffset": "0s",
"type": "AWAKE",
"createTime": "2026-03-04T04:43:40.937183Z",
"updateTime": "2026-03-04T04:43:40.937183Z"
},
…
{
"startTime": "2026-03-04T04:07:30Z",
"startUtcOffset": "0s",
"endTime": "2026-03-04T04:41:30Z",
"endUtcOffset": "0s",
"type": "AWAKE",
"createTime": "2026-03-04T04:43:40.937183Z",
"updateTime": "2026-03-04T04:43:40.937183Z"
}
],
"metadata": {
"stagesStatus": "SUCCEEDED",
"processed": true,
"main": true
},
"summary": {
"minutesInSleepPeriod": "464",
"minutesAfterWakeUp": "0",
"minutesToFallAsleep": "0",
"minutesAsleep": "407",
"minutesAwake": "57",
"stagesSummary": [
{
"type": "AWAKE",
"minutes": "56",
"count": "12"
},
{
"type": "LIGHT",
"minutes": "198",
"count": "19"
},
{
"type": "DEEP",
"minutes": "114",
"count": "10"
},
{
"type": "REM",
"minutes": "94",
"count": "4"
}
]
},
"createTime": "2026-03-04T04:43:40.337983Z",
"updateTime": "2026-03-04T04:43:40.937183Z"
}
}
],
"nextPageToken": ""
}Agréger des points de données sur une période donnée
Utilisez le rollUp
point de terminaison pour renvoyer l'
agrégation des points de données en fonction d'une fenêtre en secondes, sur la plage datetime
en fonction de l'heure physique des utilisateurs (en UTC).
Lorsque vous appelez le point de terminaison rollUp, vous devez fournir le corps de la requête représentant la période requise à l'heure civile de l'utilisateur. Exemple :
Requête
POST https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints:rollUp
Authorization: Bearer access-token
Accept: application/json
{
"range": {
"startTime": "2026-02-17T17:00:00Z",
"endTime": "2026-02-17T17:59:59Z"
},
"windowSize": "30s"
}Réponse
{
"rollupDataPoints": [
{
"startTime": "2026-02-17T17:55:00Z",
"endTime": "2026-02-17T17:55:30Z",
"steps": {
"countSum": "41"
}
},
{
"startTime": "2026-02-17T17:54:00Z",
"endTime": "2026-02-17T17:54:30Z",
"steps": {
"countSum": "31"
}
},
...
]
}Agréger des données sur une ou plusieurs journées
Le dailyRollUp
point de terminaison doit être
utilisé lorsque vous souhaitez agréger des données sur
une ou plusieurs journées, appelées windowSize. Fournissez la plage d'heures civiles fermée-ouverte pour l'intervalle requis dans le corps de la requête. Selon le type de données, vous recevrez la somme ou la moyenne sur l'intervalle.
Exemple :
Requête
POST https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints:dailyRollUp
Authorization: Bearer access-token
Accept: application/json
{
"range": {
"start": {
"date": {
"year": 2026,
"month": 2,
"day": 26
},
"time": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"nanos": 0
}
},
"end": {
"date": {
"year": 2026,
"month": 2,
"day": 26
},
"time": {
"hours": 23,
"minutes": 59,
"seconds": 59,
"nanos": 0
}
}
},
"windowSizeDays": 1
}Réponse
{
"rollupDataPoints": [
{
"civilStartTime": {
"date": {
"year": 2026,
"month": 2,
"day": 26
},
"time": {}
},
"civilEndTime": {
"date": {
"year": 2026,
"month": 2,
"day": 26
},
"time": {
"hours": 23,
"minutes": 59,
"seconds": 59
}
},
"steps": {
"countSum": "3822"
}
}
]
}Insérer ou mettre à jour les données de santé d'un utilisateur
Utilisez le patch
point de terminaison pour insérer ou
mettre à jour les données de l'application Fitbit d'un utilisateur.
Voici un exemple où un utilisateur a enregistré sa masse graisseuse sur une balance appelée "HumanScale" de la société "Scales R Us". La nouvelle mesure de masse graisseuse de l'utilisateur est de 20% pour le 10 mars 2026.
Requête
PATCH https://health.googleapis.com/v4/users/me/dataTypes/body-fat/dataPoints/1234567890
Authorization: Bearer access-token
content-length: 329
{
"name": "bodyFatName",
"dataSource": {
"recordingMethod": "ACTIVELY_MEASURED",
"device": {
"formFactor": "SCALE",
"manufacturer": "Scales R Us",
"displayName": "HumanScale"
}
},
"bodyFat": {
"sampleTime": {
"physicalTime": "2026-03-10T10:00:00Z"
},
"percentage": 20
}
}Réponse
{
"done": true,
"response": {
"@type": "type.googleapis.com/google.devicesandservices.health.v4main.DataPoint",
"name": "users/2515055256096816351/dataTypes/body-fat/dataPoints/1234567890",
"dataSource": {
"recordingMethod": "ACTIVELY_MEASURED",
"device": {
"formFactor": "SCALE",
"manufacturer": "Scales R Us",
"displayName": "HumanScale"
},
"application": {
"googleWebClientId": "618308034039.apps.googleusercontent.com"
},
"platform": "GOOGLE_WEB_API"
},
"bodyFat": {
"sampleTime": {
"physicalTime": "2026-03-10T10:00:00Z"
},
"percentage": 20
}
}
}Enregistrer un aliment
Pour enregistrer un aliment, envoyez une requête POST au point de terminaison des points de données nutrition-log. Le corps de la requête contient un DataPoint avec un objet nutritionLog.
Pour en savoir plus, consultez le guide Nutrition.
Exemple :
Requête
POST https://health.googleapis.com/v4/users/me/dataTypes/nutrition-log/dataPoints
Authorization: Bearer access-token
Content-Type: application/json
{
"nutritionLog": {
"interval": {
"startTime": "2026-06-16T12:00:00Z",
"endTime": "2026-06-16T12:30:00Z"
},
"foodDisplayName": "Banana",
"mealType": "LUNCH",
"energy": {
"kcal": 105
},
"totalCarbohydrate": {
"grams": 27
},
"totalFat": {
"grams": 0.3
}
}
}Réponse
{
"done": true,
"response": {
"@type": "type.googleapis.com/google.devicesandservices.health.v4.DataPoint",
"name": "users/2515055256096816351/dataTypes/nutrition-log/dataPoints/567890",
"dataSource": {
"recordingMethod": "ACTIVELY_MEASURED",
"platform": "GOOGLE_WEB_API"
},
"nutritionLog": {
"interval": {
"startTime": "2026-06-16T12:00:00Z",
"startUtcOffset": "0s",
"endTime": "2026-06-16T12:30:00Z",
"endUtcOffset": "0s"
},
"energy": {
"kcal": 105
},
"totalCarbohydrate": {
"grams": 27
},
"totalFat": {
"grams": 0.3
},
"mealType": "LUNCH",
"foodDisplayName": "Banana"
}
}
}Supprimer les données de santé de l'utilisateur
Utilisez le batchDelete
point de terminaison pour supprimer
un tableau de données de l'application Fitbit d'un utilisateur.
Voici un exemple où un utilisateur a précédemment enregistré sa masse graisseuse sur une balance, mais souhaite supprimer l'enregistrement. Utilisation du user-id et data-point-id de l'action d'insertion d'origine :
Requête
POST https://health.googleapis.com/v4/users/me/dataTypes/body-fat/dataPoints:batchDelete
Authorization: Bearer access-token
Accept: application/json
content-length: 93
{
"names": [
"users/2515055256096816351/dataTypes/body-fat/dataPoints/1234567890"
]
}Réponse
{
"done": true,
"response": {
"@type": "type.googleapis.com/google.devicesandservices.health.v4main.BatchDeleteDataPointsResponse"
}
}Trouver des informations sur l'appareil
Utilisez le point de terminaison list pour
récupérer la liste des appareils associés au compte d'un utilisateur. Cela inclut les informations sur le modèle de l'appareil (deviceVersion) et la dernière fois qu'il a été synchronisé avec l'application mobile Google Health (lastSyncTime).
Les informations de configuration et de synchronisation de la liste sont utiles pour résoudre les problèmes de synchronisation ou récupérer les données historiques depuis la dernière synchronisation.
Exemple :
Requête
GET https://health.googleapis.com/v4/users/me/pairedDevices Authorization: Bearer access-token Accept: application/json
Réponse
{
"pairedDevices": [
{
"name": "users/me/pairedDevices/123456",
"deviceType": "TRACKER",
"batteryStatus": "High",
"batteryLevel": 88,
"lastSyncTime": "2026-03-04T07:05:00Z",
"deviceVersion": "Charge 6",
"macAddress": "00:11:22:33:44:55",
"features": [
"STEPS",
"HEART_RATE"
]
}
]
}Interroger les données historiques
L'un des principaux avantages de l'API Google Health est la possibilité de suivre les performances d'un utilisateur et de surveiller ses constantes sur de longues périodes. Vous pouvez interroger les données d'un utilisateur aussi loin que possible dans le passé. L'API n'impose aucune limite ni restriction sur la quantité de données historiques que votre application peut consommer.
Toutefois, l'interrogation des données historiques est toujours régie par les limites de débit standards standards. Pour réduire le nombre d'appels d'API par rapport à ces limites, l'API Google Health permet d'interroger les données sur une période donnée. Notez les limites de pagination et de requête suivantes :
- Chaque point de terminaison renvoie une taille de page maximale de 10 000 points de données par page.
- Les périodes de requête sont limitées à 14 à 90 jours par requête.
Selon le volume de données historiques dont votre application a besoin, la récupération de l'ensemble de l'ensemble de données peut nécessiter plusieurs requêtes séquentielles et prendre plus de temps. Tenez-en compte lors de la conception du processus de synchronisation des données de votre application.
Pour garantir des performances optimales et éviter les erreurs d'API, suivez ces consignes lorsque vous interrogez des données historiques :
Synchronisation des données par phases (chargement à chaud ou à froid)
- Chargement "à chaud" initial : récupérez et affichez uniquement les 7 à 14 jours de données les plus récents lors de la séquence de chargement principale. Les utilisateurs voient ainsi les données immédiatement sans avoir à attendre des requêtes de longue durée.
- Chargement "à froid" en arrière-plan : déléguez la récupération des données historiques plus anciennes à une file d'attente asynchrone de priorité inférieure ou à un processus en arrière-plan une fois l'interface utilisateur principale affichée.
Découpage des requêtes en fonction du temps
- Ne demandez pas de périodes de plusieurs années ou de plusieurs mois dans un seul appel d'API. Divisez les grandes requêtes historiques en intervalles séquentiels plus petits (par exemple, une semaine par requête).
- Regroupez ou séquencez ces sous-requêtes en toute sécurité pour respecter les limites de simultanéité et maintenir des indicateurs de progression de l'interface utilisateur constants.
Utiliser des cumuls pré-agrégés
Restructurez les tableaux de bord de présentation et les graphiques de tendances pour utiliser des points de terminaison récapitulatifs pré-agrégés (tels que DailyRollUpDataPoints). Cela réduira considérablement la surcharge de calcul sur le backend et le temps de transfert réseau vers le client.
Gestion des exceptions résiliente (nouvelles tentatives intelligentes)
- Implémentez une gestion stricte des intervalles exponentiels entre les tentatives lorsque vous rencontrez des limites de débit (
429 Too Many Requests) et des délais d'expiration de la passerelle du serveur (504 Gateway Timeout). N'effectuez jamais de nouvelle tentative immédiatement pour les charges utiles volumineuses ayant échoué immédiatement. Les nouvelles tentatives instantanées multiplient la congestion du backend et aggravent la dégradation du système. - Si une requête expire de manière répétée, revenez automatiquement à une fenêtre temporelle plus petite (par exemple, réduisez un bloc d'une semaine à trois jours).