使用 Google Health API 开发睡眠体验

Google Health API 提供的数据类型可跟踪用户的睡眠模式,包括睡眠时长、睡眠质量和休息期间的生理指标。这些指标有助于应用提供有关恢复、睡眠卫生和长期健康趋势的数据洞见。

心率变异性 (HRV)、血氧饱和度 (SpO2) 和呼吸频率等生理指标是在睡眠期间专门记录的,因为此时身体处于稳定的静息状态。这样,API 就可以在不受白天压力源、身体活动或各种环境条件干扰的情况下,捕获用户自主神经和呼吸系统健康的基准。

了解这些数据类型之间的差异,以确定哪些指标适合您的应用。

支持的数据类型

该 API 支持以下用于测量睡眠的数据类型:

表:Google Health API 睡眠数据类型
数据类型 可用的
操作
范围
每日心率变异性
dataType:daily-heart-rate-variability
过滤条件参数:daily_heart_rate_variability
记录类型:每日

兼容的设备

list、reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
每日血氧饱和度
dataType:daily-oxygen-saturation
过滤条件参数:daily_oxygen_saturation
记录类型:每日

兼容的设备

list、reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
每日呼吸频率
dataType:daily-respiratory-rate
过滤条件参数:daily_respiratory_rate
记录类型:每日

兼容的设备

list、reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
每日睡眠体温衍生数据
dataType:daily-sleep-temperature-derivations
过滤条件参数:daily_sleep_temperature_derivations
记录类型:每日

兼容的设备

list、reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
心率变异性
dataType:heart-rate-variability
过滤条件参数:heart_rate_variability
记录类型:样本

兼容的设备

list、reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
血氧饱和度
dataType:oxygen-saturation
过滤条件参数:oxygen_saturation
记录类型:样本
存储分辨率:1 分钟

兼容的设备

list、reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
睡眠呼吸频率摘要
dataType:respiratory-rate-sleep-summary
过滤条件参数:respiratory_rate_sleep_summary
记录类型:样本

兼容的设备

list、reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
睡眠
dataType:sleep
过滤条件参数:sleep
记录类型:练习

兼容的设备

list、get、reconcile、create、update、batchDelete .sleep.readonly
.sleep.writeonly

睡眠时段和短暂清醒

睡眠时段 (Sleep) 表示离散的睡眠事件,例如单次夜间睡眠或日间小憩。它包含不重叠睡眠阶段的详细细分,以及称为短暂清醒的短暂清醒过渡间隔。

  • 睡眠时段 (Sleep):表示一个离散的睡眠事件(LIGHT、DEEP、REM、AWAKE 阶段间隔),用于划分主要休息时间的连续时间轴。
  • 短暂清醒 (shortAwakenings):休息期间发生的短暂清醒过渡或清醒。与标准 AWAKE 阶段间隔(划分不重叠的连续睡眠阶段进展)不同,短暂清醒是不同的片段,可以与周围的睡眠阶段重叠。它们可让您精细地了解不安和微觉醒,而不会干扰主要的睡眠阶段结构。
  • 夜间醒来:通过设备端传感器融合(加速度计、陀螺仪和步数)识别夜间醒来(例如起床喝水)。应用可以通过过滤 stages 来检测夜间醒来,以查找具有 type: "AWAKE" 的时间间隔(在 CLASSIC 和 STAGES 睡眠记录中均使用),也可以通过检查 outOfBedSegments 来检测夜间醒来。

示例

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

创建睡眠时段

如需创建睡眠时段条目,请向 sleep 数据点端点发送 POST 请求。响应包含 name 字段,其中包含 data-point-id,可在更新(修补)或删除请求中使用。

请求

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

查询和协调睡眠时段

如需检索用户的睡眠记录,请查询 reconcile 端点,而不是 list 端点。当用户通过多个来源(例如穿戴式追踪器和健康数据共享)追踪睡眠时,list 会返回每条重叠的记录。对原始 list 结果求和可能会重复统计每日睡眠时长。reconcile 端点会将重叠的日志去重并合并为单个数据流,并通过将 sleep.metadata.mainSleep 设置为 true 来标识每天的主要睡眠时段。如需比较这两个端点,请参阅比较列表和协调端点。

使用 list 或 reconcile 查询 sleep 时,请注意以下过滤和分页限制:

  1. 仅使用 sleep.interval.end_time(世界协调时间 [UTC] 的物理时间)或 sleep.interval.civil_end_time(本地民用时间)按会话的结束时间过滤 sleep 查询。使用 >= 和 < 比较运算符以及 AND 组合下限和上限。
  2. 请勿按开始时间或使用 OR 过滤 sleep 查询。对 sleep.interval.start_time 或 sleep.interval.civil_start_time 进行过滤会返回 400 Bad Request (INVALID_ARGUMENT) 错误,原因为 INVALID_DATA_POINT_FILTER_DATA_TYPE_MEMBER。使用 OR 会返回 400 Bad Request (INVALID_ARGUMENT) 错误,原因为 INVALID_DATA_POINT_FILTER_EXPRESSION_STRUCTURE。如需了解语法详情,请参阅过滤数据指南。
  3. list 和 reconcile 都会对 sleep 强制执行默认和最大 pageSize(值为 25)。如果您传递的 pageSize 大于 25,则 API 会将该值限制为 25,如果该值为负数,则会返回 400 Bad Request 错误。如需同步多周的睡眠记录,请使用 nextPageToken 进行分页,直到令牌为空。如需了解详情,请参阅查询历史数据。

例如,以下请求会查询在两周的民用日期范围内结束的已协调睡眠时段:

请求

GET https://health.googleapis.com/v4/users/me/dataTypes/sleep/dataPoints:reconcile
  ?filter=sleep.interval.civil_end_time >= "2026-03-01"
  AND sleep.interval.civil_end_time < "2026-03-15"
  &pageSize=25
Authorization: Bearer access-token
Accept: application/json

响应

{
  "dataPoints": [
    {
      "dataPointName": "users/user-id/dataTypes/sleep/dataPoints/data-point-id",
      "sleep": {
        "interval": {
          "startTime": "2026-03-03T20:57:30Z",
          "startUtcOffset": "0s",
          "endTime": "2026-03-04T04:41:30Z",
          "endUtcOffset": "0s"
        },
        "type": "STAGES",
        "stages": [
          {
            "startTime": "2026-03-03T20:57:30Z",
            "startUtcOffset": "0s",
            "endTime": "2026-03-03T20:59:30Z",
            "endUtcOffset": "0s",
            "type": "AWAKE"
          },
          {
            "startTime": "2026-03-04T04:07:30Z",
            "startUtcOffset": "0s",
            "endTime": "2026-03-04T04:41:30Z",
            "endUtcOffset": "0s",
            "type": "AWAKE"
          }
        ],
        "metadata": {
          "stagesStatus": "SUCCEEDED",
          "processed": true,
          "mainSleep": true
        },
        "summary": {
          "minutesInSleepPeriod": "464",
          "minutesAfterWakeUp": "0",
          "minutesToFallAsleep": "0",
          "minutesAsleep": "407",
          "minutesAwake": "57",
          "stagesSummary": [
            {
              "type": "AWAKE",
              "minutes": "56",
              "count": "12"
            },
            {
              "type": "LIGHT",
              "minutes": "198",
              "count": "19"
            },
            {
              "type": "DEEP",
              "minutes": "114",
              "count": "10"
            },
            {
              "type": "REM",
              "minutes": "94",
              "count": "4"
            }
          ]
        }
      }
    }
  ],
  "nextPageToken": "Xm5h-6L0viZxIlRuWjx5bmvy98zj85uG34tuMn16mu2pntsnZI32iqhq"
}

睡眠效率和入睡用时指标

除了睡眠阶段和生理指标之外,该 API 还提供量化睡眠质量和入睡情况的关键指标。睡眠效率和入睡延迟是标准的临床指标,用于描述用户相对于其在床上的总时间的有效休息情况,从而提供对睡眠卫生和休息质量的洞察。

睡眠效率得分

睡眠效率是一项标准指标,定义为睡眠时间占在床上总时间的比例。该 API 使用以下公式计算睡眠效率:

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

效率得分是在睡眠水平(阶段)划分之前计算的。API 响应中返回的总睡眠分钟数(在 summary.minutesAsleep 字段中)反映了计算睡眠水平后的最终结果。

如果用户或研究人员手动修改睡眠记录的开始或结束时间,API 会根据在新的就寝时间和起床时间范围内记录的传感器数据,重新计算睡眠效率得分并调整睡眠阶段划分。

入睡延迟

入睡潜伏期衡量的是从用户打算入睡(“在床上”或“熄灯”时间的开始)到入睡所经过的时间。

对于自动生成的日志(metadata.manuallyEdited 为 false),summary.minutesToFallAsleep 默认为 "0",因为系统未记录明确的入睡意图。手动记录或修改在床开始时间(metadata.manuallyEdited 为 true)时,API 会计算并填充 summary.minutesToFallAsleep 以及 summary.minutesAfterWakeUp。

研究和手动记录指南

当参与者手动记录或调整在床开始和结束时间时:

  1. 更新在床边界会更改睡眠 interval(和 summary.minutesInSleepPeriod)。
  2. 睡眠水平和阶段划分会自动调整,以评估新时间范围内的传感器数据。
  3. 系统会根据更新后的时间范围重新得出睡眠效率得分、summary.minutesToFallAsleep和summary.minutesAfterWakeUp。

每日睡眠体温衍生数据

每日睡眠体温衍生数据用于衡量用户睡眠期间的体表温度与基准温度之间的变化。此数据通常在主要睡眠时段后每天报告一次。

呼吸频率

呼吸频率用于测量用户每分钟的呼吸次数。在睡眠期间,它是监测睡眠质量和潜在干扰的关键指标。该 API 支持呼吸频率样本 (respiratory-rate)、每日摘要 (daily-respiratory-rate) 和时段级睡眠状况摘要 (respiratory-rate-sleep-summary)。

心率变异性 (HRV)

HRV 测量每次心跳之间的时间变化。它是自主神经系统状态的关键指标;睡眠期间 HRV 较高通常表示恢复和准备状态较好,而 HRV 较低则可能表示压力过大或训练过度。该 API 支持 HRV 样本 (heart-rate-variability) 和每日摘要 (daily-heart-rate-variability)。

血氧饱和度

血氧饱和度 (SpO2) 表示血氧饱和血红蛋白相对于血液中总血红蛋白的百分比。在睡眠期间监测 SpO2 有助于检测潜在的呼吸障碍,并确认用户在整晚是否保持充足的氧气水平。该 API 支持血氧饱和度样本 (oxygen-saturation) 和每日摘要 (daily-oxygen-saturation)。

当您查询分钟级 oxygen-saturation 时,Google Health API 仅返回经过验证的数据点,并滤除因手臂移动、手腕佩戴松动或传感器置信度低(低于 50%)而导致的无效测量值,以及与运动噪声相邻的读数。由于无效分钟数会被排除,因此分钟级覆盖率可能较低,并且预计会出现时间戳间隔。oxygen-saturation 和 daily-oxygen-saturation 都依赖于相同的经过验证的读数。如需详细了解验证标准,请参阅分钟级 SpO2 过滤和数据有效性。

全面了解睡眠健康和恢复情况

虽然每个指标都提供了特定的数据洞见,但它们之间存在着密切的关联,共同构成了用户恢复情况的整体视图。睡眠阶段(浅度睡眠、深度睡眠、快速眼动睡眠)是休息的结构基础,而 HRV 和 SpO2 等生理指标则反映了身体对休息的生理反应。 例如,深度睡眠时间充足的高质量睡眠时段通常与较高的 HRV 相关,这表明自主神经系统得到了有效恢复。

将这些数据与呼吸频率和睡眠温度推导结果相结合,应用便能识别潜在的干扰因素。呼吸频率突然飙升或睡眠温度出现偏差,可以解释用户在恢复性睡眠阶段的时间为何减少。通过同时分析这些数据类型,开发者可以全面评估睡眠卫生和长期健康趋势。

指南

在应用中集成睡眠指标时,请遵循以下准则:

  • 练习详情:如需显示用户的睡眠阶段(浅睡眠、深睡眠、REM 快速眼动睡眠、清醒)和短暂清醒,请查询 sleep 数据类型。
  • 夜间醒来:如需在没有原始传感器数据流的情况下跟踪午夜醒来事件,请检查 sleep 阶段间隔,并过滤出包含 type: "AWAKE" 的项(适用于 STAGES 和 CLASSIC 睡眠记录),或检查 outOfBedSegments。
  • 延迟时间和效率:使用 summary.minutesToFallAsleep 和睡眠效率公式进行睡眠延迟时间分析。请注意,手动修改睡眠记录(metadata.manuallyEdited 为 true)或明确记录睡眠时,系统会填充 summary.minutesToFallAsleep。
  • 生理监测:如需进行高级健康监测,请将睡眠时段数据与生理和恢复指标(例如 respiratory-rate-sleep-summary、daily-sleep-temperature-derivations、daily-heart-rate-variability 和 daily-oxygen-saturation)相结合。

计算深度睡眠总时长

如需计算用户在特定夜晚处于恢复性深度睡眠阶段的总时间,请执行以下操作:

  1. 查询指定时间范围内的 sleep 数据类型。
  2. 遍历阶段列表,找出 type 为 DEEP 的时间间隔。
  3. 计算每个深度睡眠时间间隔的时长(结束时间 - 开始时间),然后求和。

得出的总和即为该时段内深度睡眠的总实际时长。