一、公共
1. 调用超量说明
- 开发者应按业务必要性控制调用频率,优先使用时间窗口、分页 cursor 和订阅通知能力,避免高频全量轮询。
2. 服务器地址&公共传入参数
域名:https://hlthopen.io.mi.com/
3. 高级特性extra
| 应用环境 | scope_id | 权限名称 | 读/写 | 备注 |
| 线上环境 | 200016 | 步数数据 | read | |
| 200001 | 卡路里数据 | read | ||
| 200002 | 中高强度活动数据 | read | ||
| 200003 | 有效站立活动数据 | read | ||
| 200017 | 活力指标 | read | ||
| 200004 | 运动记录概要数据 | read | 具体运动key | |
| 200005 | 运动记录详情数据 | |||
| 200006 | 运动记录位置数据 | |||
| 200007 | 心率数据 | read | ||
| 200008 | 血氧数据 | read | ||
| 200009 | 睡眠数据 | read | ||
| 200010 | 体重数据 | read | ||
| 200011 | 最大摄氧量数据 | read | ||
| 200019 | 压力数据 | read | ||
| 200012 | 读取设备数据 | read | ||
| 200018 | 个人信息数据 | read | ||
| 200013 | 一个月 | read | 数据范围 | |
| 200014 | 三个月 | read | ||
| 200015 | 一年 | read |
二、认证鉴权
2.1 认证鉴权说明
- 访问小米运动健康数据平台需满足前置依赖:依托客户端 ID 完成小米账号接入,换取访问令牌 Access Token;该令牌为用户调用数据平台开放 API 的必备授权凭证。
- 生成 Access Token 的前置条件:开发者已在小米开放平台申请了账号服务,开通了小米运动健康服务,应用申请的权限已审批通过。
2.2 授权码模式生成示例
请求详情可参考小米账号服务:https://dev.mi.com/xiaomihyperos/documentation/detail?pId=1708
2.2.1 获取授权码(authorization_code)
A. 接口说明
| 请求方法 | HTTPS GET |
| 请求地址 | https://account.xiaomi.com/oauth2/authorize |
B. 请求参数
| 参数名称 | 必须 | 类型 | 备注 |
| client_id | 是 | long | 申请应用时分配的应用 ID,可以在应用详情页获取 |
| redirect_uri | 是 | string | 回调地址, 必须和申请应用时填写的一致(参数部分可不一致) |
| response_type | 是 | string | 描述获取授权的方式, 这里 response_type=code |
| scope | 否 | string | 开放数据接口权限 ID,可以传递多个,用空格分隔,具体值可以参考「细粒度授权项」 |
| scope_provider | 是 | string | healthkit |
| state | 否 | string | 随机字符串,授权请求成功后原样返回,该参数用于防止 CSRF 攻击,强烈建议传递该参数 |
| skip_confirm | 否 | boolean | 默认值为true,授权有效期内的用户在已登录情况下,不显示授权页面,直接通过。如果需要用户每次手动授权,设置为false |
C. 响应参数
| 参数名称 | 必须 | 类型 | 备注 |
| code | 是 | string | 用来换取 access_token 的授权码,有效期为 10 分钟且只能使用一次 |
| state | 否 | string | 如果请求时传递参数,会回传该参数 |
示例:
直接不写scope=多少,直接指定scope_provider=healthkit,会采用三方所有拥有权限的scope,用法举例:
https://account.xiaomi.com/oauth2/authorize?pt=0&client_id=xxxx&redirect_uri=xxxx&response_type=code&skip_confirm=false&scope_provider=healthkit
如果授权成功,授权服务器会将用户的浏览器重定向到 redirect_uri,并带上相关参数:
http://example.com/example?code=CODE&state=STATE请求响应成功,用户登录之后,将会展现授权页面,如下图所示:

2.2.2 获取访问令牌(access_token)
A. 接口说明
| 请求方法 | HTTPS POST/GET |
| 请求地址 | https://account.xiaomi.com/oauth2/token |
| 编码格式 | application/x-www-form-urlencoded |
B. 请求参数
| 参数名称 | 必须 | 类型 | 备注 |
| code | 是 | string | 第1小节中拿到的授权码,有效期为 10 分钟且只能使用一次 |
| client_id | 是 | long | 申请应用时分配的应用 ID,可以在应用详情页获取 |
| redirect_uri | 是 | string | 回调地址, 必须和申请应用时填写的一致(参数部分可不一致) |
| client_secret | 是 | string | 申请应用时分配的 AppSecret |
| grant_type | 是 | string | 这里 grant_type=authorization_code |
C. 响应参数
| 参数名称 | 必须 | 类型 | 备注 |
| access_token | 是 | string | 访问令牌 |
| expires_in | 是 | long | 访问令牌生命周期(单位:秒) |
| refresh_token | 是 | string | 刷新令牌 |
| scope | 是 | string | 访问令牌实际权限范围 |
| mac_key | 是 | string | MAC类型访问令牌对应的加密密钥 |
| mac_algorithm | 是 | string | MAC类型访问令牌对应的加密算法,目前只支持HMacSha1 |
| openId | 是 | string | 用户在APP内的唯一标识 |
| union_id | 是 | string | 同一用户,在同一个开发者下的不同应用中,获取到的union_id是相同的 |
注意: 返回值前面的 &&&START&&& 可以直接去掉。
2.2.3 Refresh Token授权管理
通过 refresh_token 更新 access_token
A. 接口说明
| 请求方法 | HTTPS POST/GET |
| 请求地址 | https://account.xiaomi.com/oauth2/refresh/token |
| 编码格式 | application/x-www-form-urlencoded |
| 使用约束 | 单个client_id <= 5000次/s,超过限制返回 http code=503 |
B. 请求参数
| 参数名称 | 必须 | 类型 | 备注 |
| pt | 是 | int | 平台 ID, 0 表示 dev.mi.com, 1 表示 developers.xiaoai.mi.com,默认为 0 |
| client_id | 是 | long | 申请应用时分配的应用 ID |
| redirect_uri | 是 | string | 回调地址, 必须和申请应用时填写的一致 |
| client_secret | 是 | string | 申请应用时分配的 app_secret |
| grant_type | 是 | string | 这里 grant_type=refresh_token |
| refresh_token | 是 | string | 授权码模式下发访问令牌时下发的刷新令牌 |
C. 响应参数
| 参数名称 | 必须 | 类型 | 备注 |
| access_token | 是 | string | 访问令牌 |
| expires_in | 是 | long | 令牌生命周期(单位:秒),默认为 2 小时 |
| refresh_token | 是 | string | 更新后的刷新令牌 |
| scope | 是 | string | 访问令牌实际权限范围 |
| mac_key | 是 | string | MAC类型访问令牌对应的加密密钥 |
| mac_algorithm | 是 | string | MAC类型访问令牌对应的加密算法,目前只支持HMacSha1 |
| open_id | 是 | string | 用户在APP内的唯一标识 |
2.3 OAuth 开放鉴权信息
更多小米账号 OAuth 2.0开放鉴权的相关信息,请参见小米账号服务-OAuth2.0 授权码模式
三、取消授权
3.1 取消授权说明
- 第三方可调用取消授权接口,解除当前小米账号对应的授权绑定关系。
- 如果你的应用还没有上线取消授权功能,可按照下面步骤手动撤销小米运动健康服务的授权:在“小米运动健康App > 我的 > 三方数据管理”选取您的想要取消授权的应用,进行取消授权。
3.2 取消授权接口
A. 接口说明
| 承载协议 | HTTPS POST |
| 接口URL | 线上:http://open.account.xiaomi.com/user/unbindOAuth2Grained |
| 数据格式 | 请求消息:application/x-www-form-urlencoded |
B. 请求参数
| 参数名称 | 参数类型 | 是否必选 | 描述 | 备注 |
| access_token | String | 是 | ||
| client_id | String | 是 | 三方应用的用户标识 | |
| client_secret | String | 是 |
- 请求示例
curl 'https://open.account.xiaomi.com/user/unbindOAuth2Grained' \
--compressed \
-X POST \
-H 'User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:139.0) Gecko/20100101 Firefox/139.0' \
-H 'Accept: */*' \
-H 'Accept-Language: zh-CN,zh;q=0.8,zh-TW;q=0.7,zh-HK;q=0.5,en-US;q=0.3,en;q=0.2' \
-H 'Accept-Encoding: gzip, deflate, br, zstd' \
-H 'content-type: application/x-www-form-urlencoded' \
-H 'Origin: moz-extension://62efe7ae-dd4f-468c-8613-90bbfd9457fe' \
-H 'Connection: keep-alive' \
-H 'Cookie: deviceId=wb_a692c63e-74d9-48b3-8b10-baa29dcb3182; _ga_XWN774PE8J=GS2.1.s1746615708$o8$g1$t1746615954$j0$l0$h0; _ga=GA1.1.102207318.1697539411; pass_ua=web; zhangluwenAccount=account; zhangluwenXiaomi=xiaomiTest; uLocale=zh_CN' \
-H 'Sec-Fetch-Dest: empty' \
-H 'Sec-Fetch-Mode: cors' \
-H 'Sec-Fetch-Site: same-origin' \
-H 'Priority: u=0' \
-H 'Pragma: no-cache' \
-H 'Cache-Control: no-cache' \
--data-raw 'access_token=xxxxxx&client_id=xxxxxx&client_secret=xxxxxxx'C. 响应参数
| 参数名称 | 参数类型 | 是否必选 | 描述 | 备注 |
| clientId | String | 是 | 三方应用的用户标识 | |
| openId | String | 是 | 用户openId | |
| unionId | String | 是 | ||
| deleteResult | int | 是 |
响应示例
- 判断是否解绑成功的唯一标志:code=0;
- 若失败,则会返回code、result、description可按需查看原因;
- 若成功,则会返回code、result、description和data,data的字段可按需获取;
{
"data": {
"clientId": "xxxxxx",
"openId": "2.0:9/HBNgHaDlv",
"unionId": "z4oPDC6J8m8OYU3E0w",
"deleteResult": 1
},
"result": "ok",
"code": 0,
"description": "no error",
"traceId": "fb7b2fdbf1ba1692f979c80e8ef26bab"
}公共参数说明
| 字段名 | 类型 | 是否必填 | 说明 | 备注 |
| Content-Type | String | 是 | 目前仅支持application/json | |
| Authorization | String | 是 | 标准OAuth2鉴权header,格式:Bearer ${access_token} access_token获取参考 https://dev.mi.com/xiaomihyperos/documentation/detail?pId=1708 | - 需传参数: scope_provider=healthkit - 线上:https://account.xiaomi.com |
| X-Client-ID | String | 是 | 小米开放平台分配的应用标识; | |
| X-Trace-Id | String | 否 | 请求跟踪ID,用于串联服务调用方与服务端整体请求链路,建议携带; | |
| X-Client-Nonce | String | 是 | 生成规则:总共12个byte(nonceBytes) - 前4个byte为uint32的随机数,以大端对齐; - 中间4个byte为uint32的随机数,以大端对齐; - 末尾4个byte为当前时间戳的分钟数,即unix时间戳 / 60,保留整数,以大端对齐 最后将12个字节进行base64 url safe编码。 nonce=Base64.Encoder.RFC4648(nonceBytes) | 不可重复 |
四、接口定义
五、数据模型
AppInfo
| 参数 | 参数类型 | 是否必须 | 说明 | 约束条件 |
| appPackageName | String | 是 | 应用程序的包名称。长度范围:1~300 如果appPackageName/clientId同时存在,appPackageName/clientId必须匹配。 | |
| appVersion | String | 是 | 应用的版本信息 | |
| clientId | String | 否 | 应用ID | |
| detailUrl | String | 否 | 用于链接该应用程序的URL |
BindList
| 参数 | 参数类型 | 是否必须 | 说明 | 约束条件 |
| appInfo | AppInfo | 否 | app信息 | |
| bindInfo | BindInfo | 否 | 绑定信息 |
BindInfo
| 参数 | 参数类型 | 是否必须 | 说明 | 约束条件 |
| deviceName | String | 是 | 设备名称 | |
| updateTime | Long | 是 | ||
| deviceCate | Int | 否 | 设备类型:1-手动添加;2-手机添加;3-其它;5-手表;6-手环;7-秤; | 「查询用户当前绑定设备」接口: 仅支持手表/手环 |
| deviceId | String | 否 | 设备id |
DeviceInfo
| 参数 | 参数类型 | 是否必须 | 说明 | 约束条件 |
| deviceType | String | 是 | 设备类型 | |
| manufacturer | String | 是 | 产品制造商 | |
| modelNum | String | 是 | 终端型号名称 | |
| uniqueId | String | 是 | 小米设备唯一标识UDID或其他厂商设备唯一标识 | |
| version | String | 否 | ||
| bindStatus | String | 否 | 绑定状态 |
DataSet
| 参数 | 参数类型 | 是否必须 | 说明 | 约束条件 |
| sourceId | Long | 是 | 数据源ID | |
| startTime | Long | 是 | 所有采样点最小开始时间,单位:毫秒 | |
| endTime | Long | 是 | 所有采样点最大结束时间,单位:毫秒 | |
| dataPoints | List<DataPoint> | 是 | DataPoint列表 | |
| zoneName | String | 是 | 时区信息 | |
| cursor | String | 否 | GET查询分页标识,且仅当查询结果大于一页时才包含。 |
DataPoint
| 参数 | 参数类型 | 是否必须 | 说明 | 约束条件 |
| dataTypeName | String | 是 | 数据类型名称 | |
| startTime | Long | 是 | 开始时间,单位:毫秒 | |
| endTime | Long | 是 | 结束时间,单位:毫秒 | |
| value | List<DataPointValue> | 是 | 数据值。数据的顺序和类型需要与DataSource中dataType定义保持一致。 | |
| modifyTime | Long | 否 | 最后修改采样点的时间,单位:毫秒 | |
| originDataSourceId | String | 否 | 原始数据采集器ID。仅在该DataPoint被包含在派生dataSource的DataSet中时有效。 | |
| metaData | String | 否 | 扩展元,JSON格式字符串; |
DataPointValue
| 参数 | 参数类型 | 是否必须 | 说明 | 约束条件 |
| fieldName | String | 是 | 字段名称 | |
| floatValue | Double | 否 | 浮点数值 | 同时只有一个字段生效 |
| integerValue | int | 否 | 整数值 | |
| longValue | Long | 否 | 长整型 | |
| mapValue | List<SamplePointMap> | 否 | Map值 | |
| stringValue | String | 否 | 字符串值。 |
DataType
| 参数 | 参数类型 | 是否必须 | 说明 | 约束条件 |
| name | String | 是 | 每个数据类型唯一的、命名空间的名称。 | 小米提供一组以 com.xiaomi. 命名空间开头的的健康数据类型; |
| field | List<TypeField> | 是 | 数据类型的维度。 |
TypeField
| 参数 | 参数类型 | 是否必须 | 说明 | 约束条件 |
| name | String | 是 | 每个数据类型唯一的、命名空间的名称。 | field 不能重复 |
| format | String | 是 | 数据类型的维度。 | 支持格式:float/integer/map/string/long |
| desc | String | 否 | 描述信息 | |
| optional | Bool | 否 | 对应数据赋值时是否必填:true:可选false:必选未配置时,默认必选。 |
DataSource
| 参数 | 参数类型 | 是否必须 | 说明 | 约束条件 |
| appInfo | AppInfo | 是 | 数据源对应的应用程序信息 | |
| sourceDataType | DataType | 是 | 数据类型定义 | |
| sourceType | String | 是 | 数据源类型常量。支持以下取值: - raw:原始数据类型 - derived:派生数据类型 | |
| sourceName | String | 否 | 数据源名称 | |
| deviceInfo | DeviceInfo | 否 | 集成各种传感器的硬件设备描述。例如:手表、手环等可穿戴设备。 | |
| sourceId | String | 否 | 数据源ID | |
| name | Bool | 否 | 用户页面展示的数据采集器名称。 | |
| lastUpdateTime | Long | 否 | 向此数据采集器中上传或删除采样数据的最后更新时间。 |
SportSummary
| 参数 | 参数类型 | 是否必须 | 说明 | 约束条件 |
| durationSummary | DurationSummary | 否 | ||
| dataSummary | list<DataPoint> | 否 | 统计数据类型采样点列表。 | 只能是统计类型。建议开发者写入该字段。 |
| paceSummary | PaceSummary | 否 | 配速信息 | |
| sportFeature | DataPoint | 否 | 运动记录特征数据点 | |
| sectionSummary | List<DataSection> | 否 | 运动记录分段统计数据采样点列表。 | |
| displaySummary | DisplaySummary | 否 | 运动记录训练表现数据 |
DurationSummary
| 参数 | 参数类型 | 是否必须 | 说明 | 约束条件 |
| duration | Integer | 否 | duration |
PaceSummary
| 参数 | 参数类型 | 是否必须 | 说明 | 约束条件 |
| maxPace | Integer | 否 | 最大配速,游泳单位是秒/百米, 非游泳是秒/km | |
| minPace | Integer | 否 | 最小配速,游泳单位是秒/百米, 非游泳是秒/km | |
| avgPace | Integer | 否 | 平均配速,游泳单位是秒/百米, 非游泳是秒/km |
SportRecord
| 参数 | 参数类型 | 是否必须 | 说明 | 约束条件 |
| appInfo | AppInfo | 否 | 数据源对应的应用程序信息 | |
| startTime | Long | 是 | 开始时间,单位:毫秒;startTime与endTime相隔时间不能超过5天。 | |
| endTime | Long | 是 | 结束时间,单位:毫秒;startTime与endTime相隔时间不能超过5天。 | |
| zoneName | String | 是 | 时区信息。 | |
| sportKey | String | 否 | 运动记录对应的运动类型常量的取值。例如:running对应xx。 | |
| deviceInfo | DeviceInfo | 否 | 集成各种传感器的硬件设备描述。例如:手表、手环等可穿戴设备。 | |
| sportSummary | SportSummary | 是 | 运动记录的概要汇总信息。 | |
| subDataRelation | List<DataPointRelation> | 否 | 子数据关联关系。 | |
| modifyTime | Long | 否 | 运动记录的最后修改时间。若用户创建activityRecords时填写了modifyTime,界面返回用户创建的activityRecords信息时将返回传入的modifyTime值;否则不返回。 |
HealthRecord
| 参数 | 参数类型 | 是否必须 | 说明 | 约束条件 |
| dataTypeName | String | 是 | 数据类型名称 | |
| startTime | Long | 是 | 开始时间,单位:毫秒 | |
| endTime | Long | 是 | 结束时间,单位:毫秒 | |
| value | List<DataPointValue> | 是 | 数据值。数据的顺序和类型需要与DataSource中dataType定义保持一致。 | |
| modifyTime | Long | 否 | 最后修改采样点的时间,单位:毫秒 | |
| originDataSourceId | String | 否 | 原始数据采集器ID。仅在该DataPoint被包含在派生dataSource的DataSet中时有效。 | |
| metaData | String | 否 | 扩展元,JSON格式字符串; | |
| subDataRelation | List<DataPointRelation> | 否 | 子数据关联关系。 | |
| subData | Map<String,DataSet> | 否 | 子数据 |
DataPointRelation
| 参数 | 参数类型 | 是否必须 | 说明 | 约束条件 |
| dataTypeName | String | 是 | 数据类型名称 | |
| startTime | Long | 是 | 开始时间,单位:毫秒 | |
| endTime | Long | 是 | 结束时间,单位:毫秒 | |
| sourceId | String | 是 | 原始数据采集器ID。 |
AbnormalPoint
| 参数 | 参数类型 | 是否必须 | 说明 | 约束条件 |
| startTime | Long | 是 | 开始时间,单位:毫秒 | |
| endTime | Long | 是 | 结束时间,单位:毫秒 | |
| value | integer | 是 | 异常记录值 |
Group
| 参数 | 参数类型 | 是否必须 | 说明 | 约束条件 |
| startTime | Long | 是 | 开始时间,单位:毫秒 | |
| endTime | Long | 是 | 结束时间,单位:毫秒 | |
| dataSet | List<DataSet> | 是 | 详情 |
EventType
| 参数 | 参数类型 | 是否必须 | 说明 | 约束条件 |
| eventType | String | 是 | 订阅事件类别 | |
| subType | String | 是 | 订阅事件子类别 |
SubscribeInfo
| 参数 | 参数类型 | 是否必须 | 说明 | 约束条件 |
| eventType | String | 是 | 订阅事件类别 | |
| subType | String | 是 | 订阅事件子类别 | |
| clientId | int | 是 | 三方client_id | |
| subscriptionId | String | 是 | 订阅记录ID | |
| openId | String | 是 | 用户-appId,组合得到的唯一标识openId |
SourceAndCursor
| 参数 | 参数类型 | 是否必须 | 说明 | 约束条件 |
| sourceId | String | 是 | sourceId | |
| cursor | int64 | 是 | 下次请求cursor |
SportGoal
| 参数 | 参数类型 | 是否必须 | 说明 | 约束条件 |
| goal | int64 | 是 | 目标值 | |
| key | String | 是 | 目标 | |
| modifyTime | int64 | 否 | 时间 |
MetaData
| 参数 | 参数类型 | 是否必须 | 说明 | 约束条件 |
| metaKey | String | 是 | ||
| metaValue | String | 是 |
六、数据类型
七、订阅数据
7.1 交互流程
流程说明:当用户数据发生变化时,实时通知开发者,以便应用拥有用户的最新数据。
- 服务端保存用户的订阅记录信息。
- 用户数据发生变化,实时通知开发者应用。
- 开发者应用收到通知消息,向服务端拉取最新的数据。
7.2 订阅角色
| 角色/事件 | 说明 |
| 订阅者 | 当其用户数据更改时,通知其服务端的回调地址。 |
| 事件 | 用户活动事件。包括用户取消授权、运动记录变化(更新)、原子数据变化(更新)等操作。 |
| 订阅记录 | 记录订阅者、用户、事件之间的关联关系。订阅记录由Subscription ID唯一标识。 |
| 通知 | 云服务向订阅者回调地址发出的通知请求,通知订阅用户事件变化。 |
7.3 订阅事件
| 事件类别(event_type) | 事件子类别(sub_type) | 描述 | 扩展元数据 | 备注 |
| USER_EVENT 用户账号事件 | CANCEL_ALL | 取消授权事件 | 无 | 用户在小米侧解绑 |
| CHANGE_SCOPE | 数据权限变更 | 无 | ||
| FITNESS_DATA_EVENT 采样数据事件 | UPDATE | 新增/更新采样事件 | metaKey: - startTime:数据变化的开始时间 - endTime:数据变化的结束时间 - dataType:原子采样数据类型 - timeZone:时区 - recordDay:日统计记录日期 | |
| FITNESS_AGGREGATED_DATA_EVENT 聚合数据事件 | UPDATE | 新增/更新聚合数据事件 | metaKey: - startTime:数据变化的开始时间 - endTime:数据变化的结束时间 - dataType:原子采样数据类型 - timeZone:时区 - recordDay:日统计记录日期 | |
| FITNESS_RECORD_DATA_EVENT 健康记录事件 | UPDATE | 新增/更新健康记录事件 | metaKey: - startTime:数据变化的开始时间 - endTime:数据变化的结束时间 - datatype:健康记录数据类型 - timeZone:时区 | |
| SPORT_RECORD_DATA_EVENT 运动记录事件 | UPDATE | 新增/更新运动记录事件 | metaKey: - startTime:数据变化的开始时间 - endTime:数据变化的结束时间 - sportKey:ActivityRecord活动类型 - timeZone:时区 |
7.4 支持订阅数据类型
| 事件类别 | 数据类别 | 活动类型/数据类型 | 描述 |
| 采样数据事件 | 健康采样数据 | com.xiaomi.weight.instantaneous | 体重 |
| com.xiaomi.heart_rate.delta | 心率 | ||
| com.xiaomi.spo2.instantaneous | 血氧 | ||
| com.xiaomi.vo2_max.delta | 最大摄氧量 | ||
| 日常活动采样数据 | com.xiaomi.steps.delta | 步数 | |
| com.xiaomi.calories.delta | 卡路里 | ||
| com.xiaomi.exercise_intensity.delta | 中高强度 | ||
| 聚合数据事件 | 日常活动统计数据 | com.xiaomi.steps.total | 步数总量 |
| com.xiaomi.calories.total | 卡路里 | ||
| com.xiaomi.exercise_intensity.statistics | 中高强度 | ||
| com.xiaomi.goal.summary | 活力指标 | ||
| 健康记录事件 | 健康记录数据 | com.xiaomi.sleep.health | 睡眠记录 |
| com.xiaomi.high_heart_rate.health | 心率过速 | ||
| com.xiaomi.low_heart_rate.health | 心率过缓 | ||
| 运动记录事件 | 运动记录 | 参见运动类型常量章节 |
八、运动常量
8.1 运动类型常量
| 运动类型 | 描述 | 运动类型 | 描述 |
| outdoor_walking | 健走 | indoor_fitness | 健身房训练 |
| indoor_walking | 室内步行 | rope_skipping | 跳绳 |
| outdoor_hiking | 户外徒步 | open_swimming | 开放水域游泳 |
| outdoor_running | 户外跑步 | freediving | 自由潜水 |
| indoor_running | 室内跑步 | recreational_scuba_diving | 休闲水肺潜水 |
| climbing | 登山 | instrument_diving | 仪表潜水 |
| outdoor_riding | 户外骑行 | triathlon | 铁人三项 |
| indoor_riding | 室内单车 | rowing_machine | 划船机 |
| race_walking | 竞走 | indoor_rock_climbing | 室内攀岩 |
| cross_hiking | 越野 | outdoor_rock_climbing | 户外攀岩 |
| spinning | 动感单车 | frisbee | 飞盘 |
| spinning_bike | 动感单车(ECO)侧设备 | snowboarding | 单板滑雪 |
| climb_stairs | 爬楼梯 | parallel_skiing | 双板滑雪 |
| elliptical_trainer | 椭圆机 | backcountry_skiing | 越野滑雪 |
| pool_swimming | 泳池游泳 |
8.2 扩展运动常量
| 运动类型 | 描述 | 运动类型 | 描述 |
| free_training | 自由活动 | wall_ball | 墙球 |
| indoor_surfing | 室内冲浪 | dumbbell_training | 哑铃训练 |
| dragon_boat | 龙舟 | barbell_training | 杠铃训练 |
| bmx | 小轮车 | weight_lifting | 举重 |
| high_interval_training | 高强度间歇训练 | dead_lift | 硬拉 |
| yoga | 瑜伽 | bobby_jump | 波比跳 |
| walking_machine | 漫步机 | sit_ups | 仰卧起坐 |
| high_bar | 单杠 | functional_training | 功能性训练 |
| parallel_bars | 双杠 | upper_limb_training | 上肢训练 |
| step_training | 踏步训练 | lower_limb_training | 下肢训练 |
| group_callisthenics | 团体操 | waist_training | 腰腹训练 |
| kickboxing | 搏击操 | back_training | 背部训练 |
| battle_rope | 战绳 | indoor_fitness | 室内健身 |
| mixed_aerobics | 混合有氧 | square_dance | 广场舞 |
| hip_hop_dance | 嘻哈舞 | belly_dance | 肚皮舞 |
| pole_dance | 钢管舞 | ballet | 芭蕾舞 |
| break_dance | 霹雳舞 | street_dance | 街舞 |
| ballroom_dance | 交际舞 | zumba | 尊巴 |
| modern_dance | 现代舞 | national_dance | 民族舞 |
| jiujitsu | 柔术 | jazz | 爵士舞 |
| futsal | 室内足球 | latin_dance | 拉丁舞 |
| footbag | 沙包球 | dance | 舞蹈 |
| bocci | 地掷球 | boxing | 拳击 |
| pelota | 回力球 | wrestling | 摔跤 |
| gateball | 门球 | martial_arts | 武术 |
| dodgeball | 躲避球 | taichi | 太极 |
| shuttlecock_kicking | 踢毽子 | muay_thai | 泰拳 |
| swing | 秋千 | judo | 柔道 |
| motion_sensing_game | 体感游戏 | taekwondo | 跆拳道 |
| foosball | 桌上足球 | karate | 空手道 |
| shuffle_board | 沙狐球 | free_sparring | 自由搏击 |
| e_sports | 电子竞技 | swordswanship | 剑术/剑道 |
| chess | 国际象棋 | fencing | 击剑 |
| draughts | 国际跳棋 | football | 足球 |
| go | 围棋 | basketball | 篮球 |
| bridge | 桥牌 | volleyball | 排球 |
| board_game | 桌游 | baseball | 棒球 |
| sailboat | 帆船 | softball | 垒球 |
| paddle_board | 桨板 | rugby | 橄榄球 |
| water_polo | 水球 | hockey | 曲棍球 |
| aquatic_sport | 水上运动 | pingpong | 乒乓球 |
| surfing | 滑水 | badminton | 羽毛球 |
| canoeing | 皮划艇 | tennis | 网球 |
| kayak_rafting | 皮艇漂流 | cricket | 板球 |
| rowing | 划船 | handball | 手球 |
| motorboat | 摩托艇 | bowling | 保龄球 |
| web_swimming | 蹼泳 | squash | 壁球 |
| driving | 跳水 | billiards | 台球 |
| fancy_swimming | 花样游泳 | shuttlecock | 毽球 |
| snorkeling | 浮潜 | beach_football | 沙滩足球 |
| kite_surfing | 风筝冲浪 | beach_volleyball | 沙滩排球 |
| rock_climbing | 攀岩 | sepak_takraw | 藤球 |
| skate | 滑板 | golf | 高尔夫 |
| roller_skating | 轮滑 | outdoor_skating | 户外滑冰 |
| parkour | 跑酷 | curling | 冰壶 |
| atv | 沙滩车 | snow_sports | 雪上运动 |
| paraglider | 滑翔伞 | snowmobile | 雪地摩托 |
| climbing_machine | 爬楼机 | puck | 冰球 |
| climb_stairs | 爬楼梯 | snow_car | 雪车 |
| stepper | 踏步机 | sled | 雪橇 |
| core_training | 核心训练 | indoor_skating | 室内滑冰 |
| flexibility_training | 柔韧训练 | archery | 射箭 |
| pilates | 普拉提 | darts | 飞镖 |
| gymnastics | 体操 | horse_riding | 骑马 |
| stretch | 拉伸 | tug_of_war | 拔河 |
| strength_training | 力量训练 | hula_hoop | 呼啦圈 |
| cross_fit | 交叉训练CrossFit | fly_kite | 放风筝 |
| aerobics | 健身操 | fishing | 钓鱼 |
| physical_training | 体能训练 | equestrian | 马术 |
| track_and_field | 田径 | racing_car | 赛车 |
九、FAQ
Q1:接口返回鉴权失败怎么办?
请确认:(1) 应用已在开放平台完成注册并获取到有效 AppId/密钥;
(2) 请求时携带了正确的 Authorization 头信息;
(3) 用户已完成授权且授权未被撤销。如问题仍存在,请联系技术支持。
Q2:调用接口返回数据为空?
请确认:(1) 查询时间窗口内确实存在对应类型的数据;
(2) 用户已对该数据类型完成授权(通过查询用户授权信息接口确认);
(3) startTime/endTime 参数为毫秒时间戳且范围不超过限制。
Q3:分页查询如何使用 cursor?
首次请求不传 cursor,响应中如果 hasMore 为 true,则携带返回的 cursor 值发起下一次请求,直到 hasMore 为 false 或无 cursor 返回。
Q4:订阅事件通知未收到回调?
请确认:(1) 回调 URL 可被公网访问;
(2) 订阅已成功创建(通过查询订阅列表确认);
(3) 用户有新数据写入触发了对应事件类型;
(4) 回调服务正确返回 HTTP 200。
Q5:数据类型名称在哪里查询?
请参见本文档"数据类型"章节。常用类型如 com.xiaomi.steps.delta(步数增量)、com.xiaomi.heart_rate(心率)等。
Q6:时间窗口限制是多少?
采样数据类接口要求 startTime 和 endTime 间隔不超过 30 天;多日统计和活力指标接口要求 startDay 和 endDay 间隔不超过 7 天。