terra-routes

Terra API Routes

Terra API Routes はデバイスへの書き込みに対応した製品（プレリリース）です。GPS ルートをウェイポイント付きで一度定義すると、Terra API がユーザーの接続済みデバイスにプッシュし、デバイス上でナビゲーションに使えるようにします。ユーザーが次回デバイスを同期すると、ルートがウォッチまたはサイクルコンピューターに表示されるため、アプリが各プロバイダー固有のルート形式を扱う必要はありません。

対応しているのは Garmin、COROS、Wahoo のみです。各プロバイダーで機能の対応範囲が大きく異なるため（下記のプロバイダーマトリックスを参照）、すべてのユーザーが Garmin を使っていると分かっている場合を除き、最も対応範囲の狭いプロバイダーを基準にルートを設計してください。

アカウントツール：CLI または MCP

Routes はプレリリースのため、アカウントコマンドはなく、エンドポイントも CLI に同梱されている API の説明には含まれていません。そのため、terra admin-api list --data-api にも表示されません。パスを検証するのは CLI ではなくサーバーであるため、terra data-api からは呼び出せます。

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

ステータス行を表示するには -i を、レスポンスをフィルタリングするには --jq を追加してください。DELETE は --yes を渡さない限り、確認を求めます。

Routes に関連するアカウント設定にはコマンドがあります。terra unified-api sources list --env <dev-id> で、以下のデバイスのうちどれが有効になっているかを確認できます。また、terra users list --env <dev-id> --provider GARMIN で、コースをプッシュする対象としてユーザーが接続済みかどうかを確認できます。

ルートの呼び出しには terra data-api を使います。これは CLI でのみ利用できます。MCP の管理ツールが対象とするのは、有効なプロバイダーと接続済みユーザーのみです。

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 admin MCP サーバーを使用してください。サンドボックスでは CLI をインストールしたり、サインインしたりできません。各管理コマンドは、ツール名と method によって表されます（terra users list は method: "list" を指定した users_read です）。terra data-api、terra admin-api、terra examples を利用できるのは CLI のみで、--select と --jq に相当する MCP の機能はありません。terra-cli と terra-mcp のスキルには、変更の確認やトランスクリプトへの認証情報の混入防止などのガードレール、エラー、およびタスクごとの手順が含まれています。これらは連携を管理するものであり、このスキルで説明する API 呼び出しの代わりにはなりません。

2 段階のワークフロー

Routes は常に 2 段階で実行します。再利用可能なテンプレートを作成し、そのテンプレートを 1 人以上のユーザーにプッシュします。

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 の 2 つのヘッダーが必要です。

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": "..." }

エンドポイント

Method	Endpoint	Description
POST	/routes	ルートテンプレートを作成します
GET	/routes	すべてのテンプレートを一覧表示します
GET	/routes/{id}	1 つのテンプレートを取得します
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	送信済みルートを 1 つ取得します
DELETE	/pushedRoutes/{id}?user_id=X	送信済みルートを削除します

更新の動作。 PUT /routes/{id} はパッチとして動作し、200 を返します。すべてのフィールドは任意で、指定したフィールドのみが更新されます（ウェイポイント、speed_meters_per_second、標高のほか、名前、説明、スポーツ）。すでに送信済みのデバイスには変更を反映しません。?cascade を追加すると、更新したルートを送信先のすべてのデバイスに再送信します。この処理は非同期で実行され、202 Accepted を返します。カスケード処理は結果を待たずに実行されます。再送信の失敗はサーバー側でログに記録されるだけで、レスポンスや GET /pushedRoutes には反映されないため、一部の失敗は API から確認できません。デバイスが実際に更新を受信したことを確認するには、そのユーザーに明示的に再送信するか、デバイス上で別途確認してください。

データモデル

RouteTemplate

フィールド	必須	備考
name	はい	デバイスに表示されるルート名。空でないこと
sport	はい	以下のスポーツ種別のいずれか
waypoints	はい	GPS ポイントの配列。最低 2 個
description	いいえ	Garmin のみ
elevation_gain_meters	いいえ	累積標高（メートル）
elevation_loss_meters	いいえ	累積下降距離（メートル）
speed_meters_per_second	いいえ	平均コース速度の目標値。Garmin のみ

Waypoint

フィールド	必須	備考
latitude	はい	10 進度数。-90～90
longitude	はい	10 進度数。-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
プッシュ	はい	はい	はい
再同期	はい	はい（新しい GPX を再 POST）	はい
削除	はい	いいえ	はい
コースポイント（POI）	はい	いいえ	いいえ
速度目標	はい	いいえ	いいえ
説明	はい	いいえ	いいえ

3 つすべてで再同期がサポートされています。COROS にはインプレース更新がないため、再同期では新しい GPX ファイルを再 POST しますが、provider_route_id は変わりません。削除が可能なのは Garmin と Wahoo のみです。

注意点

• Garmin 専用フィールドは、他のプロバイダーではエラーにならず無視されます。 course_point、speed_meters_per_second、description は Garmin では反映されますが、COROS と Wahoo ではエラーにならず無視されます。すべての対象ユーザーが Garmin を使用している場合を除き、これらに依存しないでください。
• Garmin の標高は、ルートごとに一括で反映されます。 一部のウェイポイントに elevation_meters があり、ほかにはない場合、Terra API はすべての標高値を破棄し、Garmin 独自の標高モデルで補完します。すべてのウェイポイントに標高を指定するか、どれにも指定しないでください。
• コースポイントのエラーは、発生する段階が異なります。 無効な type 文字列は、作成時の列挙値検証により POST /routes で 400 エラーになります。5 種類の方向タイプ（left、right、straight、left_fork、right_fork）は作成時の検証を通過しますが、Garmin のドキュメントに記載された 10 種類のコースポイントタイプには含まれていません。プッシュ時にどう処理されるかは保証されません（エラーになるか、破棄される可能性があります）。現在の動作を確認済みでない限り、Garmin がサポートする 10 種類の POI タイプを使用してください。
• 対応範囲が最も限られているプロバイダーは COROS です。 削除には対応していません（削除しても Terra API のデータベースからレコードが消えるだけで、ルートはデバイスに残ります）。取得にも対応しておらず、すべてのスポーツを 2 種類の内部タイプ（ランとサイクル）にまとめるため、デバイス上の表示では、たとえばグラベルサイクリングとロードバイクが区別されない場合があります。
• 同じテンプレートを繰り返しプッシュすると、プッシュ済みルートが重複して作成されます。 プッシュのたびに新しいルートが作成され、重複排除は行われません。デバイス上の重複を避ける必要がある場合は、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 で確認してください。