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

La API de Google Health proporciona tipos de datos que hacen un seguimiento de 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 estable y de reposo. Esto permite que la API capture un modelo de referencia de la salud autónoma y respiratoria del usuario sin la interferencia de los factores de estrés diurnos, la actividad física o las condiciones ambientales variables.

Comprende las diferencias entre estos tipos de datos para determinar qué métricas se adaptan 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 de
disponibles		 Alcance
Variabilidad de la frecuencia cardíaca diaria
dataType: daily-heart-rate-variability
filter parameter: daily_heart_rate_variability
Tipo de registro: Diario

Dispositivos compatibles
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Saturación de oxígeno diaria
dataType: daily-oxygen-saturation
filter parameter: daily_oxygen_saturation
Tipo de registro: Diario

Dispositivos compatibles
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Frecuencia respiratoria diaria
dataType: daily-respiratory-rate
filter parameter: daily_respiratory_rate
Tipo de registro: Diario

Dispositivos compatibles
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Daily Sleep Temperature Derivations
dataType: daily-sleep-temperature-derivations
filter parameter: daily_sleep_temperature_derivations
Tipo de registro: Diario

Dispositivos compatibles
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Variabilidad de la frecuencia cardíaca
dataType: heart-rate-variability
filter parameter: 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
filter parameter: oxygen_saturation
Tipo de registro: Muestra
Resolución de almacenamiento: 1 minuto

Dispositivos compatibles
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Resumen de sueño de la frecuencia respiratoria
dataType: respiratory-rate-sleep-summary
filter parameter: respiratory_rate_sleep_summary
Tipo de registro: Muestra

Dispositivos compatibles
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Sueño
dataType: sleep
filter parameter: 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 durante el día. Incluye un desglose detallado de las fases del sueño que no se superponen, junto con intervalos breves de transición de vigilia conocidos como despertares breves.

  • Sesión de sueño (Sleep): Representa un evento de sueño discreto (intervalos de etapas LIGHT, DEEP, REM y AWAKE) que dividen la línea de tiempo contigua del descanso principal.
  • Despertares breves (shortAwakenings): Transiciones breves de vigilia o despertares que ocurren durante el descanso. A diferencia de los intervalos de fase AWAKE estándar (que dividen la progresión de las fases del sueño contiguas que no se superponen), los despertares breves son segmentos distintos que pueden superponerse con las fases del sueño circundantes. Proporcionan visibilidad detallada de la inquietud y los microdespertares sin interrumpir la estructura principal de las fases del sueño.
  • Despertares nocturnos: Los despertares nocturnos (como levantarse para tomar agua) se identifican a través de la fusión de sensores integrados en el dispositivo (acelerómetro, giroscopio y recuento de pasos). Las aplicaciones pueden detectar despertares nocturnos filtrando stages por intervalos con type: "AWAKE" (que se usa en los registros de sueño de CLASSIC y STAGES) o inspeccionando outOfBedSegments.

Ejemplo

{
  "name": "users/user-id/dataTypes/sleep/dataPoints/data-point-id",
  "sleep": {
    "interval": {
      "startTime": "2026-04-20T22:30:00Z",
      "startUtcOffset": "-14400s",
      "endTime": "2026-04-21T06:30:00Z",
      "endUtcOffset": "-14400s"
    },
    "type": "STAGES",
    "stages": [
      {
        "startTime": "2026-04-20T22:30:00Z",
        "startUtcOffset": "-14400s",
        "endTime": "2026-04-20T23:45:00Z",
        "endUtcOffset": "-14400s",
        "type": "LIGHT"
      },
      {
        "startTime": "2026-04-20T23:45:00Z",
        "startUtcOffset": "-14400s",
        "endTime": "2026-04-21T01:15:00Z",
        "endUtcOffset": "-14400s",
        "type": "DEEP"
      }
    ],
    "shortAwakenings": [
      {
        "startTime": "2026-04-20T23:10:00Z",
        "startUtcOffset": "-14400s",
        "endTime": "2026-04-20T23:11:30Z",
        "endUtcOffset": "-14400s",
        "type": "AWAKE"
      }
    ],
    "summary": {
      "minutesInSleepPeriod": "480",
      "minutesAsleep": "455",
      "minutesAwake": "25",
      "minutesToFallAsleep": "15",
      "minutesAfterWakeUp": "10"
    }
  }
}

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 datos sleep. La respuesta incluye el campo name que contiene el data-point-id, que se puede usar en una solicitud Update (Patch) o Delete.

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 de 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 se pasa durmiendo en relación con el tiempo total que se pasa 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 de sueño (fases). La cantidad total de minutos de sueño que se muestra en la respuesta de la API (en el campo summary.minutesAsleep) refleja 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 de sensores registrados dentro del nuevo límite de hora de acostarse y de despertarse.

Latencia del inicio del sueño

La latencia de inicio del sueño mide el tiempo transcurrido desde que un usuario tiene la intención de quedarse dormido (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 generados automáticamente (metadata.manuallyEdited es false), summary.minutesToFallAsleep se establece de forma predeterminada en "0" porque no se registró ningún intento explícito de quedarse dormido. Cuando las horas de inicio en la cama se registran o editan de forma manual (metadata.manuallyEdited es true), la API calcula y propaga summary.minutesToFallAsleep junto con summary.minutesAfterWakeUp.

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

Cuando los participantes registran o ajustan manualmente las horas de inicio y finalización en la cama, ocurre lo siguiente:

  1. Actualizar los límites de tiempo en la cama cambia el interval (y el summary.minutesInSleepPeriod) del sueño.
  2. Los niveles de sueño y las particiones de las fases se ajustan automáticamente para evaluar los datos de los sensores dentro de la nueva ventana.
  3. La puntuación de eficiencia del sueño, summary.minutesToFallAsleep y summary.minutesAfterWakeUp se vuelven a calcular en función del período actualizado.

Desviaciones diarias de la temperatura durante el sueño

Las derivaciones de la temperatura durante el sueño diaria 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 informan una vez al día después de una sesión de sueño importante.

Frecuencia respiratoria

La frecuencia respiratoria mide las respiraciones por minuto del usuario. Durante el sueño, es una métrica clave para supervisar la calidad del sueño y las posibles alteraciones. La API admite la frecuencia respiratoria de muestra (respiratory-rate), los resúmenes diarios (daily-respiratory-rate) y los resúmenes de 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 suele indicar 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

La saturación de oxígeno en sangre (SpO2) representa el porcentaje de hemoglobina saturada de oxígeno en relación con la hemoglobina total en la sangre. La supervisión de la SpO2 durante el sueño ayuda a detectar posibles alteraciones de la respiración y confirma si el usuario mantiene niveles de oxígeno adecuados durante toda la noche. La API admite muestras de SpO2 (oxygen-saturation) y resúmenes diarios (daily-oxygen-saturation).

Cuando consultas oxygen-saturation a nivel de minuto, la API de Google Health devuelve solo los datos validados y filtra las mediciones no válidas causadas por el movimiento del brazo, un ajuste flojo en la muñeca o una confianza baja del sensor (menos del 50%), así como las lecturas adyacentes al ruido de movimiento. Debido a que se excluyen los minutos no válidos, la cobertura a nivel de minutos puede ser escasa y se esperan brechas en las marcas de tiempo. Tanto oxygen-saturation como daily-oxygen-saturation se basan en las mismas lecturas validadas. Para obtener detalles sobre los criterios de validación, consulta Filtrado de SpO2 por minuto y validez de los datos.

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

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

Combinar estos datos con las derivaciones de la frecuencia respiratoria y la temperatura durante el sueño permite que las aplicaciones identifiquen posibles alteraciones. Un aumento repentino de la frecuencia respiratoria o una desviación de la temperatura durante el sueño pueden contextualizar por qué un usuario podría haber pasado menos tiempo en las fases de recuperación. Si analizan 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 las métricas de sueño en tu app, sigue estos lineamientos:

  • Detalles 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 flujos de sensores sin procesar, inspecciona los intervalos de la etapa sleep y filtra los elementos con type: "AWAKE" (para los registros de sueño STAGES y CLASSIC) o inspecciona outOfBedSegments.
  • Latencia y eficiencia: Usa summary.minutesToFallAsleep y la fórmula de eficiencia del sueño para el análisis de la latencia del sueño. Ten en cuenta que summary.minutesToFallAsleep se propaga cuando los registros de sueño se editan manualmente (metadata.manuallyEdited es true) o se registran de forma explícita.
  • Supervisión fisiológica: Para una supervisión avanzada 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 wearable y un sensor de colchón) se combinen en un único registro de sueño "principal".

Calcular el tiempo total en sueño profundo

Para calcular el tiempo total que un usuario pasó en una fase de sueño profundo reparador durante una noche específica, haz lo siguiente:

  1. Consulta el tipo de datos sleep para el período especificado.
  2. Itera 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úmalas.

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

Anterior
Pasos
Siguiente
Salud de la mujer