Develop sleep experiences with Google Health API

The Google Health API provides data types that track a user's sleep patterns, including duration, quality, and physiological metrics during rest. These metrics help applications provide insights into recovery, sleep hygiene, and long-term health trends.

Physiological metrics such as Heart Rate Variability (HRV), Oxygen Saturation (SpO2), and respiratory rate are recorded specifically during sleep because the body is in a stable, resting state. This allows the API to capture a baseline of the user's autonomic and respiratory health without the interference of daytime stressors, physical activity, or varying environmental conditions.

Understand the differences between these data types to determine which metrics suit your application.

Supported data types

The API supports the following data types for measuring sleep:

Sleep sessions and short awakenings

A Sleep Session (Sleep) represents a discrete sleep event, such as a single nightly sleep or a daytime nap. It includes a detailed breakdown of non-overlapping sleep stages alongside brief wake transition intervals known as short awakenings.

• Sleep Session (Sleep): Represents a discrete sleep event (LIGHT, DEEP, REM, AWAKE stage intervals) that partition the contiguous timeline of the primary rest.
• Short Awakenings (shortAwakenings): Brief wake transitions or awakenings that occur during rest. Unlike standard AWAKE stage intervals (which divide the non-overlapping contiguous sleep stage progression), short awakenings are distinct segments that can overlap with surrounding sleep stages. They provide granular visibility into restlessness and micro-awakenings without disrupting the primary sleep stage structure.
• Nocturnal Awakenings: Mid-night awakenings (such as getting up for water) are identified by on-device sensor fusion (accelerometer, gyroscope, and step count). In the Web API, applications can detect nocturnal awakenings by filtering for intervals marked with level "wake" (classic sleep) or "awake" (stages sleep).

Example

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

Create a sleep session

To create a sleep session entry, send a POST request to the sleep data points endpoint. The response includes the name field containing the data-point-id, which can be used in an Update (Patch) or Delete request.

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

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

Sleep efficiency and latency metrics

In addition to sleep stages and physiological metrics, the API provides key metrics that quantify sleep quality and sleep onset. Sleep efficiency and sleep onset latency are standard clinical metrics that describe how effectively a user rests relative to their total time in bed, providing insight into sleep hygiene and restfulness.

Sleep efficiency score

Sleep efficiency is a standard metric defined as the proportion of time spent asleep relative to total time spent in bed. The API computes sleep efficiency using the following formula:

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

The efficiency score is calculated just before sleep level (stages) partitioning. The total minutes asleep returned in the API response (in the summary.minutesAsleep field) reflects the final result after sleep levels are computed.

If a user or researcher manually modifies the start or end time of a sleep log, the API recalculates the sleep efficiency score and adjusts stage partitions according to sensor data recorded within the new bedtime and waketime boundary.

Sleep onset latency

Sleep onset latency measures the time elapsed from when a user intends to fall asleep (the start of "in bed" or "lights out" time) until sleep onset occurs.

For logs generated automatically using auto-detection (auto_detect), minutesToFallAsleep defaults to 0 because no explicit intent to fall asleep was logged. When in-bed start times are manually recorded or edited (converting the log to manual), the API computes and populates minutesToFallAsleep along with minutesAfterWakeup.

Guidance for research and manual logging

When participants manually record or adjust in-bed start and end times:

1. Updating in-bed boundaries changes the timeInBed interval.
2. Sleep levels and stage partitions automatically adjust to evaluate sensor data within the new window.
3. Sleep efficiency score, minutesToFallAsleep, and minutesAfterWakeup are re-derived based on the updated time window.

Daily sleep temperature derivations

Daily Sleep Temperature Derivations measure the variation in a user's skin temperature during sleep compared to their baseline. This data is typically reported once per day after a major sleep session.

Respiratory rate

Respiratory rate measures the user's breaths per minute. During sleep, it is a key metric for monitoring sleep quality and potential disturbances. The API supports sample respiratory rate (respiratory-rate), daily summaries (daily-respiratory-rate), and session-level sleep summaries (respiratory-rate-sleep-summary).

Heart rate variability (HRV)

HRV measures the variation in time between each heartbeat. It is a key indicator of the autonomic nervous system's state; high HRV during sleep generally signifies better recovery and readiness, while low HRV can indicate stress or overtraining. The API supports sample HRV (heart-rate-variability) and daily summaries (daily-heart-rate-variability).

Oxygen saturation (SpO2)

SpO2 represents the percentage of oxygen-saturated hemoglobin relative to total hemoglobin in the blood. Monitoring SpO2 during sleep is critical for detecting potential breathing disturbances and ensuring the user is maintaining adequate oxygen levels throughout the night. The API supports sample SpO2 (oxygen-saturation) and daily summaries (daily-oxygen-saturation).

Holistic view of sleep health and recovery

While each metric provides specific insights, they are deeply interrelated and together offer a holistic view of a user's recovery. Sleep stages (Light, Deep, REM) provide the structural foundation of rest, while physiological markers like HRV and SpO2 indicate how the body is physically responding to that rest. For example, a high-quality sleep session with optimal Deep sleep often correlates with higher HRV, signifying effective recovery of the autonomic nervous system.

Combining these with respiratory rate and sleep temperature derivations allows applications to identify potential disturbances. A sudden spike in respiratory rate or a deviation in sleep temperature can contextualize why a user might have spent less time in restorative stages. By analyzing these data types in tandem, developers can provide a comprehensive assessment of sleep hygiene and long-term health trends.

Guidelines

When integrating sleep metrics in your app, use these guidelines:

• Session Detail: To show a user's sleep stages (Light, Deep, REM, Awake) and short awakenings, query the sleep data type.
• Nocturnal Awakenings: To track mid-night wake events without raw sensor streams, inspect the sleep stage intervals and filter for items with stage type AWAKE (or wake for classic sleep logs).
• Latency and Efficiency: Use minutesToFallAsleep and the sleep efficiency formula for sleep latency analysis. Note that minutesToFallAsleep is populated when sleep logs are manually edited or explicitly logged.
• Physiological Monitoring: For advanced health monitoring, combine the sleep session data with physiological and recovery metrics such as respiratory-rate-sleep-summary, daily-sleep-temperature-derivations, daily-heart-rate-variability, and daily-oxygen-saturation.
• Reconciliation: Use the reconcile operation to ensure that overlapping sleep logs from different devices (for example, a wearable and a mattress sensor) are merged into a single "main" sleep record.

Calculate total time in deep sleep

To calculate the total time a user spent in a restorative deep sleep stage for a specific night:

1. Query the sleep data type for the specified time range.
2. Iterate through the stages list and identify intervals where the type is DEEP.
3. Calculate the duration (End Time - Start Time) for each deep sleep interval and sum them.

The resulting sum provides the total physical duration of deep sleep for that session.