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
lista, reconciliar .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.
  • Despertares nocturnos: Los despertares a mitad de la noche (como levantarse para beber agua) se identifican mediante la fusión de sensores integrado en el dispositivo (acelerómetro, giroscopio y recuento de pasos). En la API web, las aplicaciones pueden detectar los despertares nocturnos filtrando los intervalos marcados con el nivel "wake" (sueño clásico) o "awake" (sueño por etapas).

Ejemplo

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

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

Métricas de eficiencia y latencia del sueño

Además de las fases del sueño y las métricas fisiológicas, la API proporciona métricas clave que cuantifican la calidad del sueño y el inicio del sueño. La eficiencia del sueño y la latencia del inicio del sueño son métricas clínicas estándar que describen la eficacia con la que un usuario descansa en relación con el tiempo total que pasa en la cama, lo que proporciona información sobre la higiene del sueño y el descanso.

Puntuación de eficiencia del sueño

La eficiencia del sueño es una métrica estándar que se define como la proporción de tiempo que pasaste durmiendo en relación con el tiempo total que pasaste en la cama. La API calcula la eficiencia del sueño con la siguiente fórmula:

Sleep Efficiency Score = round( (Total Minutes Asleep / Total Minutes In Bed) * 100 )

La puntuación de eficiencia se calcula justo antes de la partición de los niveles (etapas) de sueño. Los minutos totales de sueño que se muestran en la respuesta de la API (en el campo summary.minutesAsleep) reflejan el resultado final después de que se calculan los niveles de sueño.

Si un usuario o investigador modifica manualmente la hora de inicio o finalización de un registro de sueño, la API vuelve a calcular la puntuación de eficiencia del sueño y ajusta las particiones de las etapas según los datos del sensor registrados dentro del nuevo límite de hora de acostarse y hora de despertarse.

Latencia del inicio del sueño

La latencia del inicio del sueño mide el tiempo transcurrido desde que un usuario intenta dormirse (el inicio del tiempo "en la cama" o "luces apagadas") hasta que se produce el inicio del sueño.

En el caso de los registros que se generan automáticamente con la autodetección (auto_detect), minutesToFallAsleep se establece de forma predeterminada en 0 porque no se registró ninguna intención explícita de quedarse dormido. Cuando se registran o editan manualmente las horas de inicio en la cama (lo que convierte el registro en manual), la API calcula y completa minutesToFallAsleep junto con minutesAfterWakeup.

Orientación para la investigación y el registro manual

Cuando los participantes graban o ajustan manualmente las horas de inicio y finalización integradas:

  1. La actualización de los límites en la cama cambia el intervalo de timeInBed.
  2. Los niveles de sueño y las particiones de etapas se ajustan automáticamente para evaluar los datos del sensor dentro de la nueva ventana.
  3. La puntuación de eficiencia del sueño, minutesToFallAsleep y minutesAfterWakeup se vuelven a derivar en función del período actualizado.

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.
  • Despertares nocturnos: Para hacer un seguimiento de los eventos de despertar a mitad de la noche sin transmisiones de sensores sin procesar, inspecciona los intervalos de la etapa sleep y filtra los elementos con el tipo de etapa AWAKE (o wake para los registros de sueño clásicos).
  • Latencia y eficiencia: Usa minutesToFallAsleep y la fórmula de eficiencia del sueño para el análisis de la latencia del sueño. Ten en cuenta que minutesToFallAsleep se completa cuando los registros de sueño se editan manualmente o se registran de forma explícita.
  • 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 type 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