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 des API Google (AIP), en particulier les AIP-127 (transcodage HTTP et gRPC) et AIP-131 à AIP-135 (méthodes standards). Ces normes définissent la façon dont 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. Il s'agit principalement de requêtes GET (récupération d'une ressource) ou LIST (filtrage/pagination), mais il est également utilisé 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é à un paramètre de requête.
  • Recommandé 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. Généralement utilisé pour les opérations POST, PATCH et PUT.

  • Emplacement : dans la charge utile HTTP (non visible dans l'URL).
  • Syntaxe : mise en forme en tant qu'objet JSON.
  • Mappage : défini dans l'annotation google.api.http.
    • body: "*" signifie que l'intégralité du message correspond au corps.
    • body: "resource_name" signifie que seul un champ spécifique du fichier .proto constitue 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 ou une opération PATCH conforme à l'AIP-134, 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"
}

Principales différences en un coup d'œil

Fonctionnalité Paramètres de requête Corps de la requête
Conseils sur l'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

Pour exécuter les points de terminaison de l'API Google Health, vous devez utiliser les en-têtes et le 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 ni Google. Pour obtenir l'ID utilisateur, appelez le point de terminaison getIdentity. 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 point de terminaison list 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

Pour récupérer des sous-ensembles spécifiques d'enregistrements de points de données correspondant à des critères tels qu'un intervalle de temps, une date ou une heure d'observation, utilisez le point de terminaison list ou reconcile avec un paramètre filter.

Pour obtenir des consignes détaillées, des règles de mise en forme, des erreurs de validation et des exemples de requêtes, consultez le guide sur le filtrage des données.

Filtrer par famille de sources de données

Pour isoler ou agréger les données de types de sources spécifiques (par exemple, les appareils portables physiques par rapport aux saisies manuelles), utilisez le paramètre dataSourceFamily.

Pour obtenir des consignes détaillées, des informations sur les familles compatibles, ainsi que des exemples de requêtes et de réponses pour reconcile, rollUp et dailyRollUp, consultez Filtrer par famille de sources de données dans le guide "Filtrer les données".

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'observation de l'é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/123456789/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 et agréger par famille de sources de données

Une famille de sources de données est un regroupement logique de sources de données (comme les montres connectées, les applications mobiles ou les saisies manuelles). Il vous permet d'isoler ou d'agréger les données de types de sources spécifiques (par exemple, les appareils portables physiques par rapport aux saisies manuelles).

Les points de terminaison reconcile, rollUp et dailyRollUp sont tous compatibles avec le paramètre dataSourceFamily. Le mécanisme de transmission dépend du point de terminaison :

Point de terminaison (méthode HTTP) Mécanisme
reconcile (GET) Transmettez dataSourceFamily en tant que paramètre de requête d'URL.
rollUp (POST) Transmettez dataSourceFamily en tant que champ dans le corps de la requête JSON.
dailyRollUp (POST) Transmettez dataSourceFamily en tant que champ dans le corps de la requête JSON.

Familles de sources de données compatibles

Le tableau suivant décrit les valeurs dataSourceFamily acceptées :

Option Description
users/me/dataSourceFamilies/all-sources Valeur par défaut  Renvoie des points de données réconciliés pour toutes les sources de données first party (1P) et tierces (3P) enregistrées. Les données d'applications tierces seront renvoyées avec cette option (par exemple, les pas enregistrés par une montre connectée, une application tierce et un téléphone mobile, ainsi que les pas ajoutés manuellement).
users/me/dataSourceFamilies/google-wearables Inclut les données enregistrées par les appareils de suivi Google et Fitbit (comme les bracelets d'activité Fitbit et la Pixel Watch). Exclut les données enregistrées manuellement et les données estimées par le téléphone. Utilisez cette option lorsque votre intégration nécessite des données de télémétrie brutes des capteurs enregistrées directement par le matériel wearable.
users/me/dataSourceFamilies/google-sources Inclut les sources Google et Fitbit first party. Cela inclut les enregistrements des appareils de suivi d'activité physique, les données de Santé Connect et toutes les entrées manuelles enregistrées dans des applications propriétaires (comme l'app Fitbit ou Google Fit).

Pour obtenir un flux de données réconciliées à partir d'une famille de sources de données spécifique, appelez le point de terminaison reconcile avec le paramètre de requête dataSourceFamily.

Par exemple, la requête GET suivante récupère le sommeil enregistré par le bracelet 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": ""
}

Pour agréger des points de données sur une taille de fenêtre spécifique limitée à une famille de sources de données particulière, appelez le point de terminaison rollUp et transmettez le champ dataSourceFamily dans le corps de la requête JSON.

La requête POST suivante interroge le nombre de pas intrajournaliers par intervalles horaires (3600s), agrégés exclusivement à partir d'accessoires connectés :

Requête

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

{
  "range": {
    "startTime": "2026-07-29T00:00:00Z",
    "endTime": "2026-07-29T23:59:59Z"
  },
  "windowSize": "3600s",
  "dataSourceFamily": "users/me/dataSourceFamilies/google-wearables"
}

Réponse

{
  "rollupDataPoints": [
    {
      "startTime": "2026-07-29T08:00:00Z",
      "endTime": "2026-07-29T09:00:00Z",
      "steps": {
        "countSum": "1200"
      }
    },
    {
      "startTime": "2026-07-29T09:00:00Z",
      "endTime": "2026-07-29T10:00:00Z",
      "steps": {
        "countSum": "3450"
      }
    }
  ]
}

Pour agréger les points de données quotidiens d'une famille de sources spécifique, appelez le point de terminaison dailyRollUp et transmettez le champ dataSourceFamily dans le corps de la requête.

Par exemple, la requête suivante calcule les cumuls quotidiens des pas de l'utilisateur, y compris toutes les sources Google et Fitbit propriétaires (wearables + saisies manuelles) :

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": 7,
        "day": 28
      },
      "time": {
        "hours": 0,
        "minutes": 0,
        "seconds": 0,
        "nanos": 0
      }
    },
    "end": {
      "date": {
        "year": 2026,
        "month": 7,
        "day": 30
      },
      "time": {
        "hours": 0,
        "minutes": 0,
        "seconds": 0,
        "nanos": 0
      }
    }
  },
  "windowSizeDays": 1,
  "dataSourceFamily": "users/me/dataSourceFamilies/google-sources"
}

Réponse

{
  "rollupDataPoints": [
    {
      "civilStartTime": {
        "date": {
          "year": 2026,
          "month": 7,
          "day": 28
        },
        "time": {}
      },
      "civilEndTime": {
        "date": {
          "year": 2026,
          "month": 7,
          "day": 28
        },
        "time": {
          "hours": 23,
          "minutes": 59,
          "seconds": 59
        }
      },
      "steps": {
        "countSum": "8430"
      }
    },
    {
      "civilStartTime": {
        "date": {
          "year": 2026,
          "month": 7,
          "day": 29
        },
        "time": {}
      },
      "civilEndTime": {
        "date": {
          "year": 2026,
          "month": 7,
          "day": 29
        },
        "time": {
          "hours": 23,
          "minutes": 59,
          "seconds": 59
        }
      },
      "steps": {
        "countSum": "11245"
      }
    }
  ]
}

Agréger des points de données sur une période donnée

Utilisez le point de terminaison rollUp pour renvoyer l'agrégat de points de données basé sur 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 plage de dates requise dans le fuseau horaire 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 les données sur un ou plusieurs jours

Le point de terminaison dailyRollUp doit être utilisé lorsque vous souhaitez agréger des données sur un ou plusieurs jours, appelés windowSize. Indiquez la plage de temps civil 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"
      }
    }
  ]
}

Regroupement lorsque la plage n'est pas un multiple de la taille de la fenêtre

Si la plage demandée n'est pas un multiple exact de windowSize (ou windowSizeDays), le dernier bucket chronologique sera tronqué au point de terminaison supérieur de la plage et couvrira une durée inférieure à la taille de la fenêtre. L'API accepte votre demande sans la modifier et n'effectue aucun arrondi, décalage horaire ni interpolation de données.

Pour couvrir l'intégralité de la plage demandée, l'API utilise la division par excès pour calculer le nombre total de fenêtres d'agrégation :

Number of windows = ceiling(Range duration / Window size)

Chaque bucket commence séquentiellement au début de votre plage. Si l'ajout d'une autre fenêtre de taille normale dépasse l'heure de fin demandée, la dernière fenêtre est tronquée (limitée) à l'heure de fin de la plage.

Fonctionnement du regroupement dans des buckets

Lorsque vous demandez des cumuls avec des plages non divisibles, l'API applique les règles suivantes :

  • Le bucketing commence au début de la plage demandée (range.startTime ou range.start) et progresse en fonction de la taille de la fenêtre (windowSize ou windowSizeDays).
  • Le dernier bucket chronologique est limité à la fin de la plage demandée (range.endTime ou range.end), ce qui signifie qu'il couvre une durée plus courte que la taille de la fenêtre demandée.
  • Les objets RollupDataPoint ou DailyRollupDataPoint renvoyés spécifient explicitement leurs propres codes temporels de début et de fin, que vous pouvez utiliser pour inspecter la durée réelle du bucket tronqué.
  • Étant donné que l'API renvoie les données cumulées dans l'ordre chronologique inverse (les plus récentes en premier), le dernier bucket chronologique (qui est celui tronqué) apparaît comme le premier élément (index 0) de la liste renvoyée.

Scénario : plage de 12 minutes avec une fenêtre de 5 minutes

Supposons qu'un client demande un cumul sur une période de 12 minutes avec un windowSize de 5 minutes :

  • range.startTime : 10:00:00
  • range.endTime : 10:12:00 (durée totale : 12 minutes)
  • windowSize : 5 minutes

Comme 12 minutes n'est pas un multiple de 5 minutes (12 = 5 * 2 + 2), l'API accepte la requête et calcule le nombre de périodes comme suit : ceiling(12 / 5) = 3.

Cela génère les trois buckets chronologiques suivants :

  1. Bucket 1 : [10:00:00, 10:05:00) – Durée : 5 minutes (fenêtre complète)
  2. Bucket 2 : [10:05:00, 10:10:00) – Durée : 5 minutes (fenêtre complète)
  3. Bucket 3 (tronqué) : [10:10:00, 10:12:00) – Durée : 2 minutes (tronqué à range.endTime)

Impact sur les valeurs agrégées

Étant donné que la durée de la dernière fenêtre est plus courte, les métriques additives (comme la somme ou le nombre de pas) seront plus faibles dans le bucket tronqué uniquement en raison de la durée plus courte.

Si un utilisateur marche à un rythme régulier de 100 pas par minute pendant toute cette période de 12 minutes :

  • Bucket 1 (10:00–10:05) : 500 pas (5 minutes × 100 pas/minute)
  • Bucket 2 (10:05–10:10) : 500 pas (5 minutes × 100 pas/minute)
  • Bucket 3 (10:10–10:12) : 200 pas (2 minutes × 100 pas/minute)

Exemple de réponse de l'API montrant l'ordre

Étant donné que l'API renvoie les résultats dans l'ordre chronologique inverse, le bucket tronqué apparaît comme le premier élément de la liste renvoyée :

{
  "rollupDataPoints": [
    {
      "startTime": "2026-08-20T10:10:00Z",
      "endTime": "2026-08-20T10:12:00Z",
      "steps": {
        "countSum": "200"
      }
    },
    {
      "startTime": "2026-08-20T10:05:00Z",
      "endTime": "2026-08-20T10:10:00Z",
      "steps": {
        "countSum": "500"
      }
    },
    {
      "startTime": "2026-08-20T10:00:00Z",
      "endTime": "2026-08-20T10:05:00Z",
      "steps": {
        "countSum": "500"
      }
    }
  ]
}

Modifier les données de santé d'un utilisateur

Utilisez le point de terminaison patch pour mettre à jour les données de santé d'un utilisateur.

Le point de terminaison patch met à jour un enregistrement existant en fonction de l'identifiant spécifié dans l'URL de la requête. Indiquez l'identifiant d'un point de données inséré précédemment. L'API écrase l'enregistrement existant.

Quand utiliser l'identifiant de point de données ?

L'identifiant de point de données est essentiel dans les cas suivants :

  • Mises à jour ciblées : pour mettre à jour une mesure spécifique, indiquez son identifiant dans la requête patch.
  • Suppression : conserver l'identifiant permet à votre application de supprimer l'enregistrement ultérieurement à l'aide du point de terminaison batchDelete.

Voici un exemple dans lequel un utilisateur met à jour sa lecture de masse grasse sur une balance appelée "HumanScale" de la société "Scales R Us". Le nouveau taux de masse grasse de l'utilisateur est de 20% pour la date du 10/03/2026 :

Requête

PATCH https://health.googleapis.com/v4/users/me/dataTypes/body-fat/dataPoints/1234567890
Authorization: Bearer access-token
Content-Type: application/json

{
  "name": "users/me/dataTypes/body-fat/dataPoints/1234567890",
  "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/123456789/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 consigner un aliment, envoyez une requête POST au point de terminaison nutrition-log dataPoints. Le corps de la requête contient un DataPoint avec un objet nutritionLog. Pour en savoir plus, consultez le guide sur la 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/123456789/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 méthode batchDelete pour supprimer un tableau de données de l'application Fitbit d'un utilisateur.

Voici un exemple où un utilisateur a déjà enregistré sa masse grasse sur une balance, mais souhaite supprimer l'enregistrement. Utilisation de user-id et data-point-id à partir 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/123456789/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 s'est synchronisé avec l'application mobile Google Health (lastSyncTime).

Les informations de configuration et de synchronisation des listes sont utiles pour résoudre les problèmes de synchronisation ou récupérer les données historiques depuis la dernière heure de 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é, dans la mesure où elles ont été enregistrées. 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 fréquence 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 renverra 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 nextPageToken pour demander les pages suivantes.
  • Taille de page variable : les limites de capping 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 comme 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 renverra que 25 sessions de sommeil sur la première page.
  • Restrictions concernant les périodes de cumul : pour les points de terminaison de cumul et d'agrégation des données (tels que rollUp et dailyRollUp), les périodes de requête sont limitées en fonction du type de données :
    • Une plage maximale de 14 jours pour calories-in-heart-rate-zone, heart-rate, active-minutes et total-calories.
    • Une plage maximale de 90 jours pour tous les autres types de données cumulées.

En fonction du volume de données historiques dont votre application a besoin, la récupération 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 données des 7 à 14 derniers jours lors de la séquence de chargement principale. Cela garantit que les utilisateurs voient les données immédiatement, sans attendre les 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 ou à un processus en arrière-plan asynchrone et de priorité inférieure après le rendu de l'UI principale.

Regroupement 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 grandes requêtes d'agrégation historique en intervalles séquentiels plus petits respectant ces limites.
  • Regroupez ou séquencez ces sous-requêtes de manière sécurisée pour respecter les limites de simultanéité et maintenir des indicateurs de progression de l'UI stables.

Exploiter les récapitulatifs pré-agrégés

Restructurez les tableaux de bord 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)

  • Mettez en œuvre une gestion stricte de l'intervalle exponentiel entre les tentatives lorsque vous rencontrez des limites de fréquence (429 Too Many Requests) et des délais d'expiration de la passerelle du serveur (504 Gateway Timeout). Ne relancez jamais immédiatement les charges utiles volumineuses ayant échoué. Les nouvelles tentatives instantanées multiplient la congestion du backend et aggravent la dégradation du système.
Précédent
Bibliothèques clientes
Suivant
Filtres