Sviluppare esperienze di sonno con l'API Google Health

L'API Google Health fornisce tipi di dati che monitorano i pattern di sonno di un utente, inclusi durata, qualità e metriche fisiologiche durante il riposo. Queste metriche aiutano le applicazioni a fornire informazioni su recupero, igiene del sonno e tendenze di salute a lungo termine.

Le metriche fisiologiche come la variabilità del battito cardiaco (HRV), la saturazione dell'ossigeno (SpO2) e la frequenza respiratoria vengono registrate in modo specifico durante il sonno perché il corpo è in uno stato di riposo stabile. Ciò consente all'API di 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
list, reconcile .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
list, reconcile .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
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Derivazioni della temperatura del sonno giornaliera
dataType: daily-sleep-temperature-derivations
filter parameter: daily_sleep_temperature_derivations
Tipo di record: giornaliero

Dispositivi compatibili
list, reconcile .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
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Saturazione di ossigeno
dataType: oxygen-saturation
filter parameter: oxygen_saturation
Tipo di record: Esempio

Dispositivi compatibili
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Riepilogo del sonno della frequenza respiratoria
dataType: respiratory-rate-sleep-summary
filter parameter: respiratory_rate_sleep_summary
Tipo di record: Esempio

Dispositivi compatibili
list, reconcile .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 discreto, come un singolo sonno notturno o un pisolino diurno. Include un'analisi dettagliata delle fasi del sonno non sovrapposte, nonché brevi intervalli di transizione al risveglio noti come brevi risvegli.

  • Sessione di sonno (Sleep): rappresenta un evento di sonno discreto (intervalli di fase LIGHT, DEEP, REM, AWAKE) che partizionano la sequenza temporale contigua del riposo principale.
  • Risvegli brevi (shortAwakenings): brevi transizioni di veglia o risvegli che si verificano durante il riposo. A differenza degli intervalli di fase AWAKE standard (che dividono la progressione delle fasi del sonno contigue e non sovrapposte), i brevi risvegli sono segmenti distinti che possono sovrapporsi alle fasi del sonno circostanti. Forniscono una visibilità granulare su irrequietezza e microrisvegli senza interrompere la struttura principale delle fasi del sonno.
  • Risvegli notturni: i risvegli a metà notte (ad esempio per bere acqua) vengono identificati dalla fusione dei sensori sul dispositivo (accelerometro, giroscopio e numero di passi). Nell'API web, le applicazioni possono rilevare i risvegli notturni filtrando gli intervalli contrassegnati con il livello "wake" (sonno classico) o "awake" (fasi del sonno).

Esempio

{
  "name": "sleeps/12345",
  "startTime": "2026-04-20T22:30:00Z",
  "endTime": "2026-04-21T06:30:00Z",
  "sleepType": "STAGES",
  "minutesToFallAsleep": 15,
  "minutesAfterWakeup": 10,
  "sleepStages": [
    {
      "startTime": "2026-04-20T22:30:00Z",
      "endTime": "2026-04-20T23:45:00Z",
      "type": "LIGHT"
    },
    {
      "startTime": "2026-04-20T23:45:00Z",
      "endTime": "2026-04-21T01:15:00Z",
      "type": "DEEP"
    }
  ],
  "shortAwakenings": [
    {
      "startTime": "2026-04-20T23:10:00Z",
      "endTime": "2026-04-20T23:11:30Z",
      "type": "AWAKE"
    }
  ]
}

Creare una sessione di sonno

Per creare una voce della 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à e l'inizio del sonno. 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 proporzione 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 partizione dei livelli (fasi) del sonno. I minuti totali di sonno restituiti nella risposta 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 addormentamento

La latenza di addormentamento misura il tempo trascorso da quando un utente intende addormentarsi (l'inizio del periodo "a letto" o "luci spente") fino all'addormentamento.

Per i log generati automaticamente utilizzando il rilevamento automatico (auto_detect), minutesToFallAsleep è impostato su 0 per impostazione predefinita perché non è stata registrata alcuna intenzione esplicita di addormentarsi. Quando gli orari di inizio a letto vengono registrati o modificati manualmente (convertendo il log in manual), l'API calcola e compila minutesToFallAsleep insieme a minutesAfterWakeup.

Indicazioni per la ricerca e la registrazione manuale

Quando i partecipanti registrano o modificano manualmente gli orari di inizio e fine del sonno:

  1. L'aggiornamento dei confini nel letto modifica l'intervallo timeInBed.
  2. I livelli di sonno e le partizioni delle fasi si regolano automaticamente per valutare i dati del sensore all'interno della nuova finestra.
  3. Il punteggio di efficienza del sonno, minutesToFallAsleep e minutesAfterWakeup vengono ricalcolati in base alla finestra temporale aggiornata.

Derivazioni giornaliere della temperatura del sonno

Le derivazioni della temperatura del sonno giornaliera misurano la variazione della temperatura cutanea di un utente durante il sonno rispetto alla sua temperatura basale. Questi dati vengono in genere 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 i potenziali disturbi. L'API supporta la frequenza respiratoria campionata (respiratory-rate), i riepiloghi giornalieri (daily-respiratory-rate) e i riepiloghi del sonno a livello di sessione (respiratory-rate-sleep-summary).

Variabilità del battito cardiaco (HRV)

La variabilità della frequenza cardiaca 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 migliore recupero e preparazione, mentre una HRV bassa può indicare stress o sovrallenamento. L'API supporta l'HRV di esempio (heart-rate-variability) e i riepiloghi giornalieri (daily-heart-rate-variability).

Saturazione di ossigeno (SpO2)

La SpO2 rappresenta la percentuale di emoglobina satura di ossigeno rispetto all'emoglobina totale nel sangue. Il monitoraggio della SpO2 durante il sonno è fondamentale per rilevare potenziali disturbi respiratori e garantire che l'utente mantenga livelli di ossigeno adeguati durante la notte. L'API supporta campioni di SpO2 (oxygen-saturation) e riepiloghi giornalieri (daily-oxygen-saturation).

Visione olistica della salute del sonno e del recupero

Sebbene ogni metrica fornisca informazioni specifiche, sono profondamente correlate e insieme offrono una visione olistica del recupero di un utente. Le fasi del sonno (leggero, profondo, REM) forniscono le basi strutturali del riposo, mentre i marcatori fisiologici come la variabilità della frequenza cardiaca 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 una variabilità della frequenza cardiaca più elevata, che indica un recupero efficace del sistema nervoso autonomo.

La combinazione di questi dati con la frequenza respiratoria e le derivazioni della temperatura del sonno consente alle applicazioni di identificare potenziali disturbi. Un aumento improvviso della frequenza respiratoria o una deviazione della temperatura del sonno possono contestualizzare il motivo per cui un utente potrebbe aver trascorso meno tempo nelle fasi di recupero. Analizzando questi tipi di dati insieme, gli sviluppatori possono fornire una valutazione completa dell'igiene del sonno e delle tendenze sanitarie a lungo termine.

Linee guida

Quando integri le metriche del sonno nella tua app, utilizza queste linee guida:

  • Dettaglio 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 a mezzanotte senza flussi di sensori grezzi, esamina gli intervalli della fase sleep e filtra gli elementi con il tipo di fase AWAKE (o wake per i log del sonno classici).
  • Latenza ed efficienza: utilizza minutesToFallAsleep e la formula dell'efficienza del sonno per l'analisi della latenza del sonno. Tieni presente che minutesToFallAsleep viene compilato quando i log del sonno vengono modificati manualmente o registrati in modo esplicito.
  • Monitoraggio fisiologico: per un monitoraggio avanzato della salute, combina i dati della sessione di sonno con 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 log del sonno sovrapposti di dispositivi diversi (ad esempio un dispositivo indossabile e un sensore per il materasso) vengano uniti in un unico record del sonno "principale".

Calcolare il tempo totale di 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. Scorri l'elenco delle fasi e identifica gli intervalli in cui type è DEEP.
  3. Calcola la durata (ora di fine - ora di inizio) di ogni intervallo di sonno profondo e sommala.

La somma risultante fornisce la durata fisica totale del sonno profondo per quella sessione.

Indietro
Passaggi