使用 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
記錄類型： 範例

相容裝置
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
filter 參數： sleep
記錄類型： 工作階段

相容裝置
list、get、reconcile、create、update、batchDelete .sleep.readonly
.sleep.writeonly

睡眠時段和短暫清醒

「睡眠時段」圖示 (Sleep) 代表個別睡眠事件，例如一晚的睡眠或午睡。這份報告會詳細列出不重疊的睡眠階段，以及短暫的清醒過渡期 (又稱短暫清醒)。

  • 睡眠階段 (Sleep)：代表個別的睡眠事件 (LIGHT、DEEP、REM、AWAKE 階段間隔)，可劃分主要休息時間的連續時間軸。
  • 短暫清醒 (shortAwakenings)：休息期間發生的短暫清醒或醒來。與標準AWAKE階段間隔 (劃分不重疊的連續睡眠階段進展) 不同，短暫清醒是可與周圍睡眠階段重疊的獨立區段。這類資料可提供詳細的睡眠不安和微覺醒資訊，且不會影響主要睡眠階段結構。
  • 夜間清醒：裝置端感應器融合技術 (加速計、陀螺儀和步數) 會偵測夜間清醒情形 (例如起床喝水)。在 Web API 中，應用程式可以篩選標示為 "wake" (傳統睡眠) 或 "awake" (睡眠階段) 的間隔，偵測夜間清醒狀態。

範例

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

建立睡眠時段

如要建立睡眠時段項目，請將 POST 要求傳送至 sleep 資料點端點。回應會包含 name 欄位，其中含有 data-point-id，可用於「更新 (Patch)」或「刪除」要求。

要求

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

睡眠效率和睡眠延遲指標

除了睡眠階段和生理指標，這項 API 還提供可量化睡眠品質和入睡時間的關鍵指標。睡眠效率和入睡延遲是標準的臨床指標，可說明使用者相較於總睡眠時間的休息效果，並提供睡眠衛生和休息品質的洞察資料。

睡眠效率分數

睡眠效率是標準指標，定義為睡眠時間占總躺床時間的比例。API 會使用下列公式計算睡眠效率：

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

系統會在睡眠階段劃分前計算效率分數。API 回應中傳回的總睡眠時間 (位於 summary.minutesAsleep 欄位) 會反映睡眠等級計算後的最終結果。

如果使用者或研究人員手動修改睡眠記錄的開始或結束時間，API 會根據新就寢時間和起床時間範圍內記錄的感應器資料，重新計算睡眠效率分數並調整睡眠階段分割。

入睡延遲

入睡延遲時間是指從使用者打算入睡 (「就寢」或「關燈」時間) 到實際入睡的時間長度。

如果是透過自動偵測 (auto_detect) 自動產生的記錄，由於系統未記錄明確的入睡意圖，因此 minutesToFallAsleep 預設為 0。手動記錄或編輯就寢時間 (將記錄轉換為 manual) 時，API 會計算並填入 minutesToFallAsleep 和 minutesAfterWakeup。

研究和手動記錄的指引

參與者手動錄製或調整就寢時間和起床時間時：

  1. 更新就寢時間界線會變更 timeInBed 間隔。
  2. 系統會自動調整睡眠程度和階段劃分，評估新時間範圍內的感應器資料。
  3. 系統會根據更新後的時間範圍，重新計算睡眠效率分數、minutesToFallAsleep 和 minutesAfterWakeup。

每日睡眠溫度變化

「每日睡眠溫度變化」會測量使用者睡眠時的皮膚溫度變化，並與基準線比較。這項資料通常會在主要睡眠時段結束後，每天回報一次。

呼吸速率

呼吸速率是指使用者每分鐘的呼吸次數。睡眠期間，這項指標可用於監控睡眠品質和潛在干擾。這項 API 支援呼吸速率樣本 (respiratory-rate)、每日摘要 (daily-respiratory-rate) 和睡眠階段摘要 (respiratory-rate-sleep-summary)。

心率變異 (HRV)

心率變異分析會測量每次心跳間的時間變化。這是自主神經系統狀態的重要指標；睡眠期間 HRV 較高通常表示恢復狀況良好，身體已準備就緒，而 HRV 較低則可能表示壓力過大或訓練過度。這項 API 支援心率變異樣本 (heart-rate-variability) 和每日摘要 (daily-heart-rate-variability)。

血氧濃度 (SpO2)

血氧濃度是指血液中氧飽和的血紅素，占血紅素總量的百分比。睡眠期間的血氧濃度監測功能至關重要，可偵測潛在的呼吸障礙，確保使用者整夜維持充足的氧氣濃度。這項 API 支援血氧濃度樣本 (oxygen-saturation) 和每日摘要 (daily-oxygen-saturation)。

全面掌握睡眠健康和恢復狀況

雖然每項指標都能提供特定洞察資料，但這些指標彼此之間有著深層的關聯，可共同提供使用者復原情況的全面檢視畫面。睡眠階段 (淺睡、深睡、快速動眼) 是休息的結構基礎，而 HRV 和血氧濃度等生理指標則顯示身體對休息的反應。舉例來說，優質睡眠通常會伴隨較高的深層睡眠時間，這代表自律神經系統已有效恢復。

結合這些資料與呼吸速率和睡眠溫度推導結果，應用程式就能找出潛在干擾。呼吸頻率突然升高或睡眠溫度出現變化，可說明使用者為何可能較少處於恢復性睡眠階段。開發人員可以同時分析這些資料類型，全面評估睡眠衛生和長期健康趨勢。

規範

在應用程式中整合睡眠指標時，請遵循下列準則：

  • 工作階段詳細資料：如要顯示使用者的睡眠階段 (淺睡、熟睡、快速動眼期、清醒) 和短暫清醒時間，請查詢 sleep 資料型別。
  • 夜間清醒：如要追蹤午夜清醒事件，但不想使用原始感應器串流，請檢查 sleep 階段間隔，並篩選階段類型為 AWAKE 的項目 (或傳統睡眠記錄的 wake)。
  • 入睡時間和睡眠效率：使用 minutesToFallAsleep 和睡眠效率公式分析入睡時間。請注意，手動編輯或明確記錄睡眠記錄時，系統會填入 minutesToFallAsleep。
  • 生理監測：如要進階監測健康狀況，請將睡眠階段資料與生理和恢復指標 (例如 respiratory-rate-sleep-summary、daily-sleep-temperature-derivations、daily-heart-rate-variability 和 daily-oxygen-saturation) 結合。
  • 對帳：使用 reconcile 作業，確保來自不同裝置 (例如智慧手環和床墊感應器) 的重疊睡眠記錄會合併為單一「主要」睡眠記錄。

計算總深層睡眠時間

如要計算使用者在特定夜晚的恢復性深層睡眠階段總時間，請按照下列步驟操作：

  1. 查詢指定時間範圍的 sleep 資料類型。
  2. 疊代階段清單，找出 type 為 DEEP 的間隔。
  3. 計算每個深層睡眠間隔的時長 (結束時間 - 開始時間)，然後加總。

加總後即可得出該睡眠時段的深層睡眠總時長。

上一頁
操作步驟