Développer des expériences de pas avec l'API Google Health

L'API Google Health suit les données d'activité et de pas des utilisateurs à l'aide du type de données d'intervalle steps. Le nombre de pas est une mesure fondamentale de l'activité physique quotidienne. Il aide les développeurs à suivre la progression de la forme physique, à calculer la dépense énergétique et à créer des récapitulatifs d'activité quotidienne pour les utilisateurs.

Découvrez comment lire et structurer les métriques du nombre de pas dans votre application pour offrir la meilleure expérience à vos utilisateurs.

Types de données acceptés

L'API accepte le type de données suivant pour le suivi du nombre de pas :

Tableau : Types de données Google Health API Steps

Type de données	Opérations disponibles	Champ d'application
Étapes dataType : steps filter parameter : steps Type d'enregistrement  : Intervalle Résolution du stockage  : 1 minute Prise en charge des webhooks Prise en charge des zéros réels Guide des étapes Appareils compatibles Fitbit Air Fitbit Alta Fitbit Alta HR Fitbit Blaze Fitbit Charge 2 Fitbit Charge 3 Fitbit Charge 4 Fitbit Charge 5 Fitbit Charge 6 Fitbit Flex 2 Fitbit Inspire Fitbit Inspire 2 Fitbit Inspire 3 Fitbit Inspire HR Fitbit Ionic Fitbit Luxe Fitbit MobileTrack Pixel Watch Pixel Watch 2 Pixel Watch 3 Pixel Watch 4 Fitbit Sense Fitbit Sense 2 Fitbit Versa Fitbit Versa 2 Fitbit Versa 3 Fitbit Versa 4 Fitbit Versa Lite	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly

Consignes

Lorsque vous intégrez le suivi des pas à votre application, suivez ces consignes de conception et d'implémentation.

Calcul de la vitesse et de l'allure

L'API Google Health utilise des formules standards pour calculer la vitesse et l'allure :

• Vitesse = distance / time(hour)
• Allure = time(seconds) / distance

L'en-tête Accept-Language spécifié dans la requête détermine l'unité de distance.

Aperçu quotidien

Pour agréger précisément le nombre de pas quotidiens en cas de voyage, de changement de fuseau horaire ou de passage à l'heure d'été, n'effectuez pas de calculs de durée côté client. Interrogez plutôt le point de terminaison dailyRollUp, qui réconcilie automatiquement les écarts de données physiques à l'aide des décalages UTC. Le cumul renvoie un StepsRollupValue contenant le champ countSum, qui représente le nombre total de pas cumulés pour le jour demandé.

Dessiner des interfaces utilisateur (réconciliation)

Lorsque vous créez des éléments d'interface utilisateur pour afficher les données d'étape, utilisez le point de terminaison reconcile. Si plusieurs sources de données (comme une montre connectée et un téléphone mobile) ont enregistré des pas en même temps, le point de terminaison reconcile résout les conflits et fusionne les flux pour renvoyer un seul flux de données réconcilié.

Pour en savoir plus sur la gestion des intervalles qui se chevauchent lors de la synchronisation des appareils connectés et sur la mutabilité des codes temporels, consultez le guide de gestion des données.

Suivi et histogrammes intrajours

Pour afficher l'activité détaillée des utilisateurs tout au long de la journée (sous forme de graphiques, par exemple) :

• Histogrammes de pas horaires ou par minute : interrogez le point de terminaison rollUp en spécifiant la durée (par exemple, 60s pour 1 minute ou 3600s pour 1 heure) à l'aide du paramètre windowSize. Étant donné que les données de pas sont enregistrées à intervalles d'une minute (60s), définissez windowSize sur au moins 60s. Les requêtes avec des tailles de fenêtre inférieures à une minute (comme 10s ou 30s) ne segmentent pas les totaux de chaque minute, mais placent le nombre total de la minute dans le premier sous-bucket correspondant. Pour en savoir plus, consultez Taille de la fenêtre de cumul et résolution du stockage sous-jacent.
• Tous les enregistrements de pas : utilisez le point de terminaison list pour récupérer les enregistrements de pas bruts les plus précis.

Les points de terminaison rollUp, dailyRollUp et reconcile acceptent le paramètre dataSourceFamily, ce qui vous permet de filtrer les données de groupes de sources spécifiques. Pour en savoir plus et obtenir des exemples d'utilisation, consultez la section Filtrer par famille de sources de données du guide "Filtrer les données".

Synchronisation en temps réel à l'aide de webhooks

Abonnez-vous à la collection de types de données steps pour recevoir des notifications en temps réel lorsque de nouvelles données de pas sont importées ou synchronisées. Au lieu d'interroger les points de terminaison REST, mettez à jour les tableaux de bord côté client de manière dynamique en réponse à ces notifications de webhook. Pour savoir comment configurer les abonnements, consultez Abonnements aux webhooks.

Gérer les vrais zéros

L'API Google Health implémente de vrais zéros pour résoudre les intervalles sédentaires. Si un utilisateur porte un bracelet d'activité, mais ne marche pas pendant une période donnée, l'API renvoie un enregistrement pour cet intervalle contenant les métadonnées normales de la source de données et de l'horodatage, mais omet la propriété count.

Cela vous permet de faire la distinction entre :

• Périodes stationnaires au poignet : l'utilisateur porte l'appareil, mais ne marche pas. Cela renvoie les enregistrements sans la propriété count (interprétée comme zéro pas).
• Périodes sans porter l'appareil : l'utilisateur ne porte pas l'appareil. Aucun enregistrement n'est renvoyé, ce qui entraîne d'importantes lacunes dans les données.

Pour en savoir plus, consultez le guide Présence des données et vrais zéros.