Keepa API 客户端

基于 Keepa API 的亚马逊产品价格历史追踪工具。

依赖

curl (HTTP 请求)
jq (JSON 解析)

安装依赖:

# macOS
brew install curl jq

# Ubuntu/Debian
apt-get install curl jq

Usage

# ASIN 查询 - 获取产品详情和价格历史
/keepa-api asin B08XYZ123

# 批量 ASIN 查询
/keepa-api batch-asin B08XYZ123,B09ABC456,B07DEF789

# 查询价格历史
/keepa-api price-history B08XYZ123 --days 90

# 关键词搜索产品
/keepa-api search "wireless earbuds" --category Electronics

# 查询 Best Sellers
/keepa-api bestsellers --category Electronics --page 1

# 指定亚马逊站点
/keepa-api asin B08XYZ123 --domain JP

# 直接输入 ASIN
/keepa-api
[paste ASIN or product URL]

Options

| Option | Description | |--------|-------------| | --domain <US\|UK\|DE\|...> | 亚马逊站点 (默认：US) | | --days <number> | 历史数据天数：30, 90, 180 (默认：90) | | --category <name> | 商品类目 (Electronics, Home, Beauty 等) | | --output <table\|json> | 输出格式 (默认：table) | | --page <number> | 分页页码 (用于搜索和 Best Sellers) |

Core Tools

1. Product Query (产品查询)

查询单个 ASIN 的详细信息，包括价格历史、销售排名、评论等。

/keepa-api asin <ASIN> [--marketplace US] [--days 90]

返回数据:

产品基础信息 (标题、品牌、类目、图片)
当前价格 (Amazon 价格、第三方价格)
价格历史记录
销售排名 (BSR)
评论数量和评分
库存状态

2. Price History (价格历史)

获取产品历史价格数据，支持自定义时间范围。

/keepa-api price-history <ASIN> [--days 30|90|180|365]

返回数据:

每日价格点
价格变化时间线
历史最低价/最高价
平均价格

3. Sales Rank History (销售排名历史)

追踪产品销售排名变化趋势，与 asin 命令一起返回。

/keepa-api asin <ASIN> --days 90

返回数据:

每日 BSR 排名
排名变化趋势
类目前 100 记录

4. Product Search (产品搜索)

通过关键词搜索亚马逊产品。

/keepa-api search "<keyword>" [--category <category>] [--page <n>]

返回数据:

匹配产品列表
ASIN、标题、价格
评分和评论数
图片链接

5. Best Sellers (热销榜)

获取类目热销榜产品。

/keepa-api bestsellers --category <category> [--page <n>]

返回数据:

热销产品排名
产品 ASIN 和信息
当前价格

Three Dimensions

| Dimension | Controls | Options | |-----------|----------|---------| | Data Type | 数据类型 | product, price, rank, offers, search | | Marketplace | 亚马逊站点 | US, EU, UK, JP, CA, AU, IN | | Output Format | 数据输出格式 | table, json |

Marketplace Reference

| Marketplace | Code | Domain | |-------------|------|--------| | 美国 | US | amazon.com | | 英国 | UK | amazon.co.uk | | 德国 | DE | amazon.de | | 法国 | FR | amazon.fr | | 日本 | JP | amazon.co.jp | | 加拿大 | CA | amazon.ca | | 澳大利亚 | AU | amazon.com.au | | 印度 | IN | amazon.in |

Workflow

Progress Checklist

Keepa API Query Progress:
- [ ] Step 0: Check API configuration ⛔ BLOCKING
- [ ] Step 1: Understand data requirement
- [ ] Step 2: Confirm query parameters ⚠️ REQUIRED
- [ ] Step 3: Execute API request
- [ ] Step 4: Parse and display results

Flow

Input → [Step 0: Config Check] ─┬─ Configured → Continue
                                │
                                └─ Not configured → Setup required ⛔ BLOCKING
                                                   │
                                                   └─ Complete setup → Save config → Continue

Step 0: Configuration Check ⛔ BLOCKING

Purpose: Check Keepa API configuration.

Configuration paths:

Project-level: .teamclaw-skills/keepa-api/CONFIG.md
User-level: ~/.teamclaw-skills/keepa-api/CONFIG.md

Check command:

# Check project-level first
test -f .teamclaw-skills/keepa-api/CONFIG.md && echo "project"

# Then user-level
test -f "$HOME/.teamclaw-skills/keepa-api/CONFIG.md" && echo "user"

First-Time Setup (if config not found):

Use AskUserQuestion with questions:

Keepa API Key (required):
- Input your Keepa API key
- Get key from: https://keepa.com/#!api
Default marketplace:
- US (amazon.com)
- UK (amazon.co.uk)
- DE (amazon.de)
- JP (amazon.co.jp)
- Other
Default history days:
- 30 days
- 90 days (default)
- 180 days
- 365 days
Output format:
- Table (default, readable)
- JSON (for integration)

Configuration file format (CONFIG.md):

---
api_key: your-keepa-api-key-here
marketplace: US
default_days: 90
output_format: table
---

Step 1: Understand Data Requirement

Analyze user request:

Data type needed (product/price/rank/offers/search)
Target ASIN(s) or keyword(s)
Marketplace
Time period

Step 2: Confirm Query Parameters ⚠️

Display confirmation:

Query type
Target (ASIN/keyword)
Marketplace
Days range
Output format

Step 3: Execute API Request

Execute curl request:

curl -s "https://api.keepa.com/product?key=$API_KEY&domain=$DOMAIN&asin=$ASIN"

Step 4: Parse and Display Results

Output format:

═══ Keepa Product Report ═══

ASIN: B08XYZ123
Title: [Product Title]
Brand: [Brand Name]
Category: [Category]

Current Price:
- Amazon: $29.99
- 3rd Party New: $27.99
- 3rd Party Used: $22.99

Sales Rank: #1,234 in Electronics
Rating: 4.5/5 (2,847 reviews)

Price History (90 days):
- Lowest: $24.99 (2024-01-15)
- Highest: $34.99 (2024-02-01)
- Average: $29.50

API Endpoints

Product Endpoint

GET /product
Parameters:
- key: API key
- domain: Amazon domain (1=US, 3=UK, 4=DE, 5=FR, 6=JP, 7=CA, 9=AU, 10=IN)
- asin: ASIN or comma-separated list
- history: Include price history (1/0)
- rating: Include rating (1/0)

Search Endpoint

GET /search
Parameters:
- key: API key
- domain: Amazon domain
- query: Search query
- category: Category ID (optional)
- page: Page number (optional)

Best Sellers Endpoint

GET /bestsellers
Parameters:
- key: API key
- domain: Amazon domain
- categoryId: Category ID
- page: Page number (optional)

Category IDs

| Category | ID | |----------|-----| | Electronics | 172282 | | Computers | 541966 | | Home & Kitchen | 1055398 | | Beauty & Personal Care | 3760911 | | Sports & Outdoors | 3375251 | | Toys & Games | 165793011 | | Clothing | 7141123011 | | Books | 283155 | | Office Products | 1064954 | | Garden & Outdoor | 2972638011 |

File Structure

skills/keepa-api/
├── SKILL.md                 # Skill 定义
├── scripts/
│   └── keepa.sh             # 主脚本 (纯 curl 实现)
├── references/
│   └── api-docs.md          # API 文档参考
└── CONFIG.template.md       # 配置文件模板

Configuration

Get API Key

Visit Keepa API
Register or login
Go to Account → API Key
Copy your API key

Rate Limits

| Plan | Tokens/Day | Cost per Request | |------|------------|------------------| | Free | 100 | 1-2 tokens | | Basic (9€/mo) | 100,000 | 1-2 tokens | | Pro (19€/mo) | 500,000 | 1-2 tokens | | Ultra (49€/mo) | 2,000,000 | 1-2 tokens |

Token Costs

| Request Type | Token Cost | |--------------|------------| | Product (single ASIN) | 1-2 tokens | | Product (batch 10 ASINs) | 10-20 tokens | | Search | 1 token | | Best Sellers | 1 token | | Offers | 1-3 tokens |

Output Examples

Product Query Result

═══ Keepa Product Report ═══

ASIN: B08XYZ123
Title: Wireless Bluetooth Earbuds
Brand: SoundTech
Category: Electronics > Headphones

Current Price:
- Amazon: $29.99
- 3rd Party New: $27.99
- 3rd Party Used: $22.99
- Lowest in 30 days: $24.99

Sales Rank: #1,234 in Electronics (#45 in Earbud Headphones)
Rating: 4.5/5 (2,847 reviews)

Price History (90 days):
┌──────────────┬────────────┐
│ Date         │ Price      │
├──────────────┼────────────┤
│ 2024-01-15   │ $24.99 (Low)│
│ 2024-02-01   │ $34.99 (High)│
│ Current      │ $29.99     │
└──────────────┴────────────┘

Recommendation: Price is near average. Wait for deal if not urgent.

Search Result

═══ Search Results: "wireless earbuds" ═══

Page 1 of 5 (48 results)

#1  B08XYZ123  Wireless Earbuds Pro    $29.99  ★★★★☆ (2,847)
#2  B09ABC456  Bluetooth Earbuds Sport $24.99  ★★★★☆ (1,523)
#3  B07DEF789  True Wireless Earbuds   $39.99  ★★★★★ (987)
...

Best Practices

数据准确性

价格数据每 15 分钟更新
销售排名每小时更新
历史数据最多保留 2 年

API 优化

批量查询 ASIN 节省 tokens
仅请求需要的字段
缓存常用查询结果

价格追踪

设置价格提醒
关注历史低价
比较多个卖家

Troubleshooting

| Issue | Solution | |-------|----------| | Invalid API Key | Verify key in Keepa dashboard | | Token limit exceeded | Wait for daily reset or upgrade plan | | Product not found | Check ASIN and marketplace | | Rate limit | Slow down requests |

References

Notes

需要有效的 Keepa API key
免费账户每日 100 tokens
数据更新频率：15 分钟
支持 8 个亚马逊站点

Keepa Api

Keepa API 客户端

依赖

Usage

Options

Core Tools

1. Product Query (产品查询)

2. Price History (价格历史)

3. Sales Rank History (销售排名历史)

4. Product Search (产品搜索)

5. Best Sellers (热销榜)

Three Dimensions

Marketplace Reference

Workflow

Progress Checklist

Flow

Step 0: Configuration Check ⛔ BLOCKING

Step 1: Understand Data Requirement

Step 2: Confirm Query Parameters ⚠️

Step 3: Execute API Request

Step 4: Parse and Display Results

API Endpoints

Product Endpoint

Search Endpoint

Best Sellers Endpoint

Category IDs

File Structure

Configuration

Get API Key

Rate Limits

Token Costs

Output Examples

Product Query Result

Search Result

Best Practices

数据准确性

API 优化

价格追踪

Troubleshooting

References

Notes