Spécifications de l'API

La section "Spécification de l'API" fournit un aperçu détaillé des composants techniques essentiels à l'intégration à la plate-forme, y compris les champs d'application des autorisations, les définitions des types de données et les structures des points de terminaison. Cette API représente une évolution stratégique de l'ancienne API Web Fitbit, repensée sur une infrastructure moderne pour garantir une expérience de développement plus stable et cohérente.

Niveaux d'accès

Vous devez mettre à jour votre demande d'autorisation pour utiliser les champs d'application de l'API Google Health. Les champs d'application définissent si votre application accepte les opérations de lecture ou d'écriture. Suivez les instructions de mise en œuvre des champs d'application, qui indiquent de ne demander que les champs d'application nécessaires, de ne configurer l'accès en écriture que lors de l'envoi de données et de gérer correctement le consentement partiel.

Les champs d'application de l'API Google Health sont une URL HTTP commençant par https://www.googleapis.com/auth/googlehealth.{scope}. Par exemple, https://www.googleapis.com/auth/googlehealth.activity_and_fitness.writeonly.

Mappages de champs d'application

Voici comment les champs d'application de l'API Web Fitbit sont mappés à ceux de l'API Google Health :

Tableau : Mappages des champs d'application de l'API Web Fitbit vers l'API Google Health
Niveaux d'accès à l'API Web Fitbit Champs d'application de l'API Google Health
activité .activity_and_fitness.readonly
.activity_and_fitness.writeonly
blood_glucose .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
cardio_fitness .activity_and_fitness.readonly
.activity_and_fitness.writeonly
électrocardiogramme .ecg.readonly
fréq. cardiaque .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
irregular_rhythm_notifications .irn.readonly
position .location.readonly
nutrition .nutrition.readonly
.nutrition.writeonly
oxygen_saturation .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
profil .profile.readonly
.profile.writeonly
respiratory_rate .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
paramètres .settings.readonly
.settings.writeonly
sommeil .sleep.readonly
.sleep.writeonly
température .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
weight .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly

Types de données

Voici une liste des types de données de l'API Google Health et de leur correspondance avec l'API Web Fitbit.

Tableau : Mappages des types de données de l'API Web Fitbit vers l'API Google Health
Type de données de l'API Web Fitbit Type de données de l'API Google Health
  dataType		 Description
Dépense calorique Énergie dépensée en activité
  active-energy-burned 		Représente les calories brûlées pendant les périodes d'activité, y compris le métabolisme de base pour ces périodes. Dans l'API Google Health, vous pouvez reconstituer cette valeur en ajoutant le métabolisme de base au type de données active-energy-burned (qui suit uniquement les calories brûlées pendant l'activité, à l'exclusion du métabolisme de base).
Minutes en zone active Minutes en zone active
  active-zone-minutes
Contient les modifications apportées aux niveaux d'activité de l'utilisateur Niveau d'activité
  activity-level 		Enregistre le niveau d'activité de l'utilisateur (sédentaire ou actif, par exemple) sur une période donnée.
Élévation Altitude
  altitude
Activité caloriesBMR Énergie basale dépensée
  basal-energy-burned 		Calories brûlées en raison du métabolisme de base sur une période donnée.
Taux de glycémie Glycémie
  blood-glucose
Masse grasse Masse grasse
  body-fat
caloriesOut dans chaque zone de fréquence cardiaque Calories dans la zone de fréquence cardiaque
  calories-in-heart-rate-zone
Température (corporelle) Température corporelle centrale
  core-body-temperature
Résumé de la VFC Variabilité quotidienne de la fréquence cardiaque
  daily-heart-rate-variability
Résumé de la SpO2 Saturation en oxygène quotidienne
  daily-oxygen-saturation 		Résumé quotidien des statistiques de saturation en oxygène (SpO2) calculées à partir de mesures de sommeil validées.
Fréquence cardiaque au repos Fréquence cardiaque au repos quotidienne
  daily-resting-heart-rate
Température cutanée Écarts quotidiens de température pendant le sommeil
  daily-sleep-temperature-derivations
Distance Distance
  distance
Électrocardiogramme (ECG) Électrocardiogramme (ECG)
  electrocardiogram
Activité enregistrée Exercice
  exercise 		Entraînements ou séances d'exercice enregistrés, y compris les heures de début et de fin, les types d'activité et les métriques de la séance.
Étages Étages
  floors
Nourriture Cuisine
  food
Unité de mesure des aliments Unité de mesure des aliments
  food-measurement-unit
Fréquence cardiaque Fréquence cardiaque
  heart-rate
VFC intrajournalière Variabilité de la fréquence cardiaque
  heart-rate-variability
Notifications de rythme irrégulier (IRN) Notification de rythme irrégulier
  irregular-rhythm-notification
Journal d'alimentation Journal de nutrition
  nutrition-log
SpO2 intrajournalière Saturation en oxygène
  oxygen-saturation 		Renvoie uniquement les mesures de SpO2 validées à la minute près et exclut les relevés signalés comme non valides en raison d'artefacts de mouvement ou d'une faible fiabilité du capteur. Étant donné que l'API Web Fitbit n'excluait que la valeur sentinelle de 50 %, l'API Google Health renvoie moins de points de données pour la même période. Pour en savoir plus, consultez Filtrage de la saturation en oxygène.
Valeur de VO2 max lorsque l'utilisateur court VO2 max de la course
  run-vo2-max
Séries temporelles d'activité : minutes sédentaires Période sédentaire
  sedentary-period
Sommeil Sommeil
  sleep
Étapes Étapes
  steps
Séries temporelles d'activité : mouvements de nage Données sur les longueurs de nage
  swim-lengths-data
Activité caloriesOut Total des calories
  total-calories 		Nombre total de calories brûlées par un utilisateur sur une période donnée, y compris le taux métabolique de base et l'énergie active brûlée.
Valeur de VO2 max VO2 max
  vo2-max
Poids Poids
  weight

Calculs

Les mappages et les règles de l'API Google Health diffèrent de ceux de l'API Web Fitbit.

Filtrage de la saturation en oxygène

Lors de l'interrogation de la saturation en oxygène du sang à la minute (oxygen-saturation), l'API Google Health applique un filtrage de validité des données plus strict que l'ancienne API Web Fitbit :

  • L'ancienne API Web Fitbit (v1 et v3) n'excluait que les échantillons de SpO2 ayant une valeur sentinelle de 50%.
  • L'API Google Health (v4) exclut tous les échantillons de SpO2 signalés comme non valides par l'algorithme de validation. Une minute est marquée comme non valide lorsque le mouvement du bras ou un ajustement lâche au poignet rend le signal du capteur optique peu fiable, lorsque le score de confiance passe sous la barre des 50%, pendant les trois minutes précédant et suivant immédiatement une lecture non valide, ou lorsqu'une période valide dure moins de quatre minutes consécutives.

Étant donné que l'API Google Health supprime toutes les mesures non valides plutôt que seulement la valeur sentinelle de 50 %, elle renvoie moins de points de données oxygen-saturation que l'API Web Fitbit pour la même période, et des lacunes dans la couverture minute par minute sont attendues. Les relevés renvoyés à la minute correspondent aux points de données validés utilisés pour calculer le daily-oxygen-saturation résumé de la nuit de l'utilisateur. Pour en savoir plus, consultez Filtrage de la SpO2 à la minute et validité des données.

Niveau d'activité, MET et seuils de pas

Dans l'API Google Health, le niveau d'activité d'un utilisateur minute par minute est calculé à partir de son équivalent métabolique (MET) et de son nombre de pas.

Au niveau de l'activité Appareils de mesure de la fréquence cardiaque Appareils sans suivi de la fréquence cardiaque
Sédentaire ≤ 1,5 MET ≤ 1,5 MET
Légèrement actif > 1,5 MET et ≤ 4,2 MET > 1,5 MET et ≤ 3,5 MET
Modérément actif > 4,2 MET et < 6 MET
(sauf si les conditions pour Très actif sont remplies)		 > 3,5 MET et < 6,0 MET
(sauf si les conditions pour Très actif sont remplies)
Très actif ≥ 6 MET, ou ≥ 5 MET avec une cadence de 150 pas par minute ou plus ≥ 6 MET, ou ≥ 5 MET avec une cadence de 150 pas par minute ou plus

Les minutes actives sont composées des minutes MODERATELY_ACTIVE et VERY_ACTIVE combinées. Toutefois, une minute très active n'est créditée que si elle se produit pendant une série continue d'au moins 10 minutes, avec au maximum deux minutes d'activité plus faible.

Minutes sédentaires et sommeil

Les minutes sédentaires n'incluent pas le temps de sommeil. Dans les récapitulatifs quotidiens, les minutes sédentaires sont calculées en soustrayant les minutes de sommeil et les minutes actives (légèrement actives, modérément actives et très actives) du nombre total de minutes dans la journée (1 440 minutes) :

Sedentary Minutes = 1440 - Sleep Minutes - Lightly Active Minutes - Moderately Active Minutes - Very Active Minutes

Indice de masse corporelle (IMC)

Étant donné que l'API Google Health n'expose pas de type de données d'IMC intégré, les applications doivent calculer l'indice de masse corporelle côté client à l'aide des enregistrements de taille et de poids :

  1. Récupérez le poids de l'utilisateur en grammes à partir du champ weightGrams du type de données Poids. Convertissez cette valeur en kilogrammes (divisez par 1 000) ou en livres (divisez par 453,59237).
  2. Récupérez la taille de l'utilisateur en millimètres à partir du champ heightMillimeters du type de données Taille. Convertissez cette valeur en mètres (divisez par 1 000) ou en pouces (divisez par 25,4).
  3. Utilisez l'une des formules suivantes pour calculer l'IMC :
    • Formule de la métrique : BMI = weight (kg) / [height (m)]^2
    • Formule impériale : BMI = (weight (lbs) / [height (in)]^2) * 703

Les valeurs d'IMC obtenues correspondent aux catégories suivantes :

Catégorie de poids Plage d'IMC
Insuffisance pondérale Moins de 18,5
Poids sain 18,5 à 24,9
Surpoids 25 à 29,9
Obèse 30 ou plus

Métabolisme de base

Le métabolisme de base (MB) est le nombre minimal de calories nécessaires au fonctionnement de base de l'organisme au repos. Étant donné que l'API Google Health n'expose pas de type de données de métabolisme de base intégré, les applications doivent le calculer côté client à l'aide de la formule de Harris-Benedict. Pour en savoir plus, consultez l'article sur l'équation de Harris-Benedict sur Wikipédia.

Pour effectuer ce calcul :

  1. Récupérez le poids de l'utilisateur en grammes à partir du champ weightGrams du type de données Poids et convertissez-le en kilogrammes (divisez par 1 000). Pour convertir des livres en kilogrammes, divisez par 2,2.
  2. Récupérez la taille de l'utilisateur en millimètres à partir du champ heightMillimeters du type de données Height, puis convertissez-la en centimètres (divisez par 10). Pour convertir des pouces en centimètres, multipliez par 2,54.
  3. Récupérez l'âge de l'utilisateur en années à partir du champ age de la ressource Profile.
  4. Récupérez le sexe biologique indépendamment (par exemple, en le demandant à l'utilisateur ou en le conservant dans votre propre base de données), car l'API Google Health n'expose pas ce champ.
  5. Utilisez l'une des formules suivantes en fonction du sexe biologique de l'utilisateur :
    • Hommes : BMR = 66 + (13.7 x weight_kg) + (5 x height_cm) - (6.8 x age_years)
    • Femmes : BMR = 655 + (9.6 x weight_kg) + (1.8 x height_cm) - (4.7 x age_years)

Dépense énergétique quotidienne totale (DEQT)

La dépense énergétique quotidienne totale (DEQT) est une estimation du nombre total de calories qu'une personne brûle en une journée, en tenant compte à la fois du métabolisme de base et de l'activité physique. Pour estimer la DEET de l'utilisateur, multipliez la valeur du MB par un facteur d'activité correspondant à son mode de vie :

Au niveau de l'activité Description Multiplicateur
Sédentaire Peu ou pas d'exercice. BMR x 1.2
Peu actif 1 à 3 jours d'exercice par semaine. BMR x 1.375
Modérément actif 3 à 5 jours d'exercice par semaine. BMR x 1.55
Très actif 6 à 7 jours d'exercice par semaine. BMR x 1.725
Très actif Exercice très intense ou travail physique. BMR x 1.9

Points de terminaison

Les points de terminaison REST adoptent une syntaxe cohérente pour tous les types de données.

  • Point de terminaison de service : l'URL HTTP de base devient https://health.googleapis.com.
  • Syntaxe des points de terminaison : l'API Google Health est compatible avec un nombre limité de points de terminaison, qui peuvent être utilisés par la plupart des types de données compatibles. Cela fournit une syntaxe cohérente pour tous les types de données et facilite l'utilisation des points de terminaison.
  • Identifiant utilisateur : l'ID utilisateur ou "me" doit être spécifié dans la syntaxe du point de terminaison. Lorsque vous utilisez "me", l'ID utilisateur est déduit du jeton d'accès.

Exemple : Voici un exemple de point de terminaison GET Profile appelé à l'aide de l'API Google Health.

GET https://health.googleapis.com/v4/users/me/profile

Mappages de points de terminaison

Consultez le tableau Types de données de l'API Google Health pour obtenir la liste des types de données disponibles et des méthodes d'API qu'ils acceptent.

Type de point de terminaison de l'API Web Fitbit API Google Health
GET (Log | Summary | Daily Summary) où vous demandez un seul jour de données Méthode dailyRollup avec windowSize = 1 jour
GET (Intraday) où vous demandez des données précises Méthode list
GET (séries temporelles) par date ou intervalle Méthode rollUp ou dailyRollUp incluant une plage de dates
GET (liste des journaux) Méthode list
Journaux CREATE et UPDATE Méthode patch
Journaux DELETE Méthode batchDelete
Requête GET sur un profil users.getProfile renvoie les informations spécifiques de l'utilisateur
users.getSettings renvoie les unités et les fuseaux horaires de l'utilisateur
UPDATE Profile users.updateProfile modifie les informations spécifiques de l'utilisateur
users.updateSettings modifie les unités et les fuseaux horaires de l'utilisateur
Obtenir l'ID utilisateur users.getIdentity renvoie l'ancien ID utilisateur Fitbit et l'ID utilisateur Google.
Obtenir des appareils users.pairedDevices renvoie la liste des appareils associés.
Créer des abonnements projects.subscribers.subscriptions.create crée manuellement un abonnement
Supprimer les abonnements projects.subscribers.subscriptions.delete supprimer un abonnement
Obtenir la liste des abonnements projects.subscribers.subscriptions.list liste tous les abonnements.