Google Health API 資料類型

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

注意：健康資料 API 不支援 Fitbit Ace 裝置。詳情請參閱「Fitbit 兒童帳戶隱私權政策」。

重要事項：如果資料類型包含多個字詞，資料類型 ID 的格式會有所不同。在端點中，資料型別名稱必須採用 kebab case，例如 body-fat。不過，在篩選器參數中，資料型別名稱必須採用蛇形命名法，例如 body_fat。

表格：Google Health API 資料類型

資料類型   dataType   filter 參數	可用的 作業	範圍
消耗的活動熱量 active-energy-burned active_energy_burned 記錄類型： 間隔 熱量與能量指南	list、reconcile、rollup、dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
活動分鐘數 active-minutes active_minutes 記錄類型： 間隔 相容裝置 Fitbit Air Fitbit Alta Fitbit Alta HR Fitbit Blaze Fitbit Charge 2 Fitbit Charge 3 Fitbit Flex 2 Fitbit Inspire Fitbit Inspire HR Pixel Watch 4	list、reconcile、rollup、dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
活動區間分鐘數 active-zone-minutes active_zone_minutes 記錄類型： 間隔 Webhook 支援 相容裝置 Fitbit Air Fitbit Charge 4 Fitbit Charge 5 Fitbit Charge 6 Fitbit Inspire 2 Fitbit Inspire 3 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	list、reconcile、rollup、dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
活動層級 activity-level activity_level 記錄類型： 間隔 Webhook 支援	list、reconcile	.activity_and_fitness.readonly .activity_and_fitness.writeonly
海拔高度 altitude altitude 記錄類型： 間隔 Webhook 支援 支援真正的零	list、reconcile、rollup、dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
血糖 blood-glucose blood_glucose 記錄類型： 範例 Webhook 支援 Vitals 指南	list、get、reconcile、rollup、dailyRollup	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
體脂肪 body-fat body_fat 記錄類型： 範例 Webhook 支援 相容裝置 Fitbit Aria Fitbit Aria 2 Fitbit Aria Air	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 記錄類型： 間隔 Webhook 支援	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 記錄類型： 每日 Webhook 支援 健康指標指南 睡眠指南 相容裝置 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	list、reconcile	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
每日心率區間 daily-heart-rate-zones daily_heart_rate_zones 記錄類型： 每日 Webhook 支援 Vitals 指南	list、reconcile	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
每日血氧濃度 daily-oxygen-saturation daily_oxygen_saturation 記錄類型： 每日 Webhook 支援 健康指標指南 睡眠指南 相容裝置 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	list、reconcile	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
每日呼吸速率 daily-respiratory-rate daily_respiratory_rate 記錄類型： 每日 Webhook 支援 健康指標指南 睡眠指南 相容裝置 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	list、reconcile	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
每日靜止心率 daily-resting-heart-rate daily_resting_heart_rate 記錄類型： 每日 Webhook 支援 Vitals 指南 相容裝置 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 Fitbit Versa Lite	list、reconcile	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
每日睡眠溫度變化 daily-sleep-temperature-derivations daily_sleep_temperature_derivations 記錄類型： 每日 Webhook 支援 健康指標指南 睡眠指南 相容裝置 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	list、reconcile	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
每日最大攝氧量 daily-vo2-max daily_vo2_max 記錄類型： 每日 相容裝置 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 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	list、reconcile	.activity_and_fitness.readonly .activity_and_fitness.writeonly
距離 distance distance 記錄類型： 間隔 Webhook 支援 支援真正的零 相容裝置 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	list、reconcile、rollup、dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
心電圖 (ECG) electrocardiogram electrocardiogram 記錄類型： 工作階段 生理指標指南 相容裝置 Fitbit Charge 5 Fitbit Charge 6 Pixel Watch Pixel Watch 2 Pixel Watch 3 Pixel Watch 4 Fitbit Sense Fitbit Sense 2	list	.ecg.readonly
運動 exercise exercise 記錄類型： 工作階段 Webhook 支援 訓練指南 相容裝置 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	list、get、reconcile、create、update、batchDelete	.activity_and_fitness.readonly .activity_and_fitness.writeonly
樓層數 floors floors 記錄類型： 間隔 Webhook 支援 支援真正的零	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 記錄類型： 食物 營養指南 相容裝置 Fitbit Air Fitbit Blaze Fitbit Charge 2 Fitbit Charge 3 Fitbit Charge 4 Fitbit Ionic 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	list、get	.nutrition.readonly .nutrition.writeonly
心率 heart-rate heart_rate 記錄類型： 範例 Webhook 支援 Vitals 指南 相容裝置 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 Fitbit Versa Lite	list、reconcile、rollup、dailyRollup	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
心率變異 heart-rate-variability heart_rate_variability 記錄類型： 範例 Webhook 支援 健康指標指南 睡眠指南 相容裝置 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	list、reconcile	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
身高 height height 記錄類型： 範例 Webhook 支援	list、get、reconcile、create、update、batchDelete	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
飲水量記錄 hydration-log hydration_log 記錄類型： 工作階段 Webhook 支援	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 記錄類型： 範例 Webhook 支援 營養指南 相容裝置 Fitbit Air Fitbit Charge 3 Fitbit Charge 4 Fitbit Charge 5 Fitbit Charge 6 Fitbit Inspire 2 Fitbit Inspire 3 Fitbit Luxe Pixel Watch Pixel Watch 2 Pixel Watch 3 Pixel Watch 4 Fitbit Sense Fitbit Sense 2 Fitbit Versa 2 Fitbit Versa 3 Fitbit Versa 4 Fitbit Versa Lite	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 記錄類型： 範例 生理指標指南 睡眠指南 相容裝置 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	list、reconcile	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
呼吸速率睡眠摘要 respiratory-rate-sleep-summary respiratory_rate_sleep_summary 記錄類型： 範例 Webhook 支援 健康指標指南 睡眠指南 相容裝置 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	list、reconcile	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
跑步最大攝氧量 run-vo2-max run_vo2_max 記錄類型： 範例 Webhook 支援 相容裝置 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 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	list、reconcile、rollup、dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
久坐時間 sedentary-period sedentary_period 記錄類型： 間隔 Webhook 支援 相容裝置 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	list、reconcile、rollup、dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
睡眠 sleep sleep 記錄類型： 工作階段 Webhook 支援 睡眠指南 相容裝置 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	list、get、reconcile、create、update、batchDelete	.sleep.readonly .sleep.writeonly
步驟 steps steps 記錄類型： 間隔 Webhook 支援 支援真正的零 步驟指南 相容裝置 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	list、reconcile、rollup、dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
游泳距離資料 swim-lengths-data swim_lengths_data 記錄類型： 間隔 相容裝置 Fitbit Air 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	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 記錄類型： 間隔 Webhook 支援	list、reconcile、rollup、dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
總熱量 total-calories total_calories 記錄類型： 間隔 支援真正的零熱量 熱量和能量指南 相容裝置 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	rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
最大攝氧量 vo2-max vo2_max 記錄類型： 範例 相容裝置 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 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	list、reconcile	.activity_and_fitness.readonly .activity_and_fitness.writeonly
權重 weight weight 記錄類型： 範例 Webhook 支援 相容裝置 Fitbit Aria Fitbit Aria 2 Fitbit Aria Air	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 對應用程式可使用的歷史資料量沒有限制。

不過，查詢歷來資料時，仍須遵守標準的速率限制。為管理系統穩定性及避免過多酬載，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 裝置無法直接與第三方應用程式或服務通訊。這些裝置只能與 Fitbit 行動應用程式通訊及同步。

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

距離標準

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

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

日長變化

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

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

日光節約時間

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

旅遊

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

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