terra-routes

Terra API 路由

Terra API Routes 是一款写入设备的产品（预发布）：只需定义一次包含航点的 GPS 路线，Terra API 就会将其推送到用户已连接的设备上，以便在设备上导航。用户下次同步设备后，路线便会显示在手表或自行车码表上，因此你的应用无需处理各提供商原生的路线格式。

目前仅支持 Garmin、COROS 和 Wahoo。它们的功能覆盖范围差异很大（请参阅下方的提供商矩阵），因此除非你确定所有用户都使用 Garmin，否则请按最低共同标准设计路线。

账户工具：CLI 或 MCP

Routes 处于预发布阶段，因此没有账户命令，其端点也未包含在 CLI 随附的 API 描述中：terra admin-api list --data-api 不会显示这些端点。terra data-api 仍会发送这些请求，因为验证路径的是服务端，而不是 CLI：

terra data-api /routes -X POST --body-file route.json
terra data-api /pushedRoutes -q user_id=<uuid>

添加 -i 可显示状态行，添加 --jq 可筛选响应；除非传入 --yes，否则 DELETE 请求会要求确认。

Routes 相关的账户配置确实提供了命令。运行 terra unified-api sources list --env <dev-id> 可查看下方哪些设备已启用；运行 terra users list --env <dev-id> --provider GARMIN 可查看某个用户是否已连接，可向其推送路线。

路线请求本身使用 terra data-api，该命令仅 CLI 提供；通过 MCP 时，管理工具仅覆盖已启用的提供商和已连接的用户。

在编码 Agent（Claude Code、Codex、Cursor 等，无论是在用户的设备上还是云端）中，请使用 CLI；如果未安装，请提供安装方式：在 macOS 和 Linux 上运行 curl -fsSL https://cli.tryterra.co/install.sh | sh，在 Windows PowerShell 中运行 irm "https://cli.tryterra.co/install.ps1" | iex，或者在用户已使用 Homebrew 或 npm 的情况下使用它们。在聊天助手（claude.ai、Claude Desktop、ChatGPT）中，即使可以运行代码，也请使用 Terra API 管理 MCP 服务：其沙盒无法安装 CLI 或登录。每条管理命令都对应一个工具，其名称和 method 表明了命令内容（terra users list 对应 users_read，method: "list"）。只有 CLI 提供 terra data-api、terra admin-api 和 terra examples，而 --select 和 --jq 没有对应的 MCP 功能。terra-cli 和 terra-mcp 技能包含安全措施（确认更改、避免在对话记录中暴露凭据）、错误说明，以及针对每项任务的操作指南。它们用于管理集成，并不能替代本技能介绍的 API 调用。

两阶段工作流

Routes 始终分两步：先创建可重复使用的模板，再将该模板推送给一个或多个用户。

Phase 1  POST /routes                          -> route_id           (create template once)
Phase 2  POST /routes/{route_id}/push?user_id=X -> pushed_route_id    (push to a user's device)
                                                    provider_route_id

路线会在用户下次同步时到达设备。基础 URL 为 https://access.tryterra.co/api/v2。每个请求都需要两个请求头：dev-id 和 x-api-key。

curl -X POST "https://access.tryterra.co/api/v2/routes" \
  -H "Content-Type: application/json" \
  -H "dev-id: YOUR_DEV_ID" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "name": "Morning Run Loop",
    "sport": "running",
    "waypoints": [
      { "latitude": 51.5074, "longitude": -0.1278 },
      { "latitude": 51.5150, "longitude": -0.1200 }
    ]
  }'
# -> { "status": "success", "route_id": "295581149349019648" }

curl -X POST "https://access.tryterra.co/api/v2/routes/295581149349019648/push?user_id=USER_ID" \
  -H "dev-id: YOUR_DEV_ID" \
  -H "x-api-key: YOUR_API_KEY"
# -> { "status": "success", "pushed_route_id": "...", "provider_route_id": "..." }

端点

方法	端点	描述
POST	/routes	创建路线模板
GET	/routes	列出所有模板
GET	/routes/{id}	获取一个模板
PUT	/routes/{id}	更新模板，部分更新（200）
PUT	/routes/{id}?cascade	更新并重新推送到所有设备，异步处理（202）
DELETE	/routes/{id}	删除模板
POST	/routes/{id}/push?user_id=X	将路线推送到用户的设备
GET	/pushedRoutes?user_id=X	列出用户已推送的路线
GET	/pushedRoutes/{id}?user_id=X	获取一条已推送的路线
DELETE	/pushedRoutes/{id}?user_id=X	移除一条已推送的路线

更新语义。 PUT /routes/{id} 的行为类似补丁，并返回 200：所有字段均为可选项，且只会更新你提供的字段（航点、speed_meters_per_second 和海拔，以及名称、描述和运动类型）。此操作不会影响已推送到设备的路线。添加 ?cascade 还会将更新后的路线重新推送到此前发送过该路线的所有设备；此操作异步执行，并返回 202 Accepted。Cascade 是发起后即不再跟踪的操作：重新推送失败只会记录在服务端日志中，不会在响应或 GET /pushedRoutes 中显示，因此 API 无法发现部分失败。若要确认设备确实收到了更新，请明确向该用户重新推送，或在设备上通过其他方式验证。

数据模型

RouteTemplate

字段	必填	说明
name	是	设备上显示的路线名称，不可为空
sport	是	以下列出的某种运动类型
waypoints	是	GPS 点数组，至少包含 2 个点
description	否	仅 Garmin 支持
elevation_gain_meters	否	总爬升，单位为米
elevation_loss_meters	否	总下降，单位为米
speed_meters_per_second	否	路线平均速度目标，仅 Garmin 支持

Waypoint

字段	必填	说明
latitude	是	十进制度数，范围为 -90 至 90
longitude	是	十进制度数，范围为 -180 至 180
elevation_meters	否	海拔高度，单位为米
course_point	否	此途经点处的 POI 标记，仅 Garmin 支持

course_point 的格式为 { "type": ..., "name": ... }。API 架构包含 15 种类型：generic、summit、valley、water、food、danger、first_aid、sprint、segment_start、segment_end、left、right、straight、left_fork、right_fork。文档仅说明 Garmin 支持前 10 种（POI 类型）；除非已根据当前服务提供商的行为进行验证，否则不要依赖后 5 种转向类型（参见注意事项）。

运动类型（8 种）：running、trail_running、hiking、cycling、road_biking、mountain_biking、gravel_cycling、other。cycling 与 road_biking 不同，但在 Garmin 上会映射为 ROAD_CYCLING。

验证规则（创建和更新时会返回硬性 400 错误）：name 不可为空，最长 255 个字符；description 最长 2,000 个字符；sport 必须有效；途经点数量为 2 至 10,000 个；纬度范围为 -90..90；经度范围为 -180..180；elevation_meters 范围为 -500..9000；speed_meters_per_second 必须大于 0。

服务提供商对照表

功能	Garmin	COROS	Wahoo
传输格式	JSON	GPX	base64 FIT
推送	是	是	是
重新同步	是	是（重新 POST 新 GPX）	是
删除	是	否	是
路线点（POI）	是	否	否
速度目标	是	否	否
描述	是	否	否

三者都支持重新同步。COROS 不支持原位更新，因此重新同步时会重新 POST 一个新的 GPX 文件，同时 provider_route_id 保持不变。只有 Garmin 和 Wahoo 支持删除。

注意事项

• 仅 Garmin 支持的字段在其他平台上会被静默忽略。 Garmin 会识别 course_point、speed_meters_per_second 和 description，但 COROS 和 Wahoo 会静默忽略这些字段。除非所有目标用户都使用 Garmin，否则不要依赖这些字段。
• Garmin 路线的海拔数据必须全部提供或全部不提供。 如果部分航点包含 elevation_meters，而其他航点没有，Terra API 会丢弃所有海拔值，并由 Garmin 自带的海拔模型填充。请为每个航点都提供海拔，或都不提供。
• 路线点错误可能出现在不同阶段。 无效的 type 字符串会在 POST /routes 时因创建阶段的枚举校验而返回 400。五种转向类型（left、right、straight、left_fork、right_fork）可以通过创建阶段的校验，但不属于 Garmin 文档中列出的 10 种路线点类型——推送时如何处理这些类型并无保证（可能报错或将其丢弃），因此除非已验证当前行为，否则请仅使用 Garmin 支持的 10 种兴趣点类型。
• COROS 支持最有限。 不支持删除（删除操作只会从 Terra API 的数据库中移除记录，路线仍保留在设备上），不支持检索，而且会将所有运动类型合并为两种内部类型（跑步和骑行），因此设备显示可能无法区分砾石路骑行和公路骑行等类型。
• 重复推送同一模板会创建重复路线。 每次推送都会创建一条新路线，不会去重。如果需要避免设备上出现重复路线，请自行记录 pushed_route_id 值。
• 未提供海拔时会自动计算，具体处理方式取决于服务提供商。
• 不支持的操作仍会返回成功。 例如，对 COROS 执行删除操作会返回成功响应，但路线仍保留在设备上。

参考资料

• references/provider-details.md – 各服务提供商的行为：Garmin 重新同步时先执行 PUT 再执行 POST，以及海拔标准化；Wahoo 稳定的 terra-{pushed_route_id} 外部 ID 和细粒度运动类型映射；COROS 每次推送都会生成唯一 GPX，以及 provider_route_id 的含义。当路线在不同设备上的行为不一致，或需要调试重新同步或删除操作时，请阅读此文件。

如需查看上文之外的完整负载示例（包含路线点的越野跑、带速度目标的公路骑行、仅含 2 个航点的最简路线），请获取实时页面：https://docs.tryterra.co/routes-api-pre-release/sport-specific-examples.md

完整文档：Routes API 概览、简介、核心概念、服务提供商兼容性。获取页面前，请先使用 terra docs ask（或通过 MCP 使用 docs_ask）提问：它会根据文档作答并注明来源。任何文档 URL 后都可以加上 .md，以获取 Markdown 格式。

注意：Routes 文档空间仍处于预发布阶段，相关页面可能尚未发布。如果上面的页面返回“Page Not Found”，请以此工具包附带的参考资料为准，并对照实时 API 进行验证。