L'API Google Health fornisce tipi di dati che monitorano l'andamento del sonno di un utente, tra cui durata, qualità e metriche fisiologiche durante il riposo. Queste metriche aiutano le applicazioni a fornire insight su recupero, igiene del sonno e tendenze di salute a lungo termine.
Le metriche fisiologiche come la variabilità del battito cardiaco (HRV), la saturazione di ossigeno (SpO2) e la frequenza respiratoria vengono registrate specificamente durante il sonno perché il corpo si trova in uno stato stabile e di riposo. In questo modo, l'API può acquisire una base di riferimento della salute autonomica e respiratoria dell'utente senza l'interferenza di fattori di stress diurni, attività fisica o condizioni ambientali variabili.
Comprendi le differenze tra questi tipi di dati per determinare quali metriche sono adatte alla tua applicazione.
Tipi di dati supportati
L'API supporta i seguenti tipi di dati per la misurazione del sonno:
| Tipo di dati | Operazioni disponibili |
Ambito |
|---|---|---|
|
Variabilità del battito cardiaco giornaliera
dataType:
daily-heart-rate-variabilityfilter parameter: daily_heart_rate_variability
Tipo di record: giornaliero
Dispositivi compatibili
|
elenco, riconciliazione | .health_metrics_and_measurements.readonly.health_metrics_and_measurements.writeonly |
|
Saturazione di ossigeno giornaliera
dataType:
daily-oxygen-saturationfilter parameter: daily_oxygen_saturation
Tipo di record: giornaliero
Dispositivi compatibili
|
elenco, riconciliazione | .health_metrics_and_measurements.readonly.health_metrics_and_measurements.writeonly |
|
Frequenza respiratoria giornaliera
dataType:
daily-respiratory-ratefilter parameter: daily_respiratory_rate
Tipo di record: giornaliero
Dispositivi compatibili
|
elenco, riconciliazione | .health_metrics_and_measurements.readonly.health_metrics_and_measurements.writeonly |
|
Variazioni giornaliere della temperatura durante il sonno
dataType:
daily-sleep-temperature-derivationsfilter parameter: daily_sleep_temperature_derivations
Tipo di record: giornaliero
Dispositivi compatibili
|
elenca, riconcilia | .health_metrics_and_measurements.readonly.health_metrics_and_measurements.writeonly |
|
Variabilità del battito cardiaco
dataType:
heart-rate-variabilityfilter parameter: heart_rate_variability
Tipo di record: Esempio
Dispositivi compatibili
|
elenca, riconcilia | .health_metrics_and_measurements.readonly.health_metrics_and_measurements.writeonly |
|
Saturazione di ossigeno
dataType:
oxygen-saturationfilter parameter: oxygen_saturation
Tipo di record: Esempio
Risoluzione di archiviazione: 1 minuto
Dispositivi compatibili
|
elenca, riconcilia | .health_metrics_and_measurements.readonly.health_metrics_and_measurements.writeonly |
|
Riepilogo del sonno relativo alla frequenza respiratoria
dataType:
respiratory-rate-sleep-summaryfilter parameter: respiratory_rate_sleep_summary
Tipo di record: Esempio
Dispositivi compatibili
|
elenco, riconciliazione | .health_metrics_and_measurements.readonly.health_metrics_and_measurements.writeonly |
|
Sonno
dataType:
sleepfilter parameter: sleep
Tipo di record: Sessione
Dispositivi compatibili
|
list, get, reconcile, create, update, batchDelete | .sleep.readonly.sleep.writeonly |
Sessioni di sonno e brevi risvegli
Una sessione di sonno (Sleep) rappresenta un evento di sonno distinto, ad esempio un singolo sonno notturno o un pisolino diurno. Include un'analisi dettagliata delle fasi del sonno non sovrapposte, insieme a brevi intervalli di transizione alla veglia noti come brevi risvegli.
- Sessione di sonno (
Sleep): rappresenta un evento di sonno distinto (intervalli delle fasiLIGHT,DEEP,REM,AWAKE) che suddivide la cronologia contigua del riposo principale. - Brevi risvegli (
shortAwakenings): brevi transizioni di veglia o risvegli che si verificano durante il riposo. A differenza degli intervalli delle fasiAWAKEstandard (che dividono la progressione delle fasi del sonno contigue non sovrapposte), i risvegli brevi sono segmenti distinti che possono sovrapporsi alle fasi del sonno circostanti. Forniscono una visibilità granulare sull'agitazione e sui microrisvegli senza interrompere la struttura principale delle fasi del sonno. - Risvegli notturni: i risvegli notturni (ad esempio per bere un bicchiere d'acqua) vengono identificati dalla fusione dei sensori on-device (accelerometro, giroscopio e conteggio dei passi). Le applicazioni possono rilevare i risvegli notturni filtrando
stagesper gli intervalli contype: "AWAKE"(utilizzato sia nei diari del sonnoCLASSICche in quelliSTAGES) o ispezionandooutOfBedSegments.
Esempio
{
"name": "users/user-id/dataTypes/sleep/dataPoints/data-point-id",
"sleep": {
"interval": {
"startTime": "2026-04-20T22:30:00Z",
"startUtcOffset": "-14400s",
"endTime": "2026-04-21T06:30:00Z",
"endUtcOffset": "-14400s"
},
"type": "STAGES",
"stages": [
{
"startTime": "2026-04-20T22:30:00Z",
"startUtcOffset": "-14400s",
"endTime": "2026-04-20T23:45:00Z",
"endUtcOffset": "-14400s",
"type": "LIGHT"
},
{
"startTime": "2026-04-20T23:45:00Z",
"startUtcOffset": "-14400s",
"endTime": "2026-04-21T01:15:00Z",
"endUtcOffset": "-14400s",
"type": "DEEP"
}
],
"shortAwakenings": [
{
"startTime": "2026-04-20T23:10:00Z",
"startUtcOffset": "-14400s",
"endTime": "2026-04-20T23:11:30Z",
"endUtcOffset": "-14400s",
"type": "AWAKE"
}
],
"summary": {
"minutesInSleepPeriod": "480",
"minutesAsleep": "455",
"minutesAwake": "25",
"minutesToFallAsleep": "15",
"minutesAfterWakeUp": "10"
}
}
}
Crea una sessione di sonno
Per creare una voce di sessione di sonno, invia una richiesta POST all'endpoint dei punti dati sleep. La risposta include il campo name contenente data-point-id, che può essere utilizzato in una richiesta Update (Patch) o Delete.
Richiesta
POST https://health.googleapis.com/v4/users/me/dataTypes/sleep/dataPoints
Authorization: Bearer access-token
Content-Type: application/json
{
"sleep": {
"interval": {
"startTime": "2026-06-07T22:00:00Z",
"startUtcOffset": "-14400s",
"endTime": "2026-06-08T06:00:00Z",
"endUtcOffset": "-14400s"
},
"type": "STAGES",
"stages": [
{
"startTime": "2026-06-07T22:00:00Z",
"startUtcOffset": "-14400s",
"endTime": "2026-06-07T22:30:00Z",
"endUtcOffset": "-14400s",
"type": "LIGHT"
},
{
"startTime": "2026-06-07T22:30:00Z",
"startUtcOffset": "-14400s",
"endTime": "2026-06-07T23:45:00Z",
"endUtcOffset": "-14400s",
"type": "DEEP"
},
{
"startTime": "2026-06-07T23:45:00Z",
"startUtcOffset": "-14400s",
"endTime": "2026-06-08T02:15:00Z",
"endUtcOffset": "-14400s",
"type": "LIGHT"
},
{
"startTime": "2026-06-08T02:15:00Z",
"startUtcOffset": "-14400s",
"endTime": "2026-06-08T02:45:00Z",
"endUtcOffset": "-14400s",
"type": "REM"
},
{
"startTime": "2026-06-08T02:45:00Z",
"startUtcOffset": "-14400s",
"endTime": "2026-06-08T05:15:00Z",
"endUtcOffset": "-14400s",
"type": "LIGHT"
},
{
"startTime": "2026-06-08T05:15:00Z",
"startUtcOffset": "-14400s",
"endTime": "2026-06-08T06:00:00Z",
"endUtcOffset": "-14400s",
"type": "REM"
}
]
}
}Risposta
{
"done": true,
"response": {
"@type": "type.googleapis.com/google.devicesandservices.health.v4.DataPoint",
"name": "users/user-id/dataTypes/sleep/dataPoints/data-point-id",
"sleep": {
"interval": {
"startTime": "2026-06-07T22:00:00Z",
"startUtcOffset": "-14400s",
"endTime": "2026-06-08T06:00:00Z",
"endUtcOffset": "-14400s"
},
"type": "STAGES",
"stages": [
{
"startTime": "2026-06-07T22:00:00Z",
"startUtcOffset": "-14400s",
"endTime": "2026-06-07T22:30:00Z",
"endUtcOffset": "-14400s",
"type": "LIGHT"
},
{
"startTime": "2026-06-07T22:30:00Z",
"startUtcOffset": "-14400s",
"endTime": "2026-06-07T23:45:00Z",
"endUtcOffset": "-14400s",
"type": "DEEP"
},
{
"startTime": "2026-06-07T23:45:00Z",
"startUtcOffset": "-14400s",
"endTime": "2026-06-08T02:15:00Z",
"endUtcOffset": "-14400s",
"type": "LIGHT"
},
{
"startTime": "2026-06-08T02:15:00Z",
"startUtcOffset": "-14400s",
"endTime": "2026-06-08T02:45:00Z",
"endUtcOffset": "-14400s",
"type": "REM"
},
{
"startTime": "2026-06-08T02:45:00Z",
"startUtcOffset": "-14400s",
"endTime": "2026-06-08T05:15:00Z",
"endUtcOffset": "-14400s",
"type": "LIGHT"
},
{
"startTime": "2026-06-08T05:15:00Z",
"startUtcOffset": "-14400s",
"endTime": "2026-06-08T06:00:00Z",
"endUtcOffset": "-14400s",
"type": "REM"
}
]
}
}
}Metriche di efficienza e latenza del sonno
Oltre alle fasi del sonno e alle metriche fisiologiche, l'API fornisce metriche chiave che quantificano la qualità del sonno e l'addormentamento. L'efficienza del sonno e la latenza di insorgenza del sonno sono metriche cliniche standard che descrivono l'efficacia del riposo di un utente rispetto al tempo totale trascorso a letto, fornendo informazioni sull'igiene del sonno e sul riposo.
Punteggio di efficienza del sonno
L'efficienza del sonno è una metrica standard definita come la percentuale di tempo trascorso dormendo rispetto al tempo totale trascorso a letto. L'API calcola l'efficienza del sonno utilizzando la seguente formula:
Sleep Efficiency Score = round( (Total Minutes Asleep / Total Minutes In Bed) * 100 )
Il punteggio di efficienza viene calcolato appena prima della suddivisione dei livelli (fasi) del sonno. I minuti totali di sonno restituiti nella risposta dell'API (nel campo summary.minutesAsleep) riflettono il risultato finale dopo il calcolo dei livelli di sonno.
Se un utente o un ricercatore modifica manualmente l'ora di inizio o di fine di un log del sonno, l'API ricalcola il punteggio di efficienza del sonno e regola le partizioni delle fasi in base ai dati dei sensori registrati entro i nuovi limiti di ora di andare a dormire e ora di sveglia.
Latenza di inizio del sonno
La latenza di addormentamento misura il tempo trascorso dal momento in cui un utente intende addormentarsi (l'inizio del tempo "a letto" o "luci spente") fino all'addormentamento.
Per i log generati automaticamente (metadata.manuallyEdited è false),
summary.minutesToFallAsleep viene impostato su "0" per impostazione predefinita perché non è stata registrata alcuna intenzione esplicita di
addormentarsi. Quando le ore di inizio a letto vengono registrate o modificate manualmente
(metadata.manuallyEdited è true), l'API calcola e compila
summary.minutesToFallAsleep insieme a summary.minutesAfterWakeUp.
Indicazioni per la ricerca e il logging manuale
Quando i partecipanti registrano o regolano manualmente gli orari di inizio e di fine del riposo a letto:
- L'aggiornamento dei limiti di permanenza a letto modifica il sonno
interval(esummary.minutesInSleepPeriod). - I livelli del sonno e le partizioni delle fasi si regolano automaticamente per valutare i dati dei sensori all'interno della nuova finestra.
- Il punteggio di efficienza del sonno,
summary.minutesToFallAsleepesummary.minutesAfterWakeUpvengono ricalcolati in base alla finestra temporale aggiornata.
Deviazioni giornaliere della temperatura durante il sonno
Le derivazioni della temperatura durante il sonno giornaliere misurano la variazione della temperatura cutanea di un utente durante il sonno rispetto alla temperatura basale. In genere, questi dati vengono riportati una volta al giorno dopo una sessione di sonno principale.
Frequenza respiratoria
La frequenza respiratoria misura i respiri al minuto dell'utente. Durante il sonno, è una metrica chiave per monitorare la qualità del sonno e potenziali disturbi. L'API supporta la frequenza respiratoria di esempio (respiratory-rate), i riepiloghi giornalieri (daily-respiratory-rate) e i riepiloghi relativi al sonno a livello di sessione (respiratory-rate-sleep-summary).
Variabilità del battito cardiaco (HRV)
La variabilità della frequenza cardiaca (HRV) misura la variazione nel tempo tra un battito cardiaco e l'altro. È un indicatore chiave dello stato del sistema nervoso autonomo; una HRV elevata durante il sonno generalmente indica un recupero e una prontezza migliori, mentre una HRV bassa può indicare stress o sovrallenamento. L'API supporta la HRV di esempio (heart-rate-variability)
e i riepiloghi giornalieri (daily-heart-rate-variability).
Saturazione di ossigeno
La saturazione di ossigeno nel sangue (SpO2) rappresenta la percentuale di emoglobina satura di ossigeno in relazione all'emoglobina totale nel sangue. Il monitoraggio della SpO2 durante il sonno aiuta a rilevare potenziali disturbi della respirazione e conferma se l'utente mantiene livelli di ossigeno adeguati per tutta la notte. L'API supporta
la SpO2 di esempio (oxygen-saturation) e i riepiloghi giornalieri
(daily-oxygen-saturation).
Quando esegui una query su oxygen-saturation a livello di minuto, l'API Google Health restituisce solo i punti dati convalidati e filtra le misurazioni non valide causate dal movimento del braccio, da un'aderenza non corretta al polso o da una bassa affidabilità del sensore (inferiore al 50%), nonché le letture adiacenti al rumore di movimento. Poiché i minuti non validi sono esclusi,
la copertura a livello di minuto può essere scarsa e sono previsti intervalli di timestamp. Sia oxygen-saturation che daily-oxygen-saturation si basano sulle stesse letture convalidate. Per informazioni dettagliate sui criteri di convalida, consulta Filtro SpO2 a livello di minuto e validità dei dati.
Visione olistica della salute e del recupero del sonno
Sebbene ogni metrica fornisca informazioni specifiche, sono tutte profondamente correlate e insieme offrono una visione olistica del recupero di un utente. Le fasi del sonno (leggero, profondo, REM) forniscono la base strutturale del riposo, mentre gli indicatori fisiologici come la HRV e la SpO2 indicano come il corpo risponde fisicamente a questo riposo. Ad esempio, una sessione di sonno di alta qualità con un sonno profondo ottimale spesso è correlata a un HRV più elevato, il che indica un recupero efficace del sistema nervoso autonomo.
La combinazione di questi dati con le derivazioni della frequenza respiratoria e della temperatura durante il sonno consente alle applicazioni di identificare potenziali disturbi. Un picco improvviso della frequenza respiratoria o una deviazione della temperatura durante il sonno possono spiegare perché un utente potrebbe aver trascorso meno tempo nelle fasi di sonno ristoratore. Analizzando questi tipi di dati in tandem, gli sviluppatori possono fornire una valutazione completa dell'igiene del sonno e delle tendenze di salute a lungo termine.
Linee guida
Quando integri le metriche del sonno nella tua app, segui queste linee guida:
- Dettagli della sessione: per mostrare le fasi del sonno di un utente (leggero, profondo, REM, sveglio) e i brevi risvegli, esegui una query sul tipo di dati
sleep. - Risvegli notturni: per monitorare gli eventi di risveglio notturno senza flussi di sensori non elaborati, controlla gli intervalli delle fasi
sleepe filtra gli elementi contype: "AWAKE"(sia per i diari del sonnoSTAGESche per quelliCLASSIC) o controllaoutOfBedSegments. - Latenza ed efficienza: utilizza
summary.minutesToFallAsleepe la formula dell'efficienza del sonno per l'analisi della latenza del sonno. Tieni presente chesummary.minutesToFallAsleepviene compilato quando i diari del sonno vengono modificati manualmente (metadata.manuallyEditedètrue) o registrati esplicitamente. - Monitoraggio fisiologico: per un monitoraggio avanzato della salute, combina i dati della sessione di sonno con le metriche fisiologiche e di recupero, come
respiratory-rate-sleep-summary,daily-sleep-temperature-derivations,daily-heart-rate-variabilityedaily-oxygen-saturation. - Riconciliazione: utilizza l'operazione
reconcileper assicurarti che i diari del sonno sovrapposti di dispositivi diversi (ad esempio un indossabile e un sensore del materasso) vengano uniti in un unico record del sonno "principale".
Calcola il tempo totale trascorso in sonno profondo
Per calcolare il tempo totale trascorso da un utente in una fase di sonno profondo ristoratore per una notte specifica:
- Esegui una query sul tipo di dati
sleepper l'intervallo di tempo specificato. - Esegui l'iterazione dell'elenco delle fasi e identifica gli intervalli in cui
typeèDEEP. - Calcola la durata (ora di fine - ora di inizio) per ogni intervallo di sonno profondo e somma i valori.
La somma risultante fornisce la durata fisica totale del sonno profondo per quella sessione.