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 directory (same folder as SKILL.md)

API Key Configuration Mechanism

Config file location: config.json in the skill root directory, next to SKILL.md.

apiclaw-analysis-skill/
├── config.json          ← API Key stored here
├── SKILL.md
├── scripts/
│   └── apiclaw.py
└── references/

Config file format:

{
  "api_key": "hms_live_xxxxxx"
}

Initial Setup (AI Operation Guide)

When user first uses or provides new Key, AI should execute:

import os, json
# config.json is stored in the skill root directory (parent of scripts/)
skill_dir = os.path.dirname(os.path.abspath(__file__))  # when running from scripts/
skill_dir = os.path.dirname(skill_dir)  # go up to skill root
config_path = os.path.join(skill_dir, "config.json")
with open(config_path, "w") as f:
    json.dump({"api_key": "hms_live_user_provided_key"}, f, indent=2)
print(f"API Key saved to {config_path}")

Get API Key

New users please first obtain API Key:

1. Visit APIClaw Console to register account
2. Create API Key, copy it (format: hms_live_xxxxxx)
3. Tell the AI your Key in conversation, AI will automatically save it to config file

New Key first use note: Newly configured API Key may need 3-5 seconds to fully activate in backend. If first call returns 403 error, AI should wait 3 seconds then retry, max 2 retries.

File map

Reference File Usage Guide (Important)

Must load reference files in these scenarios:

Don't guess field names: If uncertain about an interface's return fields, load reference.md first to check.

Execution Standards

Prioritize script execution for API calls. The script includes built-in:

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

macOS note: macOS doesn't have python command by default, use python3. Replace python in example commands with python3.

Fallback plan: If script execution fails and can't be quickly fixed, can use curl to call API directly as temporary solution, but note "this time using curl direct call" in output.

Script usage

All commands output JSON. Progress messages go to stderr.

categories — Category tree lookup

python scripts/apiclaw.py categories --keyword "pet supplies"
python scripts/apiclaw.py categories --parent "Pet Supplies"
python scripts/apiclaw.py categories                          # root categories

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

market — Market-level aggregate data

python scripts/apiclaw.py market --category "Pet Supplies,Dogs" --topn 10
python scripts/apiclaw.py market --keyword "treadmill"

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

products — Product selection with filters

# Use a preset mode (14 built-in modes)
python scripts/apiclaw.py products --keyword "yoga mat" --mode beginner
python scripts/apiclaw.py products --keyword "pet toys" --mode high-demand-low-barrier

# Or use explicit filters
python scripts/apiclaw.py products --keyword "yoga mat" --sales-min 300 --reviews-max 50
python scripts/apiclaw.py products --keyword "yoga mat" --growth-min 0.1 --listing-age 180

# Combine mode + overrides (overrides win)
python 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

python scripts/apiclaw.py competitors --keyword "wireless earbuds"
python scripts/apiclaw.py competitors --brand "Anker"
python scripts/apiclaw.py competitors --asin B09V3KXJPB

products/competitors shared fields (easily confused):

Common fields: salesMonthly, bsrRank, ratingCount, rating, salesGrowthRate, listingDate, price, brand, categories

Complete field list see reference.md → Shared Product Object

product — Single ASIN real-time detail

python scripts/apiclaw.py product --asin B09V3KXJPB
python scripts/apiclaw.py product --asin B09V3KXJPB --marketplace JP

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

report — Full market analysis (composite)

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

Runs automatically: categories → market → products (top 50) → realtime detail (top 1). Returns combined JSON.

opportunity — Product opportunity discovery (composite)

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

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

Return Data Structure

Important: The .data field returned by all interfaces is an array, not an object. When parsing, use .data[0] to get the first record.

# Correct ✅
jq '.data[0].topSalesRate'

# Error ❌ - will report "Cannot index array with string"
jq '.data.topSalesRate'

Batch processing example:

# Iterate through all records
jq '.data[] | {name: .categoryName, sales: .sampleAvgMonthlySales}'

# Take first 5
jq '.data[:5] | .[] | .title'

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 salesMonthly is null: Monthly sales ≈ 300,000 / BSR^0.65

Output Standards (Mandatory)

Must include data source block after every analysis completion, otherwise output is considered incomplete:

---
**Data Source & Conditions**
| Item | Value |
|----|-----|
| Data Source | APIClaw API |
| Interface | [List interfaces used this time, e.g. categories, markets/search, products/search] |
| Category | [Queried category path] |
| Time Range | [dateRange, e.g. 30d] |
| Sampling Method | [sampleType, e.g. by_sale_100] |
| Top N | [topN value, e.g. 10] |
| Sort | [sortBy + sortOrder, e.g. monthlySales desc] |
| Filter Conditions | [Specific parameter values, e.g. monthlySalesMin: 300, reviewCountMax: 50] |

**Data Notes**
- Monthly sales are **estimated values** based on BSR + sampling model, not official Amazon data
- Database interface data has ~T+1 delay, realtime/product is current real-time data
- Concentration metrics calculated based on Top N sample, different topN values will yield different results

Rules:

1. Must include this block after every analysis
2. Filter conditions should be specific to parameter values (e.g. monthlySalesMin: 300, reviewCountMax: 50)
3. If multiple interfaces used, list each one
4. If data has limitations (e.g. missing historical trends), 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 Data Coverage Boundaries

Error Handling & Self-Check

HTTP errors (401/402/403/404/429) are handled by the script automatically, returning structured JSON with error.message and error.action that AI can read and act on.

When encountering issues, run self-check:

python scripts/apiclaw.py check

Tests 4 of 5 endpoints (skips realtime/product which requires a valid ASIN), reports availability.

Other common issues: