Tipi di dati dell'API Google Health

La tabella seguente contiene l'elenco completo dei tipi di dati, con diverse colonne per aiutarti a comprendere la rappresentazione di ciascun tipo nell'API Google Health, nonché l'ambito in cui è disponibile ciascun tipo.

Importante: il formato degli identificatori del tipo di dati è diverso quando il tipo di dati è composto da più di una parola. In un endpoint, il nome del tipo di dati deve essere in formato kebab case, ad esempio body-fat. In un parametro di filtro, tuttavia, il nome del tipo di dati deve essere in snake case, ad esempio body_fat.

Tabella: tipi di dati dell'API Google Health

Tipo di dati   dataType Parametro   filter	Tipo di record	Operazioni disponibili	Ambito	Supporto webhook	Supporto per i veri zeri
Energia attiva bruciata   active-energy-burned   active_energy_burned	Intervallo	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
Minuti attivi   active-minutes   active_minutes	Intervallo	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
Minuti in zona attiva   active-zone-minutes   active_zone_minutes	Intervallo	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
Livello di attività   activity-level   activity_level	Intervallo	list, reconcile	.activity_and_fitness.readonly .activity_and_fitness.writeonly
Altitudine   altitude   altitude	Intervallo	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
Glicemia   blood-glucose   blood_glucose	Esempio	list, get, reconcile, rollup, dailyRollup	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
Grasso corporeo   body-fat   body_fat	Esempio	list, get, reconcile, rollup, dailyRollup, create, update, batchDelete	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
Calorie nella zona battito cardiaco   calories-in-heart-rate-zone   calories_in_heart_rate_zone	Intervallo	rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
Temperatura corporea interna   core-body-temperature   core_body_temperature	Esempio	list, get, reconcile, rollup, dailyRollup	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
Variabilità del battito cardiaco giornaliera   daily-heart-rate-variability   daily_heart_rate_variability	Ogni giorno	list, reconcile	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
Zone battito cardiaco giornaliere   daily-heart-rate-zones   daily_heart_rate_zones	Ogni giorno	list, reconcile	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
Saturazione di ossigeno giornaliera   daily-oxygen-saturation   daily_oxygen_saturation	Ogni giorno	list, reconcile	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
Frequenza respiratoria giornaliera   daily-respiratory-rate   daily_respiratory_rate	Ogni giorno	list, reconcile	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
Battito cardiaco a riposo giornaliero   daily-resting-heart-rate   daily_resting_heart_rate	Ogni giorno	list, reconcile	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
Derivazioni giornaliere della temperatura del sonno   daily-sleep-temperature-derivations   daily_sleep_temperature_derivations	Ogni giorno	list, reconcile	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
VO2 max giornaliero   daily-vo2-max   daily_vo2_max	Ogni giorno	list, reconcile	.activity_and_fitness.readonly .activity_and_fitness.writeonly
Distanza   distance   distance	Intervallo	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
Elettrocardiogramma (ECG)   electrocardiogram   electrocardiogram	Sessione	list	.ecg.readonly
Allenamento   exercise   exercise	Sessione	list, get, reconcile, create, update, batchDelete	.activity_and_fitness.readonly .activity_and_fitness.writeonly
Piani   floors   floors	Intervallo	reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
Cibo   food   food	Cibo	list, get	.nutrition.readonly .nutrition.writeonly
Unità di misura del cibo   food-measurement-unit   food_measurement_unit	Cibo	list, get	.nutrition.readonly .nutrition.writeonly
Battito cardiaco   heart-rate   heart_rate	Esempio	list, reconcile, rollup, dailyRollup	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
Variabilità del battito cardiaco   heart-rate-variability   heart_rate_variability	Esempio	list, reconcile	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
Altezza   height   height	Esempio	list, get, reconcile, create, update, batchDelete	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
Diario dell'idratazione   hydration-log   hydration_log	Sessione	list, get, reconcile, rollup, dailyRollup, create, update, batchDelete	.nutrition.readonly .nutrition.writeonly
Notifica di ritmo irregolare   irregular-rhythm-notification   irregular_rhythm_notification	Sessione	list	.irn.readonly
Periodo mestruale   menstrual-period   menstrual_period	Intervallo	create, update, batchDelete	.reproductive_health.writeonly
Stati d'animo   moods   moods	Esempio	create, update, batchDelete	.mindfulness.writeonly
Diario alimentare   nutrition-log   nutrition_log	Esempio	list, get, reconcile, rollup, dailyRollup, create, update, batchDelete	.nutrition.readonly .nutrition.writeonly
Test di ovulazione   ovulation-test   ovulation_test	Esempio	create, update, batchDelete	.reproductive_health.writeonly
Saturazione di ossigeno   oxygen-saturation   oxygen_saturation	Esempio	list, reconcile	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
Riepilogo del sonno della frequenza respiratoria   respiratory-rate-sleep-summary   respiratory_rate_sleep_summary	Esempio	list, reconcile	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
VO2 max corsa   run-vo2-max   run_vo2_max	Esempio	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
Periodo sedentario   sedentary-period   sedentary_period	Intervallo	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
Sonno   sleep   sleep	Sessione	list, get, reconcile, create, update, batchDelete	.sleep.readonly .sleep.writeonly
Passaggi   steps   steps	Intervallo	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
Dati sulle vasche   swim-lengths-data   swim_lengths_data	Intervallo	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
Sintomi   symptoms   symptoms	Esempio	create, update, batchDelete	.logged_symptoms.writeonly
Tempo nella zona battito cardiaco   time-in-heart-rate-zone   time_in_heart_rate_zone	Intervallo	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
Calorie totali   total-calories   total_calories	Intervallo	rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
VO2 max   vo2-max   vo2_max	Esempio	list, reconcile	.activity_and_fitness.readonly .activity_and_fitness.writeonly
Peso   weight   weight	Esempio	list, get, reconcile, rollup, dailyRollup, create, update, batchDelete	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly

Vincoli per le query

Quando esegui query su punti dati, rollup o rollup giornalieri dall'API, tieni presente i seguenti vincoli:

• Requisiti di filtro:alcuni tipi di dati derivati di sola lettura, come total-calories, richiedono un filtro che specifichi un'ora di inizio dell'intervallo (utilizzando l'ora fisica o civile).
• Limiti dell'intervallo di query:l'intervallo di query massimo per calories-in-heart-rate-zone, heart-rate, active-minutes e total-calories è di 14 giorni. L'intervallo di query massimo per tutti gli altri tipi di dati è 90 giorni.

Disponibilità dei dati

Gli aggiornamenti ai dati dell'utente sono disponibili solo dopo la sincronizzazione del tracker di attività o l'inserimento manuale di nuovi dati nell'app mobile o nell'app web Fitbit. Il dispositivo Fitbit e l'app mobile Fitbit possono sincronizzarsi automaticamente ogni 15 minuti quando l'app Fitbit è aperta sul dispositivo mobile e i due dispositivi hanno una connessione dati attiva e si trovano nel raggio d'azione del Bluetooth. Se l'utente monitora l'attività utilizzando MobileTrack, la sincronizzazione di MobileTrack avviene ogni ora finché l'app è aperta.

Esecuzione di query sui dati storici

Uno dei vantaggi principali dell'API Google Health è la possibilità di monitorare le prestazioni di un utente e i suoi parametri vitali per lunghi periodi di tempo. Puoi eseguire query sui dati di un utente a partire dal momento in cui sono stati registrati. L'API non impone limitazioni o restrizioni alla quantità di dati storici che la tua applicazione può utilizzare.

Tuttavia, l'esecuzione di query sui dati storici è ancora regolata dai limiti di frequenza standard. Per ridurre il numero di chiamate API rispetto a questi limiti, l'API Google Health supporta l'esecuzione di query sui dati in un intervallo di date. Tieni presente i seguenti limiti di paginazione e richieste:

• Ogni endpoint restituisce una dimensione massima della pagina di 10.000 punti dati per pagina.
• Gli intervalli di date delle query sono limitati a un periodo compreso tra 14 e 90 giorni per richiesta.

A seconda del volume di dati storici di cui ha bisogno la tua applicazione, il recupero dell'intero set di dati potrebbe richiedere più richieste sequenziali e richiedere più tempo. Tienilo presente quando progetti la procedura di sincronizzazione dei dati della tua applicazione.

Per garantire un rendimento ottimale ed evitare errori dell'API, segui queste linee guida quando interroghi i dati storici:

Sincronizzazione dei dati in fasi (caricamento hot e caricamento completo)

• Caricamento "rapido" iniziale:recupera e visualizza solo i dati più recenti (7-14 giorni) durante la sequenza di caricamento principale. In questo modo, gli utenti vedono immediatamente i dati senza dover attendere query di lunga durata.
• Caricamento "a freddo" in background:delega il recupero dei dati storici meno recenti a una coda asincrona a priorità inferiore o a un processo in background dopo il rendering della UI principale.

Chunking delle query basato sul tempo

• Non richiedere intervalli di più anni o più mesi in una singola chiamata API. Suddividi le query storiche di grandi dimensioni in intervalli più piccoli e sequenziali (ad esempio, 1 settimana per richiesta).
• Raggruppa o sequenzia queste sottoquery in modo sicuro per rispettare i limiti di concorrenza e mantenere indicatori di avanzamento dell'interfaccia utente stabili.

Sfruttare i roll-up pre-aggregati

Ristruttura le dashboard di panoramica e i grafici delle tendenze in modo che utilizzino endpoint preaggregati e di riepilogo (ad esempio DailyRollUpDataPoints). In questo modo, si ridurranno drasticamente il sovraccarico di calcolo sul backend e il tempo di trasferimento di rete al client.

Gestione degli errori resiliente (ripetizioni intelligenti)

• Implementa una gestione rigorosa del backoff esponenziale quando si verificano limiti di frequenza (429 Too Many Requests) e timeout del gateway del server (504 Gateway Timeout). Non riprovare immediatamente a inviare payload di grandi dimensioni non riusciti. I tentativi immediati moltiplicano la congestione del backend e peggiorano il sistema.
• Se una query va ripetutamente in timeout, torna automaticamente a una finestra temporale più piccola (ad esempio, riduci un blocco di una settimana a tre giorni).

Avviso:la mancata osservanza di queste linee guida può causare errori e comportamenti imprevisti.

Accesso di terze parti

I dispositivi Fitbit non possono comunicare direttamente con applicazioni o servizi di terze parti. Questi dispositivi sono progettati per comunicare e sincronizzarsi esclusivamente con l'app mobile Fitbit.

Il dispositivo sincronizza automaticamente i dati durante il giorno, ogni volta che l'app Fitbit è aperta o ogni 15 minuti se il Bluetooth è attivo e l'app è in esecuzione in background. Una volta completata questa procedura di sincronizzazione, i dati sono disponibili per i servizi di terze parti tramite l'API Google Health.

Standard di distanza

Le distanze di allenamento, ad esempio elevationGainMillimeters, sono misurate in millimetri come unità standard per i seguenti motivi:

1. Mantenimento della precisione dei dati: il motivo più importante per utilizzare i millimetri è garantire di non perdere precisione nei dati che leggiamo e forniamo. L'utilizzo di un'unità di misura precisa come i millimetri ci consente di rappresentare le misurazioni con elevata precisione.
2. Standardizzazione: i millimetri sono l'unità standardizzata progettata per tutti i nostri servizi. Questa coerenza contribuisce a garantire un'esperienza uniforme per gli sviluppatori che interagiscono con diverse parti dell'API.
3. Ampio supporto del sistema di misurazione: l'utilizzo di un'unità di base come i millimetri consente agli sviluppatori di eseguire facilmente la conversione in qualsiasi altra unità scelta, indipendentemente dal fatto che utilizzino sistemi di misurazione metrici, imperiali o di altro tipo.

Durata variabile dei giorni

La gestione dell'ora da parte dell'API Health dà la priorità all'ora dell'utente per tenere conto della durata variabile del giorno causata dall'ora legale o dai viaggi. Ogni punto dati viene memorizzato con un timestamp UTC fisico e l'offset UTC attivo al momento dell'evento. In questo modo, il sistema può:

• Mappa l'evento in un istante fisico preciso.
• Correggi l'ora in base al contesto locale dell'utente per l'aggregazione.

Ora legale

Quando viene applicata l'ora legale, il "ritorno" all'ora solare comporta un giorno civile di 25 ore e l'aggregazione per quella data conterrà 25 ore di dati. L'ora legale comporta un giorno civile di 23 ore in cui l'ora torna all'ora solare.

Viaggiare

I viaggi attraverso i fusi orari possono causare variazioni ancora più significative nella durata fisica di un singolo giorno civile.

Utilizza l'endpoint dailyRollUp per riconciliare le differenze di fuso orario. Attribuisce automaticamente i dati al giorno di calendario in cui sono stati registrati in base all'ora locale dell'utente, "unendo" di fatto la giornata nonostante i cambiamenti di fuso orario.