Endpoints

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).