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

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

Marketplace Reference

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:

1. Project-level: .teamclaw-skills/keepa-api/CONFIG.md
2. 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:

1. Keepa API Key (required):
• Input your Keepa API key
• Get key from: https://keepa.com/#!api

1. Default marketplace:
• US (amazon.com)
• UK (amazon.co.uk)
• DE (amazon.de)
• JP (amazon.co.jp)
• Other

1. Default history days:
• 30 days
• 90 days (default)
• 180 days
• 365 days

1. 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

File Structure

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

Configuration

Get API Key

1. Visit Keepa API
2. Register or login
3. Go to Account → API Key
4. Copy your API key

Rate Limits

Token Costs

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

References

• Keepa API Documentation
• Category Tree
• API Examples

Notes

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