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:

Table: Google Health API Sleep data types

Data type   dataType   filter parameter	Record type	Available operations	Scope	Webhook support	True zeros support
Daily Heart Rate Variability   daily-heart-rate-variability   daily_heart_rate_variability   Vitals guide   Sleep guide Compatible devices Fitbit Air Fitbit Alta HR Fitbit Blaze Fitbit Charge 2 Fitbit Charge 3 Fitbit Charge 4 Fitbit Charge 5 Fitbit Charge 6 Fitbit Inspire 2 Fitbit Inspire 3 Fitbit Inspire HR Fitbit Ionic Fitbit Luxe Pixel Watch Pixel Watch 2 Pixel Watch 3 Pixel Watch 4 Fitbit Sense Fitbit Sense 2 Fitbit Versa Fitbit Versa 2 Fitbit Versa 3 Fitbit Versa 4	Daily	list, reconcile	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
Daily Oxygen Saturation   daily-oxygen-saturation   daily_oxygen_saturation   Vitals guide   Sleep guide Compatible devices Fitbit Air Fitbit Charge 4 Fitbit Charge 5 Fitbit Charge 6 Fitbit Inspire 3 Fitbit Ionic Fitbit Luxe Pixel Watch 2 Pixel Watch 3 Pixel Watch 4 Fitbit Sense Fitbit Sense 2 Fitbit Versa Fitbit Versa 2 Fitbit Versa 3 Fitbit Versa 4	Daily	list, reconcile	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
Daily Respiratory Rate   daily-respiratory-rate   daily_respiratory_rate   Vitals guide   Sleep guide Compatible devices Fitbit Air Fitbit Alta HR Fitbit Blaze Fitbit Charge 2 Fitbit Charge 3 Fitbit Charge 4 Fitbit Charge 5 Fitbit Charge 6 Fitbit Inspire 2 Fitbit Inspire 3 Fitbit Inspire HR Fitbit Ionic Fitbit Luxe Pixel Watch Pixel Watch 2 Pixel Watch 3 Pixel Watch 4 Fitbit Sense Fitbit Sense 2 Fitbit Versa Fitbit Versa 2 Fitbit Versa 3 Fitbit Versa 4	Daily	list, reconcile	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
Daily Sleep Temperature Derivations   daily-sleep-temperature-derivations   daily_sleep_temperature_derivations   Vitals guide   Sleep guide Compatible devices Fitbit Air Fitbit Charge 4 Fitbit Charge 5 Fitbit Charge 6 Fitbit Inspire 2 Fitbit Inspire 3 Fitbit Inspire HR Fitbit Ionic Fitbit Luxe Pixel Watch 2 Pixel Watch 3 Pixel Watch 4 Fitbit Sense Fitbit Sense 2 Fitbit Versa Fitbit Versa 2 Fitbit Versa 3 Fitbit Versa 4	Daily	list, reconcile	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
Heart Rate Variability   heart-rate-variability   heart_rate_variability   Vitals guide   Sleep guide Compatible devices Fitbit Air Fitbit Alta Fitbit Alta HR Fitbit Blaze Fitbit Charge 2 Fitbit Charge 3 Fitbit Charge 4 Fitbit Charge 5 Fitbit Charge 6 Fitbit Flex 2 Fitbit Inspire Fitbit Inspire 2 Fitbit Inspire 3 Fitbit Inspire HR Fitbit Ionic Fitbit Luxe Fitbit MobileTrack Pixel Watch Pixel Watch 2 Pixel Watch 3 Pixel Watch 4 Fitbit Sense Fitbit Sense 2 Fitbit Versa Fitbit Versa 2 Fitbit Versa 3 Fitbit Versa 4 Fitbit Versa Lite	Sample	list, reconcile	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
Oxygen Saturation   oxygen-saturation   oxygen_saturation   Vitals guide   Sleep guide Compatible devices Fitbit Air Fitbit Charge 4 Fitbit Charge 5 Fitbit Charge 6 Fitbit Inspire 3 Fitbit Ionic Fitbit Luxe Pixel Watch 2 Pixel Watch 3 Pixel Watch 4 Fitbit Sense Fitbit Sense 2 Fitbit Versa Fitbit Versa 2 Fitbit Versa 3 Fitbit Versa 4	Sample	list, reconcile	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
Respiratory Rate Sleep Summary   respiratory-rate-sleep-summary   respiratory_rate_sleep_summary   Vitals guide   Sleep guide Compatible devices Fitbit Air Fitbit Alta HR Fitbit Blaze Fitbit Charge 2 Fitbit Charge 3 Fitbit Charge 4 Fitbit Charge 5 Fitbit Charge 6 Fitbit Inspire 2 Fitbit Inspire 3 Fitbit Inspire HR Fitbit Ionic Fitbit Luxe Pixel Watch Pixel Watch 2 Pixel Watch 3 Pixel Watch 4 Fitbit Sense Fitbit Sense 2 Fitbit Versa Fitbit Versa 2 Fitbit Versa 3 Fitbit Versa 4	Sample	list, reconcile	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
Sleep   sleep   sleep   Sleep guide Compatible devices Fitbit Air Fitbit Alta Fitbit Alta HR Fitbit Blaze Fitbit Charge 2 Fitbit Charge 3 Fitbit Charge 4 Fitbit Charge 5 Fitbit Charge 6 Fitbit Flex 2 Fitbit Inspire Fitbit Inspire 2 Fitbit Inspire 3 Fitbit Inspire HR Fitbit Ionic Fitbit Luxe Pixel Watch Pixel Watch 2 Pixel Watch 3 Pixel Watch 4 Fitbit Sense Fitbit Sense 2 Fitbit Versa Fitbit Versa 2 Fitbit Versa 3 Fitbit Versa 4 Fitbit Versa Lite	Session	list, get, reconcile, create, update, batchDelete	.sleep.readonly .sleep.writeonly

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.

Example

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

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.
• 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 stageType 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.