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
• Resolution order:
  1. Environment variable APICLAW_API_KEY (preferred, most secure)
  2. Config file config.json in the skill root directory (fallback)

{ "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).

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.

⚠️ Pre-Execution Checklist (MANDATORY for Full Mode)

Before running any Full-mode product selection or market analysis, complete this checklist:

• Step 1 — Mode Selection: Check the Product Selection Mode Mapping table below. If ANY of the 14 preset modes matches the user's intent, USE IT (--mode xxx). Do NOT manually piece together filters when a preset mode exists. Common mappings:
  • Small/lightweight/cheap products → --mode low-price
  • New seller / beginner → --mode beginner
  • Niche / long-tail → --mode long-tail
  • Trending / rising → --mode emerging
• Step 2 — Realtime Supplement: Plan to call product --asin for the top 3-5 ASINs from results (see Realtime Data Supplementation below).
• Step 3 — Review Analysis: Plan to call analyze --asins for top ASINs to get consumer insights (especially painPoints, improvements, buyingFactors).
• Step 4 — Output Blocks: Prepare to include both 📋 Data Source & Conditions and 📊 API Usage at the end.

Why this exists: In testing, AI agents repeatedly skipped preset modes, realtime supplements, and review analysis — even though the instructions below clearly describe them. This checklist forces a pause-and-verify before execution.

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.

Realtime Data Supplementation

When products or competitors returns ASINs in Full-mode analysis, automatically call product --asin for the top 3-5 most relevant ASINs to get current real-time data.

Handling data conflicts — products/competitors has ~T+1 delay; realtime/product is live:

When realtime data differs significantly, note it: e.g. "⚡ Price updated: database $29.99 → realtime $24.99 (likely promotion)"

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

Keyword matching: Default is fuzzy (matches brand names too — e.g. "smart ring" matches "Smart Color Art" pens). Use --keyword-match-type exact or phrase for precise results. Always combine with --category when possible to reduce noise.

Category path with commas: Some category names contain commas (e.g. "Pacifiers, Teethers & Teething Relief"). Use > separator instead of , to avoid parsing errors:

# ❌ Wrong — comma in name breaks parsing
--category "Baby Products,Baby Care,Pacifiers, Teethers & Teething Relief"
# ✅ Correct — use ' > ' separator
--category "Baby Products > Baby Care > Pacifiers, Teethers & Teething Relief"

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

analyze — Review analysis (sentiment + consumer insights)

# Single ASIN
python3 scripts/apiclaw.py analyze --asin B09V3KXJPB

# Multiple ASINs (competitive review comparison)
python3 scripts/apiclaw.py analyze --asins B09V3KXJPB,B08YYYYY,B07ZZZZZ

# Category-level insights
python3 scripts/apiclaw.py analyze --category "Pet Supplies,Dogs,Toys" --period 90d

# Specific insight dimension
python3 scripts/apiclaw.py analyze --asin B09V3KXJPB --label-type painPoints,buyingFactors

Returns: totalReviews, avgRating, sentimentDistribution, ratingDistribution, consumerInsights (by labelType), topKeywords, verifiedRatio

Available labelType: scenarios, issues, positives, improvements, buyingFactors, painPoints, keywords, userProfiles, usageTimes, usageLocations, behaviors

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

⚠️ Interface Data Differences

The 4 types of interfaces return different fields. Do NOT assume they share the same structure.

Usage rule:

• Use products / competitors for sales, pricing, and competition data
• Use realtime/product for review details, listing content, and seller info
• Use market for category-level aggregate metrics
• Use reviews/analyze for AI-powered review insights (sentiment, pain points, buying factors — covers all reviews, not just topReviews)
• For reports: combine products/competitors (quantitative) + realtime/product (qualitative) + reviews/analyze (consumer insights) as evidence

Data Structure Reminder

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