Apiclaw Analysis

APIClaw — Amazon Seller Data Analysis

AI-powered Amazon product research. From market discovery to daily operations.

Language rule: Always respond in the user's language. If the user asks in Chinese, reply in Chinese. If in English, reply in English. The language of this skill document does not affect output language. All API calls go through scripts/apiclaw.py — one script, 5 endpoints, built-in error handling.

Credentials

• Required: APICLAW_API_KEY
• Scope: used only for https://api.apiclaw.io
• Storage: config.json in the skill root directory (next to SKILL.md)

{ "api_key": "hms_live_xxxxxx" }

When user provides a Key, write it to config.json. New keys may need 3-5 seconds to activate — if first call returns 403, wait 3 seconds and retry (max 2 retries).

New users: Get API Key at apiclaw.io/api-keys.

File Map

Don't guess field names — if uncertain, load reference.md first.

Execution Mode

Quick mode trigger: User asks for a single specific data point ("B09XXX monthly sales?", "how many brands in cat litter?") — no decision analysis needed.

Execution Standards

Prioritize script execution for API calls. The script includes:

• Parameter format conversion (e.g. topN auto-converted to string)
• Retry logic (429/timeout auto-retry)
• Standardized error messages
• _query metadata injection (for query traceability)

Fallback: If script fails and can't be quickly fixed, use curl directly. Note "using curl direct call" in output.

Script Usage

All commands output JSON. Progress messages go to stderr.

categories — Category tree lookup

python3 scripts/apiclaw.py categories --keyword "pet supplies"
python3 scripts/apiclaw.py categories --parent "Pet Supplies"

Common fields: categoryName (not name), categoryPath, productCount, hasChildren

market — Market-level aggregate data

python3 scripts/apiclaw.py market --category "Pet Supplies,Dogs" --topn 10

Key output fields: sampleAvgMonthlySales, sampleAvgPrice, topSalesRate (concentration), topBrandSalesRate, sampleNewSkuRate, sampleFbaRate, sampleBrandCount

products — Product selection with filters

# Preset mode (14 built-in)
python3 scripts/apiclaw.py products --keyword "yoga mat" --mode beginner

# Explicit filters
python3 scripts/apiclaw.py products --keyword "yoga mat" --sales-min 300 --reviews-max 50

# Mode + overrides (overrides win)
python3 scripts/apiclaw.py products --keyword "yoga mat" --mode beginner --price-max 30

Available modes: fast-movers, emerging, single-variant, high-demand-low-barrier, long-tail, underserved, new-release, fbm-friendly, low-price, broad-catalog, selective-catalog, speculative, beginner, top-bsr

competitors — Competitor lookup

python3 scripts/apiclaw.py competitors --keyword "wireless earbuds"
python3 scripts/apiclaw.py competitors --asin B09V3KXJPB

Easily confused fields (products/competitors shared):

Complete field list: reference.md → Shared Product Object

product — Single ASIN real-time detail

python3 scripts/apiclaw.py product --asin B09V3KXJPB

Returns: title, brand, rating, ratingBreakdown, features, topReviews, specifications, variants, bestsellersRank, buyboxWinner

report — Full market analysis (composite)

python3 scripts/apiclaw.py report --keyword "pet supplies"

Runs: categories → market → products (top 50) → realtime detail (top 1).

opportunity — Product opportunity discovery (composite)

python3 scripts/apiclaw.py opportunity --keyword "pet supplies" --mode fast-movers

Runs: categories → market → products (filtered) → realtime detail (top 3).

Data Structure Reminder

All interfaces return .data as an array. Use .data[0] to get the first record, NOT .data.fieldName.

Intent Routing

Product Selection Mode Mapping (14 types):

Quick Evaluation Criteria

Market Viability (from market output)

Product Potential (from product output)

Sales Estimation Fallback

When atLeastMonthlySales is null: Monthly sales ≈ 300,000 / BSR^0.65

Output Standards (Full Mode Only)

MUST include data source block after every Full-mode analysis:

---
**Data Source & Conditions**
| Item | Value |
|----|-----|
| Data Source | APIClaw API |
| Interface | [interfaces used] |
| Category | [category path] |
| Time Range | [dateRange] |
| Sampling | [sampleType] |
| Top N | [topN value] |
| Sort | [sortBy + sortOrder] |
| Filters | [specific parameter values] |

**Data Notes**
- Monthly sales are **lower bound estimates** (Amazon displays "10,000+ bought"), actual may be higher
- Database data has ~T+1 delay; realtime/product is current real-time data
- Concentration metrics based on Top N sample; different topN → different results

✅ Completed Example (yoga mat market analysis):

---
**Data Source & Conditions**
| Item | Value |
|----|-----|
| Data Source | APIClaw API |
| Interface | categories, markets/search, products/search |
| Category | Sports & Outdoors > Exercise & Fitness > Yoga > Yoga Mats |
| Time Range | 30d |
| Sampling | by_sale_100 |
| Top N | 10 |
| Sort | atLeastMonthlySales desc |
| Filters | monthlySalesMin: 300, reviewCountMax: 50 |

**Data Notes**
- Monthly sales are **lower bound estimates** (Amazon displays "10,000+ bought"), actual may be higher
- Database data has ~T+1 delay; realtime/product is current real-time data

Rules:

1. Every Full-mode analysis MUST end with this block
2. Filter conditions MUST list specific parameter values
3. If multiple interfaces used, list each one
4. If data has limitations, proactively explain

Limitations

What This Skill Cannot Do

• Keyword research / reverse ASIN / ABA data
• Traffic source analysis
• Historical sales trends (14-month curves)
• Historical price / BSR charts
• AI review sentiment analysis (use topReviews + ratingBreakdown manually)

API Coverage Boundaries

Error Handling

HTTP errors (401/402/403/404/429) are handled by the script, returning structured JSON with error.message and error.action.

Self-check: python3 scripts/apiclaw.py check — tests 4/5 endpoints, reports availability.