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. Ils sont principalement destinés aux requêtes GET (récupération d'une ressource) ou LIST (filtrage/pagination), mais sont également utilisés pour 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

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 :

GET https://health.googleapis.com/v4/users/me/identity
Authorization: Bearer access-token
Accept: application/json

{
  "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 :

GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints
Authorization: Bearer access-token
Accept: application/json

{
  "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 :

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

{
  "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'observation d'échantillon.

Exemple :

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

{
  "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 :

Voici un exemple de filtrage du sommeil enregistré par le bracelet d'activité uniquement pour le lendemain du 03/03/2026 :

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

{
  "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 basée sur 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 plage de dates requise à l'heure civile de l'utilisateur. Exemple :

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

{
  "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 :

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
}

{
  "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/03/2026.

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

{
  "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 dataPoints nutrition-log. Le corps de la requête contient un DataPoint avec un objet nutritionLog. Pour en savoir plus, consultez le guide Nutrition.

Exemple :

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

{
  "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é d'un utilisateur

Utilisez la batchDelete méthode 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 :

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

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

La configuration de la liste et les informations de synchronisation sont utiles pour résoudre les problèmes de synchronisation ou récupérer des données historiques depuis la dernière synchronisation.

Exemple :

GET https://health.googleapis.com/v4/users/me/pairedDevices
Authorization: Bearer access-token
Accept: application/json

{
  "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 gérer la stabilité du système et éviter les charges utiles excessives, l'API Google Health utilise la pagination automatique avec des tailles de page spécifiques aux points de terminaison. Notez les limites et le comportement suivants :

• Pagination automatique : si vous interrogez une longue période de données, l' API ne renvoie que la première page de résultats jusqu'à la limite de taille de page pour ce point de terminaison, ainsi qu'un nextPageToken. Vous devez utiliser le nextPageToken pour demander les pages suivantes.
• Tailles de page variables : les limites de plafonnement dépendent du point de terminaison et du type de données. Pour la plupart des types de données, la taille des pages est limitée à 10 000. Toutefois, pour certains types de données tels que exercise et sleep, la taille de page par défaut et maximale est limitée à 25. Par exemple, si un client demande toutes les données de sommeil des 10 dernières années, l'API ne renvoie que 25 sessions de sommeil sur la première page.
• Restrictions sur la plage de dates de cumul : pour les points de terminaison de cumul et d'agrégation de données (tels que rollUp et dailyRollUp), les plages de dates de requête sont limitées en fonction du type de données :
  • Plage maximale de 14 jours pour calories-in-heart-rate-zone, heart-rate, active-minutes et total-calories.
  • Plage maximale de 90 jours pour tous les autres types de données de cumul.

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 nécessitera une pagination séquentielle. Gardez cela à l'esprit lorsque vous concevez le 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 progressive des données (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 pour l'agrégation

• Étant donné que les points de terminaison de cumul et de cumul quotidien appliquent une limite de plage de dates maximale (14 ou 90 jours selon le type de données), vous devez diviser les requêtes d'agrégation historiques volumineuses en intervalles séquentiels plus petits dans ces limites.
• 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 de l'intervalle exponentiel entre les tentatives lorsque vous rencontrez des limites de débit (429 Too Many Requests) et des délais d'attente de la passerelle du serveur (504 Gateway Timeout). N'effectuez jamais de nouvelle tentative immédiate pour les charges utiles volumineuses ayant échoué. Les nouvelles tentatives instantanées multiplient la congestion du backend et aggravent la dégradation du système.