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.

Esempio

{
  "name": "sleeps/12345",
  "startTime": "2026-04-20T22:30:00Z",
  "endTime": "2026-04-21T06:30:00Z",
  "sleepType": "STAGES",
  "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"
        }
      ]
    }
  }
}

Derivazioni della temperatura del sonno giornaliera

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.
  • 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 stageType è 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