terra-data

Terra Data 是一个用于通过 Terra API 获取和管理健康数据的技能，可从 150 多种可穿戴设备拉取数据。

用途

该技能面向需要从可穿戴设备获取健康数据的开发场景，通过 Terra API 统一访问多个设备提供商的数据。

主要能力

支持以下数据类型：

Activity：锻炼会话及指标，每次锻炼完成后更新。
Sleep：睡眠阶段、时长、HRV，每次睡眠会话后更新。
Body：体重、身体成分、血糖，每天多次更新。
Daily：聚合的每日摘要，每天多次更新。
Nutrition：餐食、宏量营养素、卡路里，每次记录餐食时更新。
Menstruation：周期跟踪、症状，每次更新时同步。
Athlete：用户资料、人口统计信息，变更时更新。

使用方式

通过 Python 客户端初始化 Terra 实例，然后调用对应数据类型的 get 方法。示例：

from terra import Terra
from datetime import datetime, timedelta

client = Terra(
    dev_id="botaniqalmedtech-testing-SjyfjtG33s",
    api_key="_W7Pm-kAaIf1GA_Se21NnzCaFZjg3Izc"
)

end_date = datetime.now()
start_date = end_date - timedelta(days=7)

response = client.activity.get(
    user_id="terra_user_abc123",
    start_date=start_date,
    end_date=end_date
)

for activity in response.data:
    print(f"{activity.metadata.type}: {activity.calories_data.total_burned_calories} cal")

各数据类型均提供对应的 get 方法，如 get_activity、get_sleep、get_daily、get_body、get_nutrition、get_menstruation、get_athlete。

支持批量数据获取，可一次性拉取所有数据类型。

支持历史数据回填，对于超过 28 天的请求，使用 to_webhook=True 进行异步处理，结果通过 webhook 发送。

部分提供商支持数据写入，例如向 Wahoo 发布活动、向 Fitbit 发布营养数据、向 Apple Health 发布计划锻炼。

适用场景

适用于需要整合多个可穿戴设备健康数据的应用开发，如健康管理平台、健身应用、医疗研究等。

限制

不同提供商的历史数据上限不同：Garmin 5 年、Fitbit 10 年、Oura 3 年、WHOOP 2 年、Polar 30 天、COROS 3 个月、Withings 2 年。
数据写入仅限部分提供商支持。
超过 28 天的历史数据请求为异步处理，结果通过 webhook 返回。
Daily、Body、Nutrition 数据每天多次发送，应采用覆盖更新策略；Activity、Sleep 会话唯一，采用插入或忽略策略。

技能介绍

用途

主要能力

使用方式

适用场景

限制

相关技能