Desarrolla experiencias de sueño con la API de Google Health

La API de Google Health proporciona tipos de datos que registran los patrones de sueño de un usuario, incluidas la duración, la calidad y las métricas fisiológicas durante el descanso. Estas métricas ayudan a las aplicaciones a proporcionar estadísticas sobre la recuperación, la higiene del sueño y las tendencias de salud a largo plazo.

Las métricas fisiológicas, como la variabilidad de la frecuencia cardíaca (VFC), la saturación de oxígeno (SpO2) y la frecuencia respiratoria, se registran específicamente durante el sueño, ya que el cuerpo se encuentra en un estado de reposo estable. Esto permite que la API capture una línea de base de la salud autónoma y respiratoria del usuario sin la interferencia de factores estresantes diurnos, actividad física o condiciones ambientales variables.

Comprende las diferencias entre estos tipos de datos para determinar qué métricas se adaptan mejor a tu aplicación.

Tipos de datos admitidos

La API admite los siguientes tipos de datos para medir el sueño:

Tabla: Tipos de datos de sueño de la API de Google Health
Tipo de datos Operaciones
disponibles		 Alcance
Variabilidad de la frecuencia cardíaca diaria
dataType: daily-heart-rate-variability
parámetro de filtro: daily_heart_rate_variability
Tipo de registro: Diario

Dispositivos compatibles
lista, reconciliar .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Saturación de oxígeno diaria
dataType: daily-oxygen-saturation
parámetro de filtro: daily_oxygen_saturation
Tipo de registro: Diario

Dispositivos compatibles
lista, reconciliar .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Frecuencia respiratoria diaria
dataType: daily-respiratory-rate
parámetro de filtro: daily_respiratory_rate
Tipo de registro: Diario

Dispositivos compatibles
lista, reconciliar .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Derivaciones diarias de la temperatura durante el sueño
dataType: daily-sleep-temperature-derivations
parámetro de filtro: daily_sleep_temperature_derivations
Tipo de registro: Diario

Dispositivos compatibles
lista, reconciliar .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Variabilidad de la frecuencia cardíaca
dataType: heart-rate-variability
parámetro de filtro: heart_rate_variability
Tipo de registro: Muestra

Dispositivos compatibles
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Saturación de oxígeno
dataType: oxygen-saturation
parámetro de filtro: oxygen_saturation
Tipo de registro: Muestra

Dispositivos compatibles
lista, reconciliar .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Resumen de sueño de la frecuencia respiratoria
dataType: respiratory-rate-sleep-summary
parámetro de filtro: respiratory_rate_sleep_summary
Tipo de registro: Muestra

Dispositivos compatibles
lista, reconciliar .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Sueño
dataType: sleep
parámetro de filtro: sleep
Tipo de registro: Sesión

Dispositivos compatibles
list, get, reconcile, create, update, batchDelete .sleep.readonly
.sleep.writeonly

Sesiones de sueño y despertares breves

Una sesión de sueño (Sleep) representa un evento de sueño discreto, como una sola noche de sueño o una siesta diurna. Incluye un desglose detallado de las fases de sueño que no se superponen, junto con intervalos breves de transición al despertar conocidos como despertares cortos.

  • Sesión de sueño (Sleep): Representa un evento de sueño discreto (intervalos de las etapas LIGHT, DEEP, REM y AWAKE) que particionan la línea de tiempo contigua del descanso principal.
  • Despertares breves (shortAwakenings): Transiciones breves al estado de vigilia o despertares que ocurren durante el descanso. A diferencia de los intervalos de la etapa AWAKE estándar (que dividen la progresión contigua y no superpuesta de las etapas del sueño), los despertares breves son segmentos distintos que pueden superponerse con las etapas del sueño circundantes. Proporcionan visibilidad detallada sobre la inquietud y los microdespertares sin interrumpir la estructura principal de las etapas del sueño.

Ejemplo

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

Cómo crear una sesión de sueño

Para crear una entrada de sesión de sueño, envía una solicitud POST al extremo de puntos de datos sleep. La respuesta incluye el campo name que contiene el data-point-id, que se puede usar en una solicitud de actualización (parche) o eliminación.

Solicitud

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

Respuesta

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

Derivaciones diarias de la temperatura durante el sueño

Las Derivaciones de temperatura del sueño diarias miden la variación de la temperatura cutánea de un usuario durante el sueño en comparación con su valor de referencia. Por lo general, estos datos se registran una vez al día después de una sesión de sueño importante.

Frecuencia respiratoria

La frecuencia respiratoria mide las respiraciones del usuario por minuto. Durante el sueño, es una métrica clave para supervisar la calidad del sueño y las posibles interrupciones. La API admite muestras de la frecuencia respiratoria (respiratory-rate), resúmenes diarios (daily-respiratory-rate) y resúmenes del sueño a nivel de la sesión (respiratory-rate-sleep-summary).

Variabilidad de la frecuencia cardíaca (VFC)

La VFC mide la variación de tiempo entre cada latido. Es un indicador clave del estado del sistema nervioso autónomo. Una VFC alta durante el sueño generalmente significa una mejor recuperación y preparación, mientras que una VFC baja puede indicar estrés o sobreentrenamiento. La API admite muestras de VFC (heart-rate-variability) y resúmenes diarios (daily-heart-rate-variability).

Saturación de oxígeno (SpO2)

El SpO2 representa el porcentaje de hemoglobina saturada de oxígeno en relación con la hemoglobina total en la sangre. Monitorear la SpO2 durante el sueño es fundamental para detectar posibles alteraciones respiratorias y garantizar que el usuario mantenga niveles de oxígeno adecuados durante la noche. La API admite muestras de SpO2 (oxygen-saturation) y resúmenes diarios (daily-oxygen-saturation).

Vista integral de la salud y la recuperación del sueño

Si bien cada métrica proporciona estadísticas específicas, están profundamente interrelacionadas y, juntas, ofrecen una visión integral de la recuperación de un usuario. Las fases de sueño (ligero, profundo y REM) proporcionan la base estructural del descanso, mientras que los indicadores fisiológicos, como la VFC y la SpO2, indican cómo responde el cuerpo físicamente a ese descanso. Por ejemplo, una sesión de sueño de alta calidad con un sueño profundo óptimo suele correlacionarse con una mayor VRC, lo que significa una recuperación eficaz del sistema nervioso autónomo.

Si se combinan con las derivaciones de la frecuencia respiratoria y la temperatura durante el sueño, las aplicaciones pueden identificar posibles interrupciones. Un aumento repentino en la frecuencia respiratoria o una desviación en la temperatura durante el sueño pueden contextualizar por qué un usuario podría haber pasado menos tiempo en las etapas reparadoras. Al analizar estos tipos de datos en conjunto, los desarrolladores pueden proporcionar una evaluación integral de la higiene del sueño y las tendencias de salud a largo plazo.

Lineamientos

Cuando integres métricas de sueño en tu app, usa estos lineamientos:

  • Detalle de la sesión: Para mostrar las fases del sueño de un usuario (ligero, profundo, REM, despierto) y los despertares breves, consulta el tipo de datos sleep.
  • Monitoreo fisiológico: Para un monitoreo avanzado de la salud, combina los datos de la sesión de sueño con métricas fisiológicas y de recuperación, como respiratory-rate-sleep-summary, daily-sleep-temperature-derivations, daily-heart-rate-variability y daily-oxygen-saturation.
  • Conciliación: Usa la operación reconcile para asegurarte de que los registros de sueño superpuestos de diferentes dispositivos (por ejemplo, un sensor para la muñeca y un sensor para el colchón) se combinen en un solo registro de sueño "principal".

Cómo calcular el tiempo total en sueño profundo

Para calcular el tiempo total que un usuario pasó en una etapa de sueño profundo reparador durante una noche específica, sigue estos pasos:

  1. Consulta el tipo de datos sleep para el período especificado.
  2. Itera en la lista de etapas y, luego, identifica los intervalos en los que stageType es DEEP.
  3. Calcula la duración (hora de finalización - hora de inicio) de cada intervalo de sueño profundo y súmalos.

La suma resultante proporciona la duración física total del sueño profundo para esa sesión.

Anterior
Pasos