Google Health API 資料類型

下表列出所有資料類型，並提供多個資料欄，協助您瞭解 Google Health API 中各類型的表示方式，以及各類型適用的範圍。

表格：Google Health API 資料型別
資料類型
  dataType
  filter 參數		 記錄
類型		 可用的
作業		 範圍 Webhook
支援		 支援真正的零
消耗的活動熱量
  active-energy-burned
  active_energy_burned 		時間間隔 list、reconcile、rollup、dailyRollup .activity_and_fitness.readonly
.activity_and_fitness.writeonly
活動分鐘數
  active-minutes
  active_minutes 		時間間隔 list、reconcile、rollup、dailyRollup .activity_and_fitness.readonly
.activity_and_fitness.writeonly
活動區間分鐘數
  active-zone-minutes
  active_zone_minutes 		時間間隔 list、reconcile、rollup、dailyRollup .activity_and_fitness.readonly
.activity_and_fitness.writeonly
活動等級
  activity-level
  activity_level 		時間間隔 list、reconcile .activity_and_fitness.readonly
.activity_and_fitness.writeonly
海拔高度
  altitude
  altitude 		時間間隔 list、reconcile、rollup、dailyRollup .activity_and_fitness.readonly
.activity_and_fitness.writeonly
血糖
  blood-glucose
  blood_glucose 		範例 list、get、reconcile、rollup、dailyRollup .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
體脂肪
  body-fat
  body_fat 		範例 list、get、reconcile、rollup、dailyRollup、create、update、batchDelete .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
心率區間消耗的熱量
  calories-in-heart-rate-zone
  calories_in_heart_rate_zone 		時間間隔 rollup、dailyRollup .activity_and_fitness.readonly
.activity_and_fitness.writeonly
核心體溫
  core-body-temperature
  core_body_temperature 		範例 list、get、reconcile、rollup、dailyRollup .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
每日心率變異
  daily-heart-rate-variability
  daily_heart_rate_variability 		每日 list、reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
每日心率區間
  daily-heart-rate-zones
  daily_heart_rate_zones 		每日 list、reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
每日血氧濃度
  daily-oxygen-saturation
  daily_oxygen_saturation 		每日 list、reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
每日呼吸速率
  daily-respiratory-rate
  daily_respiratory_rate 		每日 list、reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
每日靜止心率
  daily-resting-heart-rate
  daily_resting_heart_rate 		每日 list、reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
每日睡眠體溫變化
  daily-sleep-temperature-derivations
  daily_sleep_temperature_derivations 		每日 list、reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
每日最大攝氧量
  daily-vo2-max
  daily_vo2_max 		每日 list、reconcile .activity_and_fitness.readonly
.activity_and_fitness.writeonly
距離
  distance
  distance 		時間間隔 list、reconcile、rollup、dailyRollup .activity_and_fitness.readonly
.activity_and_fitness.writeonly
心電圖 (ECG)
  electrocardiogram
  electrocardiogram 		工作階段 list .ecg.readonly
運動
  exercise
  exercise 		工作階段 list、get、reconcile、create、update、batchDelete .activity_and_fitness.readonly
.activity_and_fitness.writeonly
樓層數
  floors
  floors 		時間間隔 reconcile、rollup、dailyRollup .activity_and_fitness.readonly
.activity_and_fitness.writeonly
美食
  food
  food 		食物 list、get .nutrition.readonly
.nutrition.writeonly
食物測量單位
  food-measurement-unit
  food_measurement_unit 		食物 list、get .nutrition.readonly
.nutrition.writeonly
心率
  heart-rate
  heart_rate 		範例 list、reconcile、rollup、dailyRollup .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
心率變異
  heart-rate-variability
  heart_rate_variability 		範例 list、reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
身高
  height
  height 		範例 list、get、reconcile、create、update、batchDelete .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
飲水量記錄
  hydration-log
  hydration_log 		工作階段 list、get、reconcile、rollup、dailyRollup、create、update、batchDelete .nutrition.readonly
.nutrition.writeonly
心律不整通知
  irregular-rhythm-notification
  irregular_rhythm_notification 		工作階段 list .irn.readonly
經期
  menstrual-period
  menstrual_period 		時間間隔 create、update、batchDelete .reproductive_health.writeonly
情緒
  moods
  moods 		範例 create、update、batchDelete .mindfulness.writeonly
營養記錄
  nutrition-log
  nutrition_log 		範例 list、get、reconcile、rollup、dailyRollup、create、update、batchDelete .nutrition.readonly
.nutrition.writeonly
排卵檢測
  ovulation-test
  ovulation_test 		範例 create、update、batchDelete .reproductive_health.writeonly
血氧濃度
  oxygen-saturation
  oxygen_saturation 		範例 list、reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
呼吸速率睡眠摘要
  respiratory-rate-sleep-summary
  respiratory_rate_sleep_summary 		範例 list、reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
跑步最大攝氧量
  run-vo2-max
  run_vo2_max 		範例 list、reconcile、rollup、dailyRollup .activity_and_fitness.readonly
.activity_and_fitness.writeonly
久坐時間
  sedentary-period
  sedentary_period 		時間間隔 list、reconcile、rollup、dailyRollup .activity_and_fitness.readonly
.activity_and_fitness.writeonly
睡眠
  sleep
  sleep 		工作階段 list、get、reconcile、create、update、batchDelete .sleep.readonly
.sleep.writeonly
步驟
  steps
  steps 		時間間隔 list、reconcile、rollup、dailyRollup .activity_and_fitness.readonly
.activity_and_fitness.writeonly
游泳距離資料
  swim-lengths-data
  swim_lengths_data 		時間間隔 list、reconcile、rollup、dailyRollup .activity_and_fitness.readonly
.activity_and_fitness.writeonly
症狀
  symptoms
  symptoms 		範例 create、update、batchDelete .logged_symptoms.writeonly
在心率區間的時間
  time-in-heart-rate-zone
  time_in_heart_rate_zone 		時間間隔 list、reconcile、rollup、dailyRollup .activity_and_fitness.readonly
.activity_and_fitness.writeonly
總熱量
  total-calories
  total_calories 		時間間隔 rollup、dailyRollup .activity_and_fitness.readonly
.activity_and_fitness.writeonly
最大攝氧量
  vo2-max
  vo2_max 		範例 list、reconcile .activity_and_fitness.readonly
.activity_and_fitness.writeonly
權重
  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 天。

資料可用性

使用者必須同步活動追蹤器，或在 Fitbit 行動或網頁應用程式中手動輸入新資料，才能更新資料。如果 Fitbit 應用程式在行動裝置上開啟，且裝置與應用程式之間有作用中的資料連線並在藍牙範圍內，Fitbit 裝置和 Fitbit 行動應用程式每 15 分鐘就會自動同步一次。如果使用者使用 MobileTrack 追蹤活動，只要應用程式處於開啟狀態，MobileTrack 就會每小時同步一次。

查詢歷來資料

Google Health API 的主要優點之一，就是能夠追蹤使用者的運動表現，並長期監控健康指標。您可以查詢使用者記錄的資料，API 對應用程式可使用的歷史資料量沒有限制。

不過，查詢歷來資料時，仍須遵守標準的速率限制。為減少相對於這些限制的 API 呼叫次數，Google Health API 支援查詢特定日期範圍內的資料。請注意下列分頁和要求界線：

  • 每個端點每頁最多可傳回 10,000 個資料點。
  • 每個要求查詢的日期範圍必須介於 14 到 90 天之間。

視應用程式需要的歷來資料量而定，擷取整個資料集可能需要多個連續請求，並花費額外時間。設計應用程式的資料同步程序時，請將這點納入考量。

為確保最佳效能並避免發生 API 錯誤，查詢歷來資料時請遵循下列準則：

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

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

以時間為依據將查詢分塊

  • 請勿在單一 API 呼叫中要求多年或多月的時間範圍。 將大型歷史記錄查詢拆分成較小的連續間隔 (例如每個要求 1 週)。
  • 請安全地批次處理或依序執行這些子查詢，以遵守並行限制，並維持穩定的 UI 進度指標。

運用預先匯總的匯總資料

重新架構總覽資訊主頁和趨勢圖表，改用預先匯總的摘要端點 (例如 DailyRollUpDataPoints)。這會大幅減少後端的運算負荷，以及用戶端的網路傳輸時間。

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

  • 遇到速率限制 (429 Too Many Requests) 和伺服器閘道逾時 (504 Gateway Timeout) 時，請嚴格處理指數輪詢。切勿立即重試大型失敗的酬載。即時重試會加劇後端壅塞，並導致系統效能進一步下降。
  • 如果查詢持續逾時，系統會自動改用較小的時間範圍 (例如將 1 週縮短為 3 天)。

第三方存取權

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

只要開啟 Fitbit 應用程式，裝置就會全天自動同步資料。如果藍牙已啟用，且應用程式在背景執行，裝置每 15 分鐘就會同步一次。同步程序完成後，第三方服務就能透過 Google Health API 存取資料。

距離標準

運動距離 (例如 elevationGainMillimeters) 會以公釐做為標準單位，原因如下：

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

日長變化

健康資料 API 會優先處理使用者的時間，以因應日光節約時間或旅行造成的每日時間長度變化。每個資料點都會儲存實際的 UTC 時間戳記，以及事件發生時有效的 UTC 時差。這樣一來，系統就能：

  • 將事件對應至精確的實際時間點。
  • 將時間修正為使用者的當地時區，以便進行匯總。

日光節約時間

在日光節約時間期間，「調慢」會導致民用日有 25 小時，而該日期的匯總資料會包含 25 小時的資料。「春季前進」會導致民用日為 23 小時，時間會調回標準時間。

旅遊

跨時區旅行時，單一民事日期的實際長度可能會出現更明顯的差異。

使用 dailyRollUp 端點來調整時區差異。系統會根據使用者的當地時間，自動將資料歸因於記錄資料的日曆日期，即使時區有所變更，也能有效「縫合」當天資料。

下一頁
熱量和能量