API 规范

“API 规范”部分详细概述了与平台集成所必需的技术组件，包括授权范围、数据类型定义和端点结构。此 API 是旧版 Fitbit Web API 的战略性演进，在现代基础架构上进行了重构，可确保提供更稳定、更一致的开发者体验。

范围

您必须更新授权请求，以使用 Google Health API 范围。 这些范围定义了您的应用是否支持读取或写入操作。 请遵循范围实现说明，其中规定了仅请求所需范围、仅在发送数据时配置写入权限，以及妥善处理部分同意。

Google Health API 范围是以 https://www.googleapis.com/auth/googlehealth.{scope} 开头的 HTTP 网址。例如 https://www.googleapis.com/auth/googlehealth.activity_and_fitness.writeonly。

范围映射

Fitbit Web API 范围与 Google Health API 范围的映射关系如下：

表：Fitbit Web API 到 Google Health API 的范围映射
Fitbit Web API 范围 Google Health API 范围
活动 .activity_and_fitness.readonly
.activity_and_fitness.writeonly
blood_glucose .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
cardio_fitness .activity_and_fitness.readonly
.activity_and_fitness.writeonly
心电图 .ecg.readonly
心率 .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
irregular_rhythm_notifications .irn.readonly
地理位置 .location.readonly
营养 .nutrition.readonly
.nutrition.writeonly
oxygen_saturation .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
个人资料 .profile.readonly
.profile.writeonly
respiratory_rate .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
设置 .settings.readonly
.settings.writeonly
sleep .sleep.readonly
.sleep.writeonly
温度 .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
重量 .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly

数据类型

下面列出了 Google Health API 数据类型以及它们与 Fitbit Web API 的映射关系。

表：Fitbit Web API 到 Google Health API 的数据类型映射
Fitbit Web API 数据类型 Google Health API 数据类型
  dataType		 说明
活动消耗卡路里数 活动消耗能量
  active-energy-burned 		表示活动期间消耗的卡路里，包括这些时段的基础代谢率 (BMR)。在 Google Health API 中，可以通过将 BMR 添加到 active-energy-burned 数据类型（该数据类型仅跟踪活动消耗，不包括基础代谢率）来重构此数据。
活跃区间分钟数 活跃区间分钟数
  active-zone-minutes
包含用户活动水平的变化 活动水平
  activity-level 		捕获用户在特定时间段内的活动水平（例如久坐或活跃）。
海拔 海拔
  altitude
活动 caloriesBMR 基础能量消耗
  basal-energy-burned 		特定时间段内因基础代谢率 (BMR) 而消耗的卡路里数。
血糖 血糖
  blood-glucose
体脂 体脂率
  body-fat
处于各心率区间的时长：caloriesOut 在心率区间内消耗的卡路里数
  calories-in-heart-rate-zone
温度（核心） 核心体温
  core-body-temperature
HRV 摘要 每日心率变异性
  daily-heart-rate-variability
血氧饱和度摘要 每日血氧饱和度
  daily-oxygen-saturation 		根据经过验证的睡眠测量结果计算出的血氧饱和度 (SpO2) 统计数据的每日摘要。
静息心率 每日静息心率
  daily-resting-heart-rate
体表温度 每日睡眠温度偏差
  daily-sleep-temperature-derivations
距离 距离
  distance
心电图 (ECG) 心电图 (ECG)
  electrocardiogram
记录的活动 锻炼
  exercise 		记录的锻炼或练习，包括开始/结束时间、活动类型和练习指标。
楼层数 爬楼层数
  floors
美食 美食
  food
食物计量单位 食物计量单位
  food-measurement-unit
心率 心率
  heart-rate
HRV 当日 心率变异性
  heart-rate-variability
心律不齐通知 (IRN) 心律不齐通知
  irregular-rhythm-notification
饮食记录 营养记录
  nutrition-log
当日血氧饱和度 血氧饱和度
  oxygen-saturation 		仅返回经过验证的分钟级 SpO2 测量值，并排除因运动伪影或传感器置信度低而被标记为无效的读数。由于 Fitbit Web API 仅排除了 50% 的哨兵值，因此 Google Health API 针对同一时间范围返回的数据点较少。如需了解详情，请参阅血氧饱和度过滤。
用户跑步时的最大摄氧量值 跑步最大摄氧量
  run-vo2-max
活动时间序列久坐分钟数 久坐时段
  sedentary-period
睡眠 睡眠
  sleep
步骤 步骤
  steps
活动时间序列游泳姿势 游泳距离数据
  swim-lengths-data
活动 caloriesOut 总卡路里
  total-calories 		用户在一段时间内消耗的卡路里总数，包括基础代谢率和活动消耗的能量。
最大摄氧量值 最大摄氧量
  vo2-max
重量 权重
  weight

计算

Google Health API 中的映射和规则与 Fitbit Web API 不同。

血氧饱和度过滤

查询分钟级血氧饱和度 (oxygen-saturation) 时，Google Health API 会应用比旧版 Fitbit Web API 更严格的数据有效性过滤条件：

  • 旧版 Fitbit Web API（v1 和 v3）仅排除了哨兵值为 50% 的 SpO2 样本。
  • Google Health API (v4) 会排除被验证算法标记为无效的所有血氧饱和度样本。如果手臂移动或手腕佩戴松动导致光学传感器信号不可靠、置信度分数降至 50% 以下、无效读数前后 3 分钟内，或有效时间段持续不到连续 4 分钟，则该分钟会被标记为无效。

由于 Google Health API 会移除所有无效测量值，而不仅仅是 50% 的哨兵值，因此对于同一时间范围，它返回的 oxygen-saturation 数据点比 Fitbit Web API 少，并且预计每分钟覆盖率会出现差距。返回的分钟级读数与用于计算用户 daily-oxygen-saturation 睡眠状况摘要的经过验证的数据点一致。如需了解详情，请参阅分钟级血氧饱和度过滤和数据有效性。

活动量、MET 和步数阈值

在 Google Health API 中，用户的每分钟活动水平是根据其代谢当量 (MET) 和步数得出的。

activity 级别 心率设备 非心率设备
久坐 ≤ 1.5 METs ≤ 1.5 METs
轻度活动 > 1.5 MET 且 ≤ 4.2 MET > 1.5 MET 且 ≤ 3.5 MET
中等活跃 > 4.2 MET 且 < 6.0 MET
（除非满足非常活跃的条件）		 > 3.5 MET 且 < 6.0 MET
（除非满足非常活跃的条件）
非常活跃 ≥ 6.0 MET，或 ≥ 5.0 MET 且步频达到每分钟 150 步或以上 ≥ 6.0 MET，或 ≥ 5.0 MET 且步频达到每分钟 150 步或以上

活跃分钟数由MODERATELY_ACTIVE和VERY_ACTIVE分钟数组成。不过，只有在连续至少 10 分钟的活动期间，且活动强度较低的间歇不超过 2 分钟时，高强度活动分钟数才会被计入。

久坐分钟数和睡眠

久坐分钟数不包括睡眠时间。在每日汇总中，久坐分钟数的计算方法是从一天的总分钟数（1,440 分钟）中减去睡眠分钟数和活跃分钟数（轻度活跃、中度活跃和非常活跃）：

Sedentary Minutes = 1440 - Sleep Minutes - Lightly Active Minutes - Moderately Active Minutes - Very Active Minutes

身体质量指数 (BMI)

由于 Google Health API 不提供内置的 BMI 数据类型，因此应用必须使用身高和体重记录在客户端计算身体质量指数：

  1. 从体重数据类型的 weightGrams 字段中检索用户的体重（以克为单位）。将此值转换为千克（除以 1,000）或磅（除以 453.59237）。
  2. 从身高数据类型的 heightMillimeters 字段中检索用户的身高（以毫米为单位）。将此值转换为米（除以 1,000）或英寸（除以 25.4）。
  3. 使用以下公式之一计算 BMI 值：
    • 指标公式： BMI = weight (kg) / [height (m)]^2
    • 英制公式： BMI = (weight (lbs) / [height (in)]^2) * 703

BMI 值对应于以下类别：

体重类别 BMI 范围
体重过轻 低于 18.5
健康体重 18.5 至 24.9
超重 25 至 29.9
肥胖 30 或更高版本

基础代谢率 (BMR)

基础代谢率 (BMR) 是指在静息状态下维持基本身体机能所需的最低卡路里数。由于 Google Health API 不提供内置的 BMR 数据类型，因此应用必须使用 Harris-Benedict 公式在客户端计算 BMR。如需了解详情，请参阅维基百科上的哈里斯-本尼迪克特公式文章。

如需执行此计算，请执行以下操作：

  1. 从体重数据类型的 weightGrams 字段中检索用户的体重（以克为单位），并转换为公斤（除以 1,000）。如需将磅转换为千克，请除以 2.2。
  2. 从 Height 数据类型的 heightMillimeters 字段中检索用户的身高（以毫米为单位），并转换为厘米（除以 10）。如需将英寸转换为厘米，请乘以 2.54。
  3. 从个人资料资源中的 age 字段检索用户的年龄（以年为单位）。
  4. 由于 Google Health API 不会公开此字段，因此请单独检索生理性别（例如，通过提示用户或在您自己的数据库中维护此信息）。
  5. 根据用户的生理性别，使用以下公式之一：
    • 男性： BMR = 66 + (13.7 x weight_kg) + (5 x height_cm) - (6.8 x age_years)
    • 女性： BMR = 655 + (9.6 x weight_kg) + (1.8 x height_cm) - (4.7 x age_years)

每日总能量消耗 (TDEE)

每日总能量消耗 (TDEE) 是指一个人一天内消耗的总卡路里数的估算值，其中考虑了 BMR 和身体活动。如需估算用户的 TDEE，请将 BMR 值乘以与其生活方式对应的活动系数：

activity 级别 说明 系数
久坐 几乎不运动。 BMR x 1.2
轻度活跃 每周锻炼 1-3 天。 BMR x 1.375
中等活跃 每周锻炼 3-5 天。 BMR x 1.55
非常活跃 每周锻炼 6-7 天。 BMR x 1.725
非常活跃 高强度锻炼或体力工作。 BMR x 1.9

端点

REST 端点对所有数据类型采用一致的语法。

  • 服务端点：基础 HTTP 网址更改为 https://health.googleapis.com。
  • 端点语法：Google Health API 支持有限数量的端点，这些端点可供大多数受支持的数据类型使用。这为所有数据类型提供了统一的语法，并使端点更易于使用。
  • 用户标识符：应在端点语法中指定用户 ID 或 me。使用 me 时，系统会从访问令牌中推断用户 ID。

示例：以下是使用 Google Health API 调用的 GET Profile 端点的示例

GET https://health.googleapis.com/v4/users/me/profile

端点映射

如需查看可用数据类型及其支持的 API 方法的列表，请参阅 Google Health API 数据类型表格。

Fitbit Web API 端点类型 Google Health API
GET（日志 | 摘要 | 每日摘要），其中您请求的是单日数据 dailyRollup 方法，windowSize = 1 天
GET（日内），用于请求精细数据 list 方法
GET（时序）- 按日期或时间间隔 rollUp 或 dailyRollUp 方法（包含日期范围）
GET（日志列表） list 方法
CREATE 和 UPDATE 日志 patch 方法
删除日志 batchDelete 方法
GET Profile users.getProfile 返回用户的特定信息
users.getSettings 返回用户的单位和时区
更新个人资料 users.updateProfile 修改用户的特定信息
users.updateSettings 修改用户的单位和时区
获取用户 ID users.getIdentity 会返回用户的 Fitbit 旧版用户 ID 和 Google 用户 ID。
获取设备 users.pairedDevices 会返回已配对的设备列表
创建订阅 projects.subscribers.subscriptions.create 手动创建订阅
删除订阅 projects.subscribers.subscriptions.delete 删除订阅
获取订阅列表 projects.subscribers.subscriptions.list 列出所有订阅