Google Health API 資料類型

下表列出完整的資料類型清單,並提供多個資料欄,協助您瞭解每種類型在 Google Health API 中的表示方式,以及每種類型的可用範圍。

資料類型欄位

Google Health API 資料類型表格包含多個欄位,可協助您瞭解各資料類型的表示法和需求。這些資料欄如下:

表格:Google Health API 資料類型欄位說明
欄位 說明
dataType 端點網址中使用的 ID,以連字號分隔 (例如 active-minutes)。
filter 參數 以底線分隔的 ID (例如 active_minutes),在每日統整和統整要求中做為 dataType 篩選器參數的值。
記錄類型

表示記錄資料的結構和格式。在幕後,這與資料點的資源表示法一致。可能的值為:

  • Interval (代表一段時間內記錄的測量結果)。
  • Sample (代表即時測量值)。
  • Daily (代表每日匯總或記錄的測量結果)。
  • Session (代表連續記錄區塊,例如健身或心電圖 (ECG) 工作階段)。
  • Food (代表食品或營養相關資料實體)。
可用的運算選項 列出資料類型支援的 API 方法 (例如 list、create 和 rollUp)。
範圍 存取資料類型所需的 OAuth 範圍。
Webhook 支援 表示資料類型支援在同步新資料時,使用 Webhook 傳送通知。
支援真零 表示資料類型支援記錄明確的零值,以區分有效的零值 (例如零活動分鐘數) 與遺漏或未記錄的資料。
儲存解析度 儲存資料點的最小記錄或取樣間隔 (例如 steps 為 1 分鐘)。如果是匯總,這代表建議的最小 windowSize,以確保匯總分布平均,不會出現子間隔資料構件。
相容裝置 可展開的清單,列出能記錄這類資料並同步至 Google Health API (透過 Fitbit 應用程式) 的實體裝置。

表格:Google Health API 資料類型
資料類型 可用的
作業
範圍
活動消耗的熱量
dataType:active-energy-burned
篩選器參數:active_energy_burned
記錄類型:間隔
儲存空間解析度:1 分鐘
list、reconcile、rollup、dailyRollup .activity_and_fitness.readonly
.activity_and_fitness.writeonly
活動分鐘數
dataType:active-minutes
篩選器參數:active_minutes
記錄類型:間隔
儲存空間解析度:1 分鐘

相容裝置

list、reconcile、rollup、dailyRollup .activity_and_fitness.readonly
.activity_and_fitness.writeonly
活動區間分鐘數
dataType:active-zone-minutes
篩選器參數:active_zone_minutes
記錄類型:間隔
儲存空間解析度:1 分鐘

相容裝置

list、reconcile、rollup、dailyRollup .activity_and_fitness.readonly
.activity_and_fitness.writeonly
活動強度
dataType:activity-level
篩選器參數:activity_level
記錄類型:間隔
list、reconcile .activity_and_fitness.readonly
.activity_and_fitness.writeonly
Altitude
dataType:altitude
篩選器參數:altitude
記錄類型:間隔
儲存空間解析度:1 分鐘
list、reconcile、rollup、dailyRollup .activity_and_fitness.readonly
.activity_and_fitness.writeonly
血糖
dataType:blood-glucose
篩選器參數:blood_glucose
記錄類型:範例
list、get、reconcile、rollup、dailyRollup .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
體脂肪
dataType:body-fat
篩選器參數:body_fat
記錄類型:範例

相容裝置

list、get、reconcile、rollup、dailyRollup、create、update、batchDelete .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
心率區間卡路里
dataType:calories-in-heart-rate-zone
篩選器參數:calories_in_heart_rate_zone
記錄類型:間隔
儲存空間解析度:1 分鐘
rollup、dailyRollup .activity_and_fitness.readonly
.activity_and_fitness.writeonly
核心體溫
dataType:core-body-temperature
篩選器參數:core_body_temperature
記錄類型:範例
list、get、reconcile、rollup、dailyRollup .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
每日心率變異
dataType:daily-heart-rate-variability
篩選器參數:daily_heart_rate_variability
記錄類型:每日

相容裝置

list、reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
每日心率區間
dataType:daily-heart-rate-zones
篩選器參數:daily_heart_rate_zones
記錄類型:每日
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-resting-heart-rate
篩選器參數:daily_resting_heart_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:daily-vo2-max
篩選器參數:daily_vo2_max
記錄類型:每日

相容裝置

list、reconcile .activity_and_fitness.readonly
.activity_and_fitness.writeonly
距離
dataType:distance
篩選器參數:distance
記錄類型:間隔
儲存空間解析度:1 分鐘

相容裝置

list、reconcile、rollup、dailyRollup .activity_and_fitness.readonly
.activity_and_fitness.writeonly
心電圖 (ECG)
dataType:electrocardiogram
篩選器參數:electrocardiogram
記錄類型:工作階段

相容裝置

list .ecg.readonly
運動
dataType:exercise
篩選器參數:exercise
記錄類型:工作階段

相容裝置

list、get、reconcile、create、update、batchDelete .activity_and_fitness.readonly
.activity_and_fitness.writeonly
樓層數
dataType:floors
篩選器參數:floors
記錄類型:間隔
儲存空間解析度:1 分鐘

相容裝置

reconcile、rollup、dailyRollup .activity_and_fitness.readonly
.activity_and_fitness.writeonly
食物
dataType:food
篩選器參數:food
記錄類型:食物
list、get .nutrition.readonly
.nutrition.writeonly
食物份量單位
dataType:food-measurement-unit
篩選器參數:food_measurement_unit
記錄類型:食物
list、get .nutrition.readonly
.nutrition.writeonly
心率
dataType:heart-rate
篩選器參數:heart_rate
記錄類型:範例
儲存空間解析度:1 秒

相容裝置

list、reconcile、rollup、dailyRollup .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:height
篩選器參數:height
記錄類型:範例
list、get、reconcile、create、update、batchDelete .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
飲水量記錄
dataType:hydration-log
篩選器參數:hydration_log
記錄類型:工作階段
list、get、reconcile、rollup、dailyRollup、create、update、batchDelete .nutrition.readonly
.nutrition.writeonly
心律不整通知
dataType:irregular-rhythm-notification
篩選器參數:irregular_rhythm_notification
記錄類型:工作階段

相容裝置

list .irn.readonly
經期
dataType:menstrual-period
篩選器參數:menstrual_period
記錄類型:間隔
create、update、batchDelete .reproductive_health.writeonly
心情
dataType:moods
篩選器參數:moods
記錄類型:範例
create、update、batchDelete .mindfulness.writeonly
營養記錄
dataType:nutrition-log
篩選器參數:nutrition_log
記錄類型:工作階段
list、get、reconcile、rollup、dailyRollup、create、update、batchDelete .nutrition.readonly
.nutrition.writeonly
排卵檢測
dataType:ovulation-test
篩選器參數:ovulation_test
記錄類型:範例
create、update、batchDelete .reproductive_health.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:run-vo2-max
篩選器參數:run_vo2_max
記錄類型:範例

相容裝置

list、reconcile、rollup、dailyRollup .activity_and_fitness.readonly
.activity_and_fitness.writeonly
久坐時間
dataType:sedentary-period
篩選器參數:sedentary_period
記錄類型:間隔

相容裝置

list、reconcile、rollup、dailyRollup .activity_and_fitness.readonly
.activity_and_fitness.writeonly
皮膚溫度感應器 v4beta
dataType:skin-temperature-sensors
篩選器參數:skin_temperature_sensors
記錄類型:範例

相容裝置

list .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
睡眠
dataType:sleep
篩選器參數:sleep
記錄類型:工作階段

相容裝置

list、get、reconcile、create、update、batchDelete .sleep.readonly
.sleep.writeonly
步驟
dataType:steps
篩選器參數:steps
記錄類型:間隔
儲存空間解析度:1 分鐘

相容裝置

list、reconcile、rollup、dailyRollup .activity_and_fitness.readonly
.activity_and_fitness.writeonly
游泳趟數資料
dataType:swim-lengths-data
篩選器參數:swim_lengths_data
記錄類型:間隔

相容裝置

list、reconcile、rollup、dailyRollup .activity_and_fitness.readonly
.activity_and_fitness.writeonly
症狀
dataType:symptoms
篩選器參數:symptoms
記錄類型:範例
create、update、batchDelete .logged_symptoms.writeonly
心率區間時間
dataType:time-in-heart-rate-zone
篩選器參數:time_in_heart_rate_zone
記錄類型:間隔
儲存空間解析度:1 分鐘
list、reconcile、rollup、dailyRollup .activity_and_fitness.readonly
.activity_and_fitness.writeonly
總卡路里
dataType:total-calories
篩選器參數:total_calories
記錄類型:間隔
儲存空間解析度:1 分鐘

相容裝置

rollup、dailyRollup .activity_and_fitness.readonly
.activity_and_fitness.writeonly
最大攝氧量
dataType:vo2-max
篩選器參數:vo2_max
記錄類型:範例

相容裝置

list、reconcile .activity_and_fitness.readonly
.activity_and_fitness.writeonly
權重
dataType:weight
篩選器參數:weight
記錄類型:範例

相容裝置

list、get、reconcile、rollup、dailyRollup、create、update、batchDelete .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly

查詢限制

透過 API 查詢資料點、匯總資料或每日匯總資料時,請注意下列限制:

  • 篩選器需求:部分唯讀衍生資料類型 (例如 total-calories) 需要篩選器指定間隔開始時間 (使用實際時間或民用時間)。
  • 查詢範圍限制:匯總和每日匯總端點會根據資料類型,強制執行查詢範圍上限:
    • calories-in-heart-rate-zone、heart-rate、active-minutes 和 total-calories 的查詢範圍上限為 14 天。
    • 所有其他資料類型的查詢範圍上限為 90 天。
  • 匯總時間範圍大小:呼叫 rollUp 端點時,windowSize 持續時間必須至少為 1 秒 ("1s")。如果持續時間小於一秒,系統會拒絕並傳回 INVALID_ARGUMENT。此外,請選擇等於或大於資料類型基礎儲存空間解析度的 windowSize (例如 "60s",適用於 1 分鐘間隔資料類型,例如 steps 和 distance),避免子間隔分布不均。詳情請參閱「匯總時間範圍和儲存空間解析度」。

每日與間隔資料類型

針對心率變異 (HRV) 或血氧濃度 (SpO2) 等特定生理指標,Google Health API 提供兩種不同的資料類型:每日版本和間隔版本。瞭解兩者的差異,是為用途選擇合適指標的關鍵:

  • 每日:整天的單一預先匯總摘要。如要查看高層級趨勢和每日資訊主頁,請使用這個選項,節省處理費用。

  • 間隔:全天進行精細的高解析度測量。這項功能可用於繪製當日波動圖表,或進行深入的逐時分析。

資料可用性

使用者必須同步活動追蹤器,或在 Google Health 應用程式中手動輸入新資料,系統才會更新資料。如果 Google Health 應用程式在行動裝置上開啟,且兩者有有效的資料連線,並在藍牙範圍內,Fitbit 裝置和 Google Health 應用程式每 15 分鐘會自動同步一次。如果使用者透過 MobileTrack 追蹤活動,只要應用程式處於開啟狀態,MobileTrack 每小時就會同步一次。

查詢歷來資料

Google Health API 的核心優勢之一,是能長期追蹤使用者的表現並監控其生命徵象。您可以查詢使用者自記錄以來的所有資料,API 不會限制應用程式可使用的歷來資料量。

不過,查詢歷來資料仍受標準頻率限制規範。為管理系統穩定性並防止酬載過多,Google Health API 會使用自動分頁功能,並根據端點設定頁面大小。請注意下列界限和行為:

  • 自動分頁:如果您查詢的資料時間範圍較長,API 只會傳回第一頁結果 (最多為該端點的頁面大小上限),以及 nextPageToken。您必須使用 nextPageToken 要求後續頁面。
  • 可變頁面大小:上限取決於端點和資料類型。對於大多數資料類型,頁面大小上限為 10,000。 不過,對於 exercise 和 sleep 等特定資料類型,預設和最大頁面大小上限為 25。舉例來說,如果用戶端要求過去 10 年的所有睡眠資料,API 仍只會在第一頁傳回 25 個睡眠時段。
  • 匯總日期範圍限制:對於資料匯總和匯總端點 (例如 rollUp 和 dailyRollUp),查詢日期範圍會根據資料類型受到限制:
    • calories-in-heart-rate-zone、heart-rate、active-minutes 和 total-calories 的最大範圍為 14 天。
    • 所有其他匯總資料類型的最大範圍為 90 天。

視應用程式所需的歷來資料量而定,擷取整個資料集時,必須依序翻頁。設計應用程式的資料同步處理程序時,請務必留意這一點。

為確保最佳效能並避免 API 錯誤,查詢歷來資料時,請遵循下列規範:

分階段同步資料 (熱載入與冷載入)

  • 初始「熱」載入:在主要載入序列中,只擷取及算繪最近 7 到 14 天的資料。這樣一來,使用者就能立即看到資料,不必等待長時間執行的查詢。
  • 背景「冷」載入:在主要 UI 算繪後,將較舊的歷來資料擷取作業委派給非同步、優先順序較低的佇列或背景程序。

查詢匯總資料區塊

  • 由於匯總和每日匯總端點會強制執行日期範圍上限 (14 或 90 天,視資料類型而定),因此您必須將大型歷來匯總查詢細分為較小的連續間隔,並符合這些限制。
  • 安全地批次處理或排序這些子查詢,以遵守並行限制,並維持穩定的 UI 進度指標。

運用預先匯總的匯總資料

重構總覽資訊主頁和趨勢圖表,使用預先匯總的摘要端點 (例如 DailyRollUpDataPoints)。這樣可以大幅減少後端的運算負擔,以及傳輸至用戶端的網路傳輸時間。

彈性的錯誤處理機制 (智慧重試)

  • 遇到頻率限制 (429 Too Many Requests) 和伺服器閘道逾時 (504 Gateway Timeout) 時,請實施嚴格的指數輪詢處理。請勿立即重試大型失敗酬載。立即重試會加劇後端壅塞,並加劇系統效能降低。

第三方存取權

Fitbit 裝置無法直接與第三方應用程式或服務通訊。這些裝置只能與 Google Health 應用程式通訊及同步。

裝置會自動同步一整天的資料,只要 Google Health 應用程式開啟,或藍牙啟用且應用程式在背景執行,每 15 分鐘就會同步一次。同步處理程序完成後,第三方服務就能透過 Google Health API 取得資料。

資料品質和有效性篩選

為提供可靠的健康指標,Google Health API 會先驗證感應器遙測資料,並排除無效的測量結果,再傳回回應,因此您不必自訂用戶端雜訊篩選功能:

  • 如果是每分鐘血氧濃度 (oxygen-saturation),API 只會傳回經過驗證的讀數,並移除因手臂移動、手腕鬆動或感應器信賴分數低於 50% 而標示為無效的分鐘數,以及無效讀數前後 3 分鐘和短於 4 分鐘的獨立有效讀數。因此,每分鐘的涵蓋範圍可能較為稀疏,且可能會有落差。詳情請參閱「每分鐘血氧濃度篩選和資料有效性」。

距離標準

運動距離 (例如 elevationGainMillimeters) 以公釐為標準單位,原因如下:

  1. 維持資料精確度:使用公釐的最重要原因,是確保我們讀取和提供的資料不會失去精確度。使用公釐等精細單位,可精確表示測量結果。
  2. 標準化:公釐是我們服務中設計的標準化單位。這種一致性有助於確保開發人員在與 API 的不同部分互動時,能獲得一致的體驗。
  3. 廣泛支援測量系統:使用公釐等基本單位,開發人員就能輕鬆轉換為任何其他所選單位,無論是公制、英制或其他測量系統。

晝長變化

Health API 處理時間時,會優先考量使用者的時間,以因應日光節約時間或旅行導致的日長變化。每個資料點都會儲存實體世界標準時間時間戳記,以及事件發生時有效的世界標準時間偏移。這樣一來,系統就能:

  • 將事件對應至精確的實際時間點。
  • 根據使用者的當地時間修正時間,以便匯總。

日光節約時間

實施日光節約時間時,「秋季調慢」會導致民用日變成 25 小時,該日期的匯總資料會包含 25 小時的資料。「春季調快」會導致民用日變成 23 小時,時間會調回標準時間。

旅遊

跨時區旅行可能會導致單一民用日的實際時間長度出現更明顯的變化。

請使用 dailyRollUp 端點來協調時區差異。系統會根據使用者的當地時間,自動將資料歸因於記錄當天,有效將當天資料「拼接」在一起,不受時區變更影響。如需詳細資訊和範例,請參閱「匯總資料」指南中的「匯總日曆天數」。