strava-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Strava API

Direct integration with Strava API v3 for fitness data management.

与Strava API v3直接集成，用于健身数据管理。

Security Model

安全模型

IMPORTANT: All secrets are stored in system keychain (macOS Keychain / Linux Secret Service).

AI agents CANNOT read secrets from keychain
Only the Python scripts can access credentials at runtime
Non-secret metadata (athlete name, token expiry) stored in
```
~/.strava/metadata.json
```

This design ensures your API credentials are never exposed to AI agents.

重要提示：所有密钥均存储在系统密钥链中（macOS Keychain / Linux Secret Service）。

AI Agent无法从密钥链中读取密钥
仅Python脚本可在运行时访问凭证
非密钥元数据（运动员姓名、令牌过期时间）存储在
```
~/.strava/metadata.json
```
中

这种设计可确保你的API凭证绝不会暴露给AI Agent。

First-Time Setup Workflow

首次设置流程

When user requests Strava data for the first time:

当用户首次请求Strava数据时：

Step 1: Check if configured

步骤1：检查是否已配置

bash

python3 scripts/strava_api.py athlete

If error "Strava not configured" → proceed to Step 2. If success → skip to "Using the API" section.

bash

python3 scripts/strava_api.py athlete

若出现错误“Strava not configured”（未配置Strava）→ 进入步骤2。若成功→ 跳至“使用API”部分。

Step 2: Create Strava Application

步骤2：创建Strava应用

Guide user to create API application:

Open https://www.strava.com/settings/api
Fill application form:
- Application Name: Any name (e.g., "My Fitness App")
- Category: Choose any
- Website:
```
http://localhost
```
- Authorization Callback Domain:
```
localhost
```
Note Client ID and Client Secret (will be entered in setup)

引导用户创建API应用：

打开https://www.strava.com/settings/api
填写应用表单：
- 应用名称：任意名称（例如：“我的健身应用”）
- 分类：任意选择
- 网站：
```
http://localhost
```
- 授权回调域名：
```
localhost
```
记录Client ID和Client Secret（将在设置时输入）

Step 3: Run Interactive Setup

步骤3：运行交互式设置

bash

python3 scripts/setup_oauth.py

Script will:

Ask for Client ID and Client Secret (secret input hidden)
Open browser for Strava authorization
Guide user to copy redirect URL
Exchange code for tokens automatically
Store secrets in system keychain (secure)
Store metadata in
```
~/.strava/metadata.json
```
Verify connection

bash

python3 scripts/setup_oauth.py

脚本将：

要求输入Client ID和Client Secret（密钥输入会隐藏）
打开浏览器进行Strava授权
引导用户复制重定向URL
自动交换代码以获取令牌
将密钥安全存储在系统密钥链中
将元数据存储在
```
~/.strava/metadata.json
```
中
验证连接

Step 4: Verify Setup

步骤4：验证设置

bash

python3 scripts/strava_api.py athlete

Should display athlete profile JSON.

bash

python3 scripts/strava_api.py athlete

应显示运动员档案JSON数据。

Using the API

使用API

CLI Commands

CLI命令

bash

undefined

bash

undefined

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

原始API请求

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}'

undefined

undefined

Python Import

Python导入

python

from scripts.strava_api import StravaClient

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

python

from scripts.strava_api import StravaClient

client = StravaClient()  # 自动从密钥链加载，必要时刷新令牌

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 )

undefined

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

undefined

Token Management

令牌管理

Tokens refresh automatically. Check status:

bash

undefined

令牌会自动刷新。检查状态：

bash

undefined

Check token status

检查令牌状态

python3 scripts/refresh_token.py --status

Force refresh

强制刷新

python3 scripts/refresh_token.py --force

---

python3 scripts/refresh_token.py --force

---

Decision Tree

决策树

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

用户请求
├── 首次使用 / "setup strava"（配置Strava）→ 运行setup_oauth.py
├── "获取我的档案/统计数据" → strava_api.py athlete/stats
├── "列出我的活动" → strava_api.py activities
├── "获取活动详情" → strava_api.py activity {id}
├── "创建/记录活动" → client.create_activity()
├── "更新活动" → client.update_activity()
├── "获取训练数据/数据流" → client.get_activity_streams()
├── "查找附近路段" → strava_api.py segments {bounds}
├── "导出路线" → 原始GET请求 /routes/{id}/export_gpx
└── "令牌过期" → 由客户端自动处理

Quick Reference

快速参考

Item	Value
Secrets storage	System Keychain (secure)
Metadata location	`~/.strava/metadata.json`
Base URL	`https://www.strava.com/api/v3`
Rate limits	100 req/15min, 1000 req/day
Token lifetime	6 hours (auto-refresh)

References:

Full API docs: references/api_reference.md
Manual setup: references/setup_guide.md

项目	值
密钥存储	系统密钥链（安全）
元数据位置	`~/.strava/metadata.json`
基础URL	`https://www.strava.com/api/v3`
速率限制	15分钟100次请求，每日1000次请求
令牌有效期	6小时（自动刷新）

参考资料：

完整API文档：references/api_reference.md
手动设置指南：references/setup_guide.md

Sport Types

运动类型

Running:
```
Run
```
,
```
TrailRun
```
,
```
VirtualRun
```
Cycling:
```
Ride
```
,
```
MountainBikeRide
```
,
```
GravelRide
```
,
```
EBikeRide
```
Other:
```
Swim
```
,
```
Walk
```
,
```
Hike
```
,
```
Workout
```
,
```
WeightTraining
```
,
```
Yoga
```

跑步：
```
Run
```
,
```
TrailRun
```
,
```
VirtualRun
```
骑行：
```
Ride
```
,
```
MountainBikeRide
```
,
```
GravelRide
```
,
```
EBikeRide
```
其他：
```
Swim
```
,
```
Walk
```
,
```
Hike
```
,
```
Workout
```
,
```
WeightTraining
```
,
```
Yoga
```

Error Handling

错误处理

Status	Meaning	Action
401	Token expired	Auto-handled by client
403	Insufficient scope	Re-run setup_oauth.py
404	Resource not found	Check ID
429	Rate limit	Wait 15 min

状态码	含义	操作
401	令牌过期	由客户端自动处理
403	权限不足	重新运行setup_oauth.py
404	资源不存在	检查ID是否正确
429	超出速率限制	等待15分钟