Desenvolver experiências de sono com a API Google Health

A API Google Health oferece tipos de dados que rastreiam os padrões de sono de um usuário, incluindo duração, qualidade e métricas fisiológicas durante o descanso. Essas métricas ajudam os aplicativos a fornecer insights sobre recuperação, higiene do sono e tendências de saúde de longo prazo.

Métricas fisiológicas, como variabilidade da frequência cardíaca (VFC), saturação de oxigênio (SpO₂) e frequência respiratória, são registradas especificamente durante o sono porque o corpo está em um estado estável de descanso. Isso permite que a API capture um valor de referência da saúde autonômica e respiratória do usuário sem a interferência de fatores estressantes diurnos, atividade física ou condições ambientais variáveis.

Entenda as diferenças entre esses tipos de dados para determinar quais métricas são adequadas ao seu aplicativo.

Tipos de dados compatíveis

A API é compatível com os seguintes tipos de dados para medir o sono:

Tabela: tipos de dados de sono da API Google Health
Tipo de dado Operações
disponíveis		 Escopo
Variabilidade da frequência cardíaca diária
dataType:daily-heart-rate-variability
filter parameter:daily_heart_rate_variability
Tipo de registro : diário

Dispositivos compatíveis
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Saturação de oxigênio diária
dataType:daily-oxygen-saturation
filter parameter:daily_oxygen_saturation
Tipo de registro : diário

Dispositivos compatíveis
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Frequência respiratória diária
dataType:daily-respiratory-rate
filter parameter:daily_respiratory_rate
Tipo de registro : diário

Dispositivos compatíveis
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Derivações diárias da temperatura do sono
dataType:daily-sleep-temperature-derivations
filter parameter:daily_sleep_temperature_derivations
Tipo de registro : diário

Dispositivos compatíveis
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Variabilidade da frequência cardíaca
dataType:heart-rate-variability
filter parameter:heart_rate_variability
Tipo de registro : Exemplo

Dispositivos compatíveis
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Saturação de oxigênio
dataType:oxygen-saturation
filter parameter:oxygen_saturation
Tipo de registro : Exemplo

Dispositivos compatíveis
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Resumo do sono com ritmo respiratório
dataType:respiratory-rate-sleep-summary
filter parameter:respiratory_rate_sleep_summary
Tipo de registro : Exemplo

Dispositivos compatíveis
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Dormir
dataType:sleep
filter parameter:sleep
Tipo de registro : sessão

Dispositivos compatíveis
list, get, reconcile, create, update, batchDelete .sleep.readonly
.sleep.writeonly

Sessões de sono e pequenos despertares

Uma sessão de sono (Sleep) representa um evento de sono discreto, como uma noite de sono ou uma soneca diurna. Ele inclui um detalhamento detalhado dos estágios do sono não sobrepostos e intervalos breves de transição de vigília, conhecidos como pequenos despertares.

  • Sessão de sono (Sleep): representa um evento de sono discreto (intervalos de estágio LIGHT, DEEP, REM, AWAKE) que particionam a linha do tempo contígua do descanso principal.
  • Despertares curtos (shortAwakenings): transições breves de despertar ou despertares que ocorrem durante o descanso. Ao contrário dos intervalos padrão de estágios de sono AWAKE (que dividem a progressão contígua e não sobreposta dos estágios do sono), os despertares curtos são segmentos distintos que podem se sobrepor aos estágios do sono ao redor. Eles oferecem visibilidade granular sobre a agitação e os microdespertares sem interromper a estrutura principal dos estágios do sono.

Exemplo

{
  "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"
    }
  ]
}

Criar uma sessão de sono

Para criar uma entrada de sessão de sono, envie uma solicitação POST para o endpoint de pontos de dados sleep. A resposta inclui o campo name com o data-point-id, que pode ser usado em uma solicitação Update (Patch) ou Delete.

Solicitação

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"
      }
    ]
  }
}

Resposta

{
  "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"
        }
      ]
    }
  }
}

Derivações diárias da temperatura do sono

As derivações diárias de temperatura do sono medem a variação na temperatura da pele de um usuário durante o sono em comparação com o valor de referência. Esses dados costumam ser informados uma vez por dia após uma sessão de sono longa.

Ritmo respiratório

A frequência respiratória mede as respirações do usuário por minuto. Durante o sono, ela é uma métrica importante para monitorar a qualidade do sono e possíveis distúrbios. A API é compatível com ritmo respiratório de amostra (respiratory-rate), resumos diários (daily-respiratory-rate) e resumos de sono no nível da sessão (respiratory-rate-sleep-summary).

Variabilidade da frequência cardíaca (VFC)

A VFC mede a variação de tempo entre cada batimento cardíaco. Ela é um indicador importante do estado do sistema nervoso autônomo. Uma VFC alta durante o sono geralmente significa melhor recuperação e disposição, enquanto uma VFC baixa pode indicar estresse ou treino em excesso. A API é compatível com amostras de VRC (heart-rate-variability) e resumos diários (daily-heart-rate-variability).

Saturação de oxigênio (SpO₂)

A SpO₂ representa a porcentagem de hemoglobina saturada de oxigênio em relação à hemoglobina total no sangue. O monitoramento da SpO₂ durante o sono é fundamental para detectar possíveis distúrbios respiratórios e garantir que o usuário mantenha níveis adequados de oxigênio durante a noite. A API é compatível com amostras de SpO₂ (oxygen-saturation) e resumos diários (daily-oxygen-saturation).

Visão completa da saúde e recuperação do sono

Embora cada métrica forneça insights específicos, elas estão profundamente inter-relacionadas e, juntas, oferecem uma visão holística da recuperação de um usuário. Os estágios de sono (leve, profundo, REM) fornecem a base estrutural do descanso, enquanto os marcadores fisiológicos, como VFC e SpO₂, indicam como o corpo está respondendo fisicamente a esse descanso. Por exemplo, uma sessão de sono de alta qualidade com sono profundo ideal geralmente se correlaciona com uma VFC mais alta, o que significa uma recuperação eficaz do sistema nervoso autônomo.

A combinação desses dados com a frequência respiratória e as derivações de temperatura do sono permite que os aplicativos identifiquem possíveis distúrbios. Um aumento repentino na frequência respiratória ou um desvio na temperatura do sono podem contextualizar por que um usuário passou menos tempo em estágios restauradores. Ao analisar esses tipos de dados em conjunto, os desenvolvedores podem fornecer uma avaliação abrangente da higiene do sono e das tendências de saúde de longo prazo.

Diretrizes

Ao integrar métricas de sono no seu app, use estas diretrizes:

  • Detalhes da sessão: para mostrar os estágios de sono de um usuário (leve, profundo, REM, acordado) e pequenos despertares, consulte o tipo de dados sleep.
  • Monitoramento fisiológico: para um monitoramento avançado da saúde, combine os dados da sessão de sono com métricas fisiológicas e de recuperação, como respiratory-rate-sleep-summary, daily-sleep-temperature-derivations, daily-heart-rate-variability e daily-oxygen-saturation.
  • Conciliação: use a operação reconcile para garantir que registros de sono sobrepostos de dispositivos diferentes (por exemplo, um wearable e um sensor de colchão) sejam mesclados em um único registro de sono "principal".

Calcular o tempo total de sono profundo

Para calcular o tempo total que um usuário passou em um estágio de sono profundo restaurador em uma noite específica:

  1. Consulte o tipo de dados sleep para o período especificado.
  2. Itere a lista de estágios e identifique os intervalos em que stageType é DEEP.
  3. Calcule a duração (horário de término - horário de início) de cada intervalo de sono profundo e some esses valores.

A soma resultante fornece a duração física total do sono profundo para essa sessão.

Anterior
Etapas