Specifiche dell'API

La sezione Specifica dell'API fornisce una panoramica dettagliata dei componenti tecnici essenziali per l'integrazione con la piattaforma, inclusi gli ambiti di autorizzazione, le definizioni dei tipi di dati e le strutture degli endpoint. Questa API rappresenta un'evoluzione strategica dell'API Fitbit Web legacy, ricostruita su un'infrastruttura moderna per garantire un'esperienza di sviluppo più stabile e coerente.

Ambiti

Devi aggiornare la richiesta di autorizzazione per utilizzare gli ambiti dell'API Google Health. Gli ambiti definiscono se l'app supporta le operazioni di lettura o scrittura. Segui le istruzioni per l'implementazione degli ambiti, che specificano di richiedere solo gli ambiti necessari, di configurare l'accesso in scrittura solo durante l'invio dei dati e di gestire correttamente il consenso parziale.

Gli ambiti dell'API Google Health sono un URL HTTP che inizia con https://www.googleapis.com/auth/googlehealth.{scope}. Ad esempio, https://www.googleapis.com/auth/googlehealth.activity_and_fitness.writeonly.

Mappature degli ambiti

Ecco come gli ambiti dell'API Fitbit Web vengono mappati agli ambiti dell'API Google Health:

Tabella: mappature degli ambiti dall'API Fitbit Web all'API Google Health
Ambiti API Fitbit Web Ambiti dell'API Google Health
attività .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
elettrocardiogramma .ecg.readonly
battito cardiaco .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
irregular_rhythm_notifications .irn.readonly
località .location.readonly
alimentazione .nutrition.readonly
.nutrition.writeonly
oxygen_saturation .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
profilo .profile.readonly
.profile.writeonly
respiratory_rate .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
impostazioni .settings.readonly
.settings.writeonly
sonno .sleep.readonly
.sleep.writeonly
temperatura .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
peso .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly

Tipi di dati

Di seguito è riportato un elenco dei tipi di dati dell'API Google Health e della loro mappatura all'API Fitbit Web.

Tabella: mappature dei tipi di dati dall'API Fitbit Web all'API Google Health
Tipo di dati dell'API Fitbit Web Tipo di dati dell'API Google Health
  dataType		 Descrizione
Calorie attività Energia attiva bruciata
  active-energy-burned 		Rappresenta le calorie bruciate durante i periodi di attività, incluso il BMR per questi periodi. Nell'API Google Health, questo valore può essere ricostruito aggiungendo il metabolismo basale al tipo di dati active-energy-burned (che monitora le calorie bruciate solo durante l'attività, escluso il metabolismo basale).
Minuti in zona attiva Minuti in zona attiva
  active-zone-minutes
Contiene le modifiche ai livelli di attività dell'utente Livello di attività
  activity-level 		Acquisisce il livello di attività dell'utente (ad esempio sedentario o attivo) in un periodo di tempo specifico.
Elevazione Altitudine
  altitude
Attività caloriesBMR Energia bruciata basale
  basal-energy-burned 		Le calorie bruciate in base al metabolismo basale (BMR) in un periodo di tempo specifico.
Glicemia Glicemia
  blood-glucose
Grasso corporeo Grasso corporeo
  body-fat
caloriesOut in ciascuna zona del battito cardiaco Calorie nella zona del battito cardiaco
  calories-in-heart-rate-zone
Temperatura (interna) Temperatura corporea interna
  core-body-temperature
Riepilogo HRV Variabilità del battito cardiaco giornaliera
  daily-heart-rate-variability
Riepilogo SpO2 Saturazione di ossigeno giornaliera
  daily-oxygen-saturation 		Un riepilogo giornaliero delle statistiche sulla saturazione di ossigeno nel sangue (SpO2) calcolate in base alle misurazioni del sonno convalidate.
Battito cardiaco a riposo Battito cardiaco a riposo giornaliero
  daily-resting-heart-rate
Temperatura cutanea Deviazioni giornaliere della temperatura durante il sonno
  daily-sleep-temperature-derivations
Distanza Distanza
  distance
Elettrocardiogramma (ECG) Elettrocardiogramma (ECG)
  electrocardiogram
Attività registrata Esercizio
  exercise 		Allenamenti o sessioni di allenamento registrati, che includono orari di inizio/fine, tipi di attività e metriche della sessione.
Piani Piani
  floors
Cibo Cibo
  food
Unità di misura degli alimenti Unità di misura degli alimenti
  food-measurement-unit
Frequenza cardiaca Battito cardiaco
  heart-rate
HRV infragiornaliero Variabilità del battito cardiaco
  heart-rate-variability
Notifiche di ritmo irregolare (NRI) Notifica di ritmo irregolare
  irregular-rhythm-notification
Diario alimentare Diario alimentare
  nutrition-log
SpO2 infragiornaliero Saturazione di ossigeno
  oxygen-saturation 		Restituisce solo le misurazioni della SpO2 con granularità al minuto convalidate ed esclude le letture contrassegnate come non valide a causa di artefatti da movimento o bassa affidabilità del sensore. Poiché l'API Fitbit Web escludeva solo il valore sentinella del 50%, l'API Google Health restituisce meno punti dati per lo stesso intervallo di tempo. Per maggiori dettagli, consulta Filtro della saturazione di ossigeno.
Valore VO2 max quando l'utente corre VO2 max corsa
  run-vo2-max
Minuti di sedentarietà della serie temporale di attività Periodo di sedentarietà
  sedentary-period
Sonno Sonno
  sleep
Passaggi Passaggi
  steps
Bracciate delle serie temporali di attività Dati sulle vasche di nuoto
  swim-lengths-data
Attività caloriesOut Calorie totali
  total-calories 		Il numero totale di calorie bruciate da un utente in un periodo di tempo, inclusi il metabolismo basale e l'energia attiva bruciata.
Valore VO2 max VO2 max
  vo2-max
Peso Peso
  weight

Calcoli

Le mappature e le regole dell'API Google Health sono diverse da quelle dell'API Fitbit Web.

Filtro della saturazione di ossigeno

Quando esegui query sulla saturazione di ossigeno nel sangue (oxygen-saturation) a livello di minuto, l'API Google Health applica un filtro di validità dei dati più rigoroso rispetto all'API Fitbit Web precedente:

  • L'API Fitbit Web precedente (v1 e v3) escludeva solo i campioni di SpO2 con un valore sentinella del 50%.
  • L'API Google Health (v4) esclude tutti i campioni di SpO2 contrassegnati come non validi dall'algoritmo di convalida. Un minuto viene contrassegnato come non valido quando il movimento del braccio o un'aderenza non ottimale al polso rendono inaffidabile il segnale del sensore ottico, quando il punteggio di affidabilità scende al di sotto del 50%, durante i 3 minuti immediatamente precedenti e successivi a una lettura non valida o quando un intervallo valido dura meno di 4 minuti consecutivi.

Poiché l'API Google Health rimuove tutte le misurazioni non valide anziché solo il valore sentinella del 50%, restituisce meno punti dati oxygen-saturation rispetto all'API Fitbit Web per lo stesso intervallo di tempo e sono previste lacune nella copertura minuto per minuto. Le letture a livello di minuto restituite sono in linea con i punti dati convalidati utilizzati per calcolare il riepilogo relativo al sonno daily-oxygen-saturation dell'utente. Per ulteriori informazioni, consulta Filtro SpO2 a livello di minuto e validità dei dati.

Livello di attività, MET e soglie di passi

Nell'API Google Health, il livello di attività minuto per minuto di un utente viene ricavato dal suo equivalente metabolico (MET) e dal conteggio dei passi.

Livello di attività Dispositivi per il battito cardiaco Dispositivi senza rilevazione del battito cardiaco
Sedentaria ≤ 1,5 MET ≤ 1,5 MET
Leggermente attivo > 1,5 MET e ≤ 4,2 MET > 1,5 MET e ≤ 3,5 MET
Moderatamente attivo > 4,2 MET e < 6,0 MET
(a meno che non siano soddisfatte le condizioni per Molto attivo)		 > 3,5 MET e < 6,0 MET
(a meno che non siano soddisfatte le condizioni per Molto attivo)
Molto attivo ≥ 6,0 MET o ≥ 5,0 MET con una frequenza di passi pari o superiore a 150 passi al minuto ≥ 6,0 MET o ≥ 5,0 MET con una frequenza di passi pari o superiore a 150 passi al minuto

I minuti attivi sono costituiti dalla combinazione di minuti MODERATELY_ACTIVE e VERY_ACTIVE. Tuttavia, un minuto attivo viene accreditato solo se si verifica durante una serie continua di almeno 10 minuti, con un massimo di 2 minuti di interruzione di attività meno intensa.

Minuti sedentari e sonno

I minuti sedentari non includono il tempo di sonno. Nei riepiloghi giornalieri, i minuti sedentari vengono calcolati sottraendo i minuti di sonno e i minuti attivi (leggermente attivo, moderatamente attivo e molto attivo) dai minuti totali della giornata (1440 minuti):

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

Indice di massa corporea (IMC)

Poiché l'API Google Health non espone un tipo di dati IMC integrato, le applicazioni devono calcolare l'indice di massa corporea lato client utilizzando i record di altezza e peso:

  1. Recupera il peso dell'utente in grammi dal campo weightGrams nel tipo di dati Peso. Converti questo valore in chilogrammi (dividi per 1000) o in libbre (dividi per 453,59237).
  2. Recupera l'altezza dell'utente in millimetri dal campo heightMillimeters nel tipo di dati Altezza. Converti questo valore in metri (dividi per 1000) o pollici (dividi per 25,4).
  3. Utilizza una delle seguenti formule per calcolare il valore dell'IMC:
    • Formula della metrica: BMI = weight (kg) / [height (m)]^2
    • Formula imperiale: BMI = (weight (lbs) / [height (in)]^2) * 703

I valori di IMC risultanti corrispondono alle seguenti categorie:

Categoria peso Intervallo di IMC
Sottopeso Meno di 18,5
Peso sano Da 18,5 a 24,9
Sovrappeso Da 25 a 29,9
Obese 30 o superiore

Metabolismo basale (BMR)

Il metabolismo basale (BMR) è il numero minimo di calorie necessarie per le funzioni corporee di base a riposo. Poiché l'API Google Health non espone un tipo di dati BMR integrato, le applicazioni devono calcolarlo lato client utilizzando la formula di Harris-Benedict. Per saperne di più, consulta l'articolo sull'equazione di Harris-Benedict su Wikipedia.

Per eseguire questo calcolo:

  1. Recupera il peso dell'utente in grammi dal campo weightGrams nel tipo di dati Peso e convertilo in chilogrammi (dividi per 1000). Per convertire le libbre in chilogrammi, dividi per 2,2.
  2. Recupera l'altezza dell'utente in millimetri dal campo heightMillimeters nel tipo di dati Altezza e convertila in centimetri (dividi per 10). Per convertire i pollici in centimetri, moltiplica per 2,54.
  3. Recupera l'età dell'utente in anni dal campo age nella risorsa Profile.
  4. Recupera il sesso biologico in modo indipendente (ad esempio, chiedendolo all'utente o conservandolo nel tuo database), poiché l'API Google Health non espone questo campo.
  5. Utilizza una delle seguenti formule in base al sesso biologico dell'utente:
    • Uomo: BMR = 66 + (13.7 x weight_kg) + (5 x height_cm) - (6.8 x age_years)
    • Donne: BMR = 655 + (9.6 x weight_kg) + (1.8 x height_cm) - (4.7 x age_years)

Dispendio energetico giornaliero totale (TDEE)

Il dispendio energetico giornaliero totale (TDEE) è una stima del numero totale di calorie bruciate da una persona in un giorno, che tiene conto sia del BMR sia dell'attività fisica. Per stimare il TDEE dell'utente, moltiplica il valore del BMR per un fattore di attività corrispondente al suo stile di vita:

Livello di attività Descrizione Moltiplicatore
Sedentaria Attività fisica scarsa o nulla. BMR x 1.2
Attività leggera 1-3 giorni di allenamento a settimana. BMR x 1.375
Attività moderata 3-5 giorni di allenamento a settimana. BMR x 1.55
Molto attivo 6-7 giorni di allenamento a settimana. BMR x 1.725
Attività molto intensa Esercizio fisico molto intenso o lavoro fisico. BMR x 1.9

Endpoint

Gli endpoint REST adottano una sintassi coerente per tutti i tipi di dati.

  • Endpoint di servizio: l'URL HTTP di base cambia in https://health.googleapis.com.
  • Sintassi degli endpoint: l'API Google Health supporta un numero limitato di endpoint, che possono essere utilizzati dalla maggior parte dei tipi di dati supportati. In questo modo, viene fornita una sintassi coerente per tutti i tipi di dati e gli endpoint sono più facili da utilizzare.
  • Identificatore dell'utente: nella sintassi dell'endpoint deve essere specificato l'ID utente o me. Quando utilizzi me, l'ID utente viene dedotto dal token di accesso.

Esempio: di seguito è riportato un esempio dell'endpoint GET Profile chiamato utilizzando l'API Google Health

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

Mappature degli endpoint

Consulta la tabella Tipi di dati dell'API Google Health per un elenco dei tipi di dati disponibili e dei metodi API supportati.

Tipo di endpoint API Fitbit Web API Google Health
GET (Log | Summary | Daily Summary) in cui richiedi i dati di un singolo giorno dailyRollup con windowSize = 1 giorno
GET (Intraday) per richiedere dati granulari Metodo list
GET (serie temporale) per data o intervallo Metodo rollUp o dailyRollUp che include un intervallo di date
GET (Log List) Metodo list
Log CREATE e UPDATE Metodo patch
Log DELETE Metodo batchDelete
GET Profile users.getProfile restituisce le informazioni specifiche dell'utente
users.getSettings restituisce le unità e i fusi orari dell'utente
UPDATE Profile users.updateProfile modifica le informazioni specifiche dell'utente
users.updateSettings modifica le unità e i fusi orari dell'utente
Ottieni l'ID utente users.getIdentity restituisce l'ID utente Fitbit legacy e l'ID utente Google.
Ottieni dispositivi users.pairedDevices restituisce l'elenco dei dispositivi accoppiati
Crea abbonamenti projects.subscribers.subscriptions.create crea manualmente una sottoscrizione
Elimina sottoscrizioni projects.subscribers.subscriptions.delete eliminare un abbonamento
Ottieni l'elenco degli abbonamenti projects.subscribers.subscriptions.list elenca tutte le sottoscrizioni