strava-api

Strava API

フィットネスデータを管理するための、Strava API v3 との直接連携です。

セキュリティモデル

重要：すべてのシークレットはシステムのキーチェーン（macOS Keychain／Linux Secret Service）に保存されます。

• AI エージェントはキーチェーンからシークレットを読み取れません
• 実行時に認証情報へアクセスできるのは Python スクリプトのみです
• シークレット以外のメタデータ（アスリート名、トークンの有効期限）は ~/.strava/metadata.json に保存されます

この設計により、API 認証情報が AI エージェントに公開されることはありません。

---

初回セットアップのワークフロー

ユーザーが初めて Strava のデータをリクエストした場合：

ステップ 1：設定済みか確認する

python3 scripts/strava_api.py athlete

「Strava not configured」というエラーが表示された場合は、ステップ 2 に進みます。 成功した場合は、「API の使用」セクションに進みます。

ステップ 2：Strava アプリケーションを作成する

API アプリケーションの作成をユーザーに案内します：

1. https://www.strava.com/settings/api を開きます
2. アプリケーションのフォームに入力します：
   • アプリケーション名：任意の名前（例：「My Fitness App」）
   • カテゴリー：任意のものを選択します
   • ウェブサイト：http://localhost
   • 認証コールバックドメイン：localhost
3. Client ID と Client Secret を控えます（セットアップ時に入力します）

ステップ 3：対話形式のセットアップを実行する

python3 scripts/setup_oauth.py

スクリプトは次の処理を行います：

1. Client ID と Client Secret の入力を求めます（シークレットの入力は非表示です）
2. Strava の認証画面をブラウザーで開きます
3. リダイレクト URL のコピーをユーザーに案内します
4. コードをトークンと自動的に交換します
5. シークレットをシステムのキーチェーンに安全に保存します
6. メタデータを ~/.strava/metadata.json に保存します
7. 接続を確認します

ステップ 4：セットアップを確認する

python3 scripts/strava_api.py athlete

アスリートのプロフィール JSON が表示されます。

---

API の使用

CLI コマンド

# Get athlete profile
python3 scripts/strava_api.py athlete

# Get athlete stats
python3 scripts/strava_api.py stats

# List recent activities
python3 scripts/strava_api.py activities --limit 20

# Get specific activity
python3 scripts/strava_api.py activity 12345678

# Explore segments in area
python3 scripts/strava_api.py segments "37.7,-122.5,37.8,-122.4" --type running

# Raw API request
python3 scripts/strava_api.py raw GET /athlete/zones
python3 scripts/strava_api.py raw POST /activities --data '{"name":"Test","sport_type":"Run","start_date_local":"2024-01-15T10:00:00Z","elapsed_time":1800}'

Python インポート

from scripts.strava_api import StravaClient

client = StravaClient()  # Auto-loads from keychain, refreshes token if needed

# Get athlete
athlete = client.get_athlete()

# List activities
activities = client.list_activities(per_page=50)

# Create activity
new_activity = client.create_activity(
    name="Morning Run",
    sport_type="Run",
    start_date_local="2024-01-15T07:30:00Z",
    elapsed_time=1800,
    distance=5000
)

トークン管理

トークンは自動的に更新されます。ステータスを確認するには：

# Check token status
python3 scripts/refresh_token.py --status

# Force refresh
python3 scripts/refresh_token.py --force

---

判断フロー

User Request
├── First time / "setup strava" → Run setup_oauth.py
├── "Get my profile/stats" → strava_api.py athlete/stats
├── "List my activities" → strava_api.py activities
├── "Get activity details" → strava_api.py activity {id}
├── "Create/log activity" → client.create_activity()
├── "Update activity" → client.update_activity()
├── "Get training data/streams" → client.get_activity_streams()
├── "Find segments nearby" → strava_api.py segments {bounds}
├── "Export route" → raw GET /routes/{id}/export_gpx
└── "Token expired" → Auto-handled by client

---

クイックリファレンス

項目	値
シークレットの保存先	システムのキーチェーン（安全）
メタデータの場所	~/.strava/metadata.json
ベース URL	https://www.strava.com/api/v3
レート制限	100 リクエスト／15 分、1000 リクエスト／日
トークンの有効期間	6 時間（自動更新）

参考資料：

• API ドキュメント全体：references/api_reference.md
• 手動セットアップ：references/setup_guide.md

スポーツの種類

• ランニング：Run、TrailRun、VirtualRun
• サイクリング：Ride、MountainBikeRide、GravelRide、EBikeRide
• その他：Swim、Walk、Hike、Workout、WeightTraining、Yoga

エラー処理

ステータス	意味	対応
401	トークンの有効期限切れ	クライアントが自動的に処理します
403	スコープが不足しています	setup_oauth.py を再実行します
404	リソースが見つかりません	ID を確認します
429	レート制限	15 分待ちます