Sviluppare esperienze di sonno con l'API Google Health

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:

Tabella: tipi di dati relativi al sonno dell'API Google Health
Tipo di dati Operazioni
disponibili
Ambito
Variabilità del battito cardiaco giornaliera
dataType: daily-heart-rate-variability
filter 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-saturation
filter 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-rate
filter 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-derivations
filter 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-variability
filter 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-saturation
filter 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-summary
filter 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: sleep
filter 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 fasi LIGHT, 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 fasi AWAKE standard (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 stages per gli intervalli con type: "AWAKE" (utilizzato sia nei diari del sonno CLASSIC che in quelli STAGES) o ispezionando outOfBedSegments.

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:

  1. L'aggiornamento dei limiti di permanenza a letto modifica il sonno interval (e summary.minutesInSleepPeriod).
  2. I livelli del sonno e le partizioni delle fasi si regolano automaticamente per valutare i dati dei sensori all'interno della nuova finestra.
  3. Il punteggio di efficienza del sonno, summary.minutesToFallAsleep e summary.minutesAfterWakeUp vengono 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 sleep e filtra gli elementi con type: "AWAKE" (sia per i diari del sonno STAGES che per quelli CLASSIC) o controlla outOfBedSegments.
  • Latenza ed efficienza: utilizza summary.minutesToFallAsleep e la formula dell'efficienza del sonno per l'analisi della latenza del sonno. Tieni presente che summary.minutesToFallAsleep viene 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-variability e daily-oxygen-saturation.
  • Riconciliazione: utilizza l'operazione reconcile per 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:

  1. Esegui una query sul tipo di dati sleep per l'intervallo di tempo specificato.
  2. Esegui l'iterazione dell'elenco delle fasi e identifica gli intervalli in cui type è DEEP.
  3. 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.