Amazon Review Intelligence Extractor — 11 Dimensions, 1B+ Reviews#

Pre-analyzed consumer insights. Pain points, buying factors, user profiles, differentiation gaps.

Files#

• Script: {skill_base_dir}/scripts/zoodata.py — run --help for params
• Reference: {skill_base_dir}/references/reference.md (field names & response structure)

Credential#

Required: ZOODATA_API_KEY. Get free key at zoodata.ai/api-keys

Capabilities & Data Flow#

• Network: only https://api.zoodata.ai (Bearer ZOODATA_API_KEY). Setting ZOODATA_BASE_URL to an untrusted host (anything other than api.zoodata.ai / *.zoodata.ai / localhost) makes the CLI refuse the request and withhold the key — the Bearer token is never sent to an untrusted host.
• Execution: bundled shared ZooData CLI {skill_base_dir}/scripts/zoodata.py (Python 3, stdlib-only). This skill allows analyze, review-deepdive, product, categories, check, plus the review fallback toolkit ( reviews-raw / review-tag-prompt / review-reduce-prompt / review-aggregate). Do not invoke unrelated subcommands for this skill's tasks — the bundled manifest {skill_base_dir}/scripts/allowed-commands.json enforces this: the CLI refuses out-of-scope subcommands with a structured COMMAND_NOT_ALLOWED error before any API request.
• Local files: a private temporary working dir (created with mktemp -d, removed when the fallback completes) during the review fallback; reads the optional credential store ~/.zoodata/config.json.
• Sent to the API: keywords, category paths, ASINs, marketplace/date and numeric filter values only. Never sent: budget, experience level, risk tolerance, or any other user-profile text — profile inputs map client-side to numeric filters.
• Credits: every API call consumes account credits. For broad or ambiguous requests, state the estimated credit cost and confirm with the user before running multi-call scans. The composite review-deepdive command executes ~14+ API calls (~10-20 credits) in ONE invocation and has NO skip/trim flags — under a credit cap, use the granular commands instead.

Shared CLI Contract#

Before selecting or invoking the first command, read and apply the local references/cli-contract.md. Reapply it after every granular or composite result and before any fallback, additional call, state write, interpretation, or user-facing report. Use this skill's fallback logic only when the shared contract classifies the result as non-terminal.

Local Interface Failure Output#

For a terminal interface failure, respond in the user's language that the review analysis could not be completed, followed by the succeeded and failed endpoint identifiers. Do not generate pain-point rankings, sentiment conclusions, listing copy, or differentiation recommendations. Keep control tokens, parameters, and retry logs internal unless diagnostics are requested.

Input (one of)#

• Single ASIN: "Analyze reviews for B09V3KXJPB"
• Multi-ASIN: "Compare review pain points across these 5 competitor ASINs"
• Category-wide: keyword/category name → resolve via categories first (need ≥3-level deep path)

API Pitfalls (CRITICAL)#

• reviews/analysis needs 50+ reviews. Fallback chain when sample is insufficient:

  1. Lightweight: realtime/product ratingBreakdown — only star distribution, no themes
  2. Full 11-dim insights: see "Insufficient Data Fallback" section below — use the local toolkit ( reviews-raw + review-tag-prompt + review-reduce-prompt + review-aggregate) to bypass /reviews/analysis entirely

• labelType is NOT an API request parameter — the API returns all 11 dimensions in one call. Filter by labelType client-side from the consumerInsights array.

• Category mode needs precise path (≥3 levels) — broad categories = diluted insights

• Field name is reviewRate (NOT the legacy reviewPercentage from API v1) for mention frequency

• ASIN-specific endpoints don't need --category; keyword-based ones do

• Category auto-detection: categoryPath is auto-detected from target ASIN. If category_source in output is inferred_from_search, confirm with user

On Missing Key#

When ZOODATA_API_KEY is not set (verify via python {skill_base_dir}/scripts/zoodata.py check — exits 2 if no key in env or ~/.zoodata/config.json), stop before any evidence call. Tell the user that a ZooData API key is required, link to https://zoodata.ai/en/api-keys, and explain that the key may be set in the environment or local config. Do not substitute public knowledge or a "for reference only" analysis.

On 401 Invalid Key#

When _transport.status=401, stop further calls, tell the user that the configured key was rejected, direct them to https://zoodata.ai/en/api-keys, and do not fabricate missing data.

On 402 Credit Exhausted#

When _transport.status=402, stop further calls. Report where the workflow stopped, any compatible partial findings already gathered, and returned credit metadata when present; direct the user to https://zoodata.ai/en/pricing and do not fabricate missing data.

11 Analysis Dimensions#

painPoints · issues · positives · improvements · buyingFactors · keywords · userProfiles · scenarios · usageTimes · usageLocations · behaviors

Unique Logic#

Analysis Modes#

• Category mode: all reviews in category → market-level insights
• ASIN mode: specific products → competitive analysis
• Choose based on user intent. Category = broader, ASIN = deeper.

Pain Point Impact Ranking#

Rank differentiation opportunities by: frequency × avg rating delta "Top pain point: durability — mentioned in 27/471 reviews (5.7%), avg rating 2.4 when mentioned"

reviewRateFrequency LevelInterpretation>10%🔴 CriticalMentioned by 1 in 10 buyers — must address in product design 📊5-10%🟡 SignificantCommon complaint — differentiator if solved 📊2-5%🟠 NotableWorth mentioning in listing if you solve it 📊<2%🟢 MinorEdge case — deprioritize unless easy fix 🔍avgRating when mentionedSeverity<2.5Severe — causes returns/1-star reviews 📊2.5-3.5Moderate — disappoints but doesn't cause returns 🔍>3.5Mild — noticed but not deal-breaker 🔍

Differentiation Priority = High frequency + Low avgRating = Biggest opportunity 🔍. If top 3 pain points all have reviewRate >5% and avgRating <3.0, there is a clear product improvement opportunity 💡. If all pain points have reviewRate <2%, the category is well-served — differentiation through reviews is limited 🔍.

⚠️ Small-sample caveat (N < 50): The reviewRate thresholds above assume ≥50 reviews. With smaller samples (e.g. fallback toolkit with 14 reviews), every single mention = 1/N which already crosses 5-10%. Rules to apply when reviewCount < 50:

• Demote single-mention pain points / positives from 📊 to 🔍 (directional, not data-backed)

• In the report, surface a "Sample-size advisory" banner above all percentage-based tables

• Prefer reporting count alongside reviewRate so readers can judge weight themselves

• Do NOT trigger "🔴 Critical / clear improvement opportunity" 💡 verdicts on counts of 1

• Never attach a table-level or section-header 📊 label when ANY row inside is single-mention (🔍-demoted). A header 📊 implies the entire table is data-backed, which contradicts the per-row demotion rule and smuggles 🔍 data back into the 📊 tier via visual grouping. Either:

  • (a) Omit the header-level confidence label entirely and let individual rows carry their own labels, OR
  • (b) If the header must carry a label, use the LOWEST confidence present in any row (🔍 if any row is 🔍; 📊 only if EVERY row qualifies as 📊 on its own — i.e. all counts ≥ 2 when N<50)

Consumer Profile Synthesis#

Combine userProfiles + scenarios + usageTimes + usageLocations → complete buyer persona.

Listing Copy from Reviews#

Quote actual customer words from positives — these are proven converting phrases. High-frequency positive elements (reviewRate >5%) should appear in title or first bullet 💡.

Competitor Comparison#

Align dimensions (pain points vs pain points) across products. If competitor review data unavailable, use brand-detail sampleProducts + note limitation.

• Your pain point rate < competitor's: Advantage — highlight in listing 💡
• Your pain point rate > competitor's: Risk — address in product iteration 💡
• Both high on same pain point: Category-wide issue — solving it is a strong differentiator 🔍

Composite Command#

bash

python3 {skill_base_dir}/scripts/zoodata.py review-deepdive --target-asin "<ASIN>" [--keyword "<kw>"] [--category "<path>"]

Optional: --comp-asins "<asin1>,<asin2>" for comparison. Runs: reviews × 11 dimensions + competitors + realtime + market context + price/trend. ( <placeholders> are LITERAL — replace with actual values, no curly braces in commands.)

Detecting when to fall back#

After review-deepdive runs, programmatically inspect its JSON output for sparse review aggregation. The composite continues past review failures, so success is NOT proof of usable insights. Detection rule:

python

import json
deepdive = json.load(open("deepdive.json"))
reviews_section = deepdive.get("reviews", {})
# review-deepdive currently makes one /reviews/analysis call per labelType (target_painPoints,
# target_positives, etc.). All-fail means switch to fallback.
all_failed = all(
    sub.get("success") is False
    or not (sub.get("data") or {}).get("consumerInsights")
    for sub in reviews_section.values()
    if isinstance(sub, dict)
)
target_review_count = (deepdive.get("target_realtime", {}) or {}).get("data", {}).get("ratingCount", 0)
# Fallback triggers if ANY of these are true:
needs_fallback = (
    all_failed
    or target_review_count < 50
    or any((sub.get("error") or {}).get("code") == "INSUFFICIENT_REVIEWS"
           for sub in reviews_section.values() if isinstance(sub, dict))
)

If needs_fallback is True, run the "Insufficient Data Fallback" workflow below. Important: the fallback REPLACES ONLY the review-analysis piece. Keep using the deepdive's other outputs ( target_realtime, competitors, market, brand_overview, price_band_overview, product_history) for the corresponding report sections.

Insufficient Data Fallback#

When /reviews/analysis cannot produce meaningful aggregation, fetch raw reviews live from Amazon and use this skill's own LLM (you) to perform Map/Reduce in-context. No external LLM service or API key is required.

Working directory convention: create a per-run temp dir to keep intermediate files together. Create it with mktemp -d (private, 0700 — not a predictable path) and keep raw.json, tagged.json, clusters.json, insights.json inside it. Example:

bash

WORK=$(mktemp -d)

Remove the directory ( rm -rf "$WORK") after Step 4 succeeds or the workflow aborts.

Step 1 — Fetch raw reviews#

bash

python3 {skill_base_dir}/scripts/zoodata.py reviews-raw \
    --asin <ASIN> [--marketplace US] [--max-pages 10] > $WORK/raw.json
# Cost: 1 credit/page, 10 reviews/page, hard cap 100 (10 pages).
# Stops automatically when nextCursor=null (small-volume ASINs may exhaust earlier).
# For cost control: --max-pages 5 = 50 reviews / 5 credits / ~30s.

Then save just the reviews array for downstream tooling:

bash

python3 -c "import json,sys; d=json.load(open('$WORK/raw.json'))['data']['reviews']; json.dump(d,open('$WORK/reviews_array.json','w'),ensure_ascii=False)"

Step 2 — Map (per-review tagging)#

review-tag-prompt renders the prompt but does NOT call any LLM — YOU (this skill's LLM) produce the JSON. The template is uniform per review, so render it ONCE to learn the schema, then mass-produce tags for all reviews in a single in-context pass.

bash

# Render the prompt for ONE review to learn the schema (do this once per skill run)
python3 {skill_base_dir}/scripts/zoodata.py review-tag-prompt \
    --review "$(python3 -c 'import json,sys; print(json.dumps(json.load(open(sys.argv[1]))[0]))' $WORK/reviews_array.json)" \
    [--product-title "..."] [--product-category "..."]

The schema you must produce per review (12 fields, all required, empty arrays for empties):

json

{
  "sentiment": "positive|neutral|negative",
  "mentioned_scenarios": [], "mentioned_issues": [], "mentioned_positives": [],
  "mentioned_improvements": [], "mentioned_buying_factors": [],
  "mentioned_pain_points": [], "user_profiles": [],
  "mentioned_usage_times": [], "mentioned_usage_locations": [],
  "mentioned_behaviors": [], "keywords": []
}

After producing tags for all N reviews, save them as a JSON array preserving review order:

bash

# Save your in-context output as the array (example structure)
cat > $WORK/tagged.json <<'EOF'
[ {tag obj for review[0]}, {tag obj for review[1]}, ... ]
EOF

Step 3 — Reduce (semantic clustering per dimension)#

First extract unique candidate phrases per dimension from tagged.json:

python

import json
from collections import defaultdict
tagged = json.load(open(f"{WORK}/tagged.json"))
DIMS = ["mentioned_scenarios","mentioned_issues","mentioned_positives",
        "mentioned_improvements","mentioned_buying_factors","mentioned_pain_points",
        "user_profiles","mentioned_usage_times","mentioned_usage_locations",
        "mentioned_behaviors","keywords"]
candidates = {d: sorted({el.strip().lower() for t in tagged for el in (t.get(d) or [])}) for d in DIMS}

Then for EACH of the 11 dimensions, render the reduce prompt and YOU produce clusters:

bash

python3 {skill_base_dir}/scripts/zoodata.py review-reduce-prompt \
    --label-type positives \
    --candidates '["comfortable","comfy","very comfortable",...]'
# → YOU produce {"clusters": [{"canonical": "Comfortable Fit",
#                              "members": ["comfortable","comfy","very comfortable"]}]}

Assemble all 11 dimension cluster outputs into one clusters.json:

json

{
  "mentioned_scenarios": [{"canonical": "...", "members": [...]}],
  "mentioned_issues":    [{"canonical": "...", "members": [...]}],
  ... (all 11 dims, even if empty: use [])
}

Keywords dim chunking: when keywords has >150 unique candidates, split into chunks of ~150, render the reduce prompt per chunk, and merge clusters across chunks by case-insensitive canonical name match. Other dims rarely exceed 100 candidates.

Step 4 — Aggregate (no LLM, pure local)#

bash

python3 {skill_base_dir}/scripts/zoodata.py review-aggregate \
    --reviews $WORK/raw.json \
    --tagged $WORK/tagged.json \
    --clusters $WORK/clusters.json > $WORK/insights.json
# Output structure matches /reviews/analysis:
#   { reviewCount, avgRating, sentimentDistribution, consumerInsights[], topKeywords[] }
# Each consumerInsight has: {element, labelType, count, reviewRate, avgRating}

Use the same Pain Point Impact Ranking and Differentiation Priority tables above — but apply the small-sample caveat when reviewCount < 50.

Quality flags to surface in the final report#

When generating the report from a fallback run, the Data Provenance section MUST flag:

1. Sample-size warning — if reviewCount < 50, banner above all rate-based tables.

2. Suspicious review patterns — scan raw.json for clusters of:

   • Same date + ≥3 unverified reviews + similar themes (potential seeded reviews)
   • Same author across multiple ASINs (review farm signal) Report these as "🔍 Possible seeded reviews" in Data Provenance.

3. Spider exhaustion — if pages < max_pages and capped == false, note that Spider exhausted the visible review window before reaching the 100-cap.

Competitor Comparison in fallback mode#

The default fallback workflow only fetches reviews for the TARGET ASIN. SKILL.md's "Competitor Comparison" rules (your-rate vs competitor-rate) require competitor review data, which is NOT available by default in fallback. Two options:

• Option A (default): in the report's Competitor Comparison section, note "Pain-rate comparison unavailable in fallback mode — competitor review aggregations not fetched". Use only structural comparison (rating, ratingCount, price).
• Option B (extension): for each top-3 competitor ASIN from the deepdive's competitors output, run Steps 1-4 again per ASIN. Cost: ~10 credits per competitor + LLM time. Only do this when the user explicitly asks for sentiment comparison.

Cost / latency benchmark#

Sample sizeFetchLLM Map+ReduceAggregateTotal100 reviews60s + 10 creditsmodel-dependent (suggest ≤20 concurrent)<1s90-120s50 reviews30s + 5 creditshalf<1s~60s14 reviews (validated)20s + 2 creditsinline single pass<1s30s

Quality vs /reviews/analysis: comparable 11-dim coverage; finer sizing-direction splits (small vs large vs inaccurate) than server-side aggregation; properly distinguishes painPoints (problems experienced) from positives (problems solved).

Output#

Respond in user's language.

Sections: Review Snapshot → Top 10 Pain Points (with count & %) → Top 10 Positives → Buying Factors → Improvement Wishlist → Consumer Profile → Usage Patterns → Competitor Comparison → Listing Copy Suggestions → Differentiation Roadmap (impact-ranked) → Data Provenance → API Usage

Do NOT invent insights — only report what the API returns. Omit empty dimensions.

Cross-validation rule (mandatory): star distribution ( ratingBreakdown) should match sentiment distribution (from reviews/analysis OR fallback Map tags). Compute:

• 4-5★ % vs positive %
• 3★ % vs neutral %
• 1-2★ % vs negative %

If any band mismatches by >15 percentage points, re-examine the Map tags before publishing. Common causes: LLM mis-classifying a 5★ "didn't love it but works" as positive; non-English reviews mis-tagged. Document residual mismatch in Data Provenance.

Language (required)#

Output language MUST match the user's input language. If the user asks in Chinese, the entire report is in Chinese. If in English, output in English. Exception: API field names (e.g. monthlySalesFloor, categoryPath), endpoint names, technical terms (e.g. ASIN, BSR, CR10, FBA, credits) remain in English.

Disclaimer (required, at the top of every report)#

Data is based on ZooData API sampling as of [date]. Monthly sales ( monthlySalesFloor) are lower-bound estimates. This analysis is for reference only and should not be the sole basis for business decisions. Validate with additional sources before acting.

Confidence Labels (required, tag EVERY conclusion)#

• 📊 Data-backed — direct API data (e.g. "painPoint 'durability' mentioned by 27% of reviewers 📊")
• 🔍 Inferred — logical reasoning from data (e.g. "durability is the #1 differentiation opportunity 🔍")
• 💡 Directional — suggestions, predictions, strategy (e.g. "highlight durability in bullet point #1 💡")

Rules: Strategy recommendations and listing copy suggestions are NEVER 📊. User criteria override AI judgment.

Aggregate-label rule (applies to ALL report output, not just fallback): NEVER attach 📊 to ANY element that aggregates or groups underlying content when ANY piece of that content is 🔍 or 💡. "Aggregate/grouping elements" include:

• Section headers at EVERY level ( #, ##, ###, ####) — including top-level summary sections like "Overall Score", "Verdict", "Executive Summary"
• Summary/score lines anywhere in the report (e.g. ## Overall Score — 27/100 · Grade F 📊 is WRONG if any Basis row inside is 🔍)
• Table column headers in comparison tables (e.g. **Target ASIN** 📊 as a column label is WRONG if any cell in that column contains 🔍)
• Table row headers or row-aggregation labels (when the row aggregates multiple cells of mixed confidence)
• Any other visual grouping label — bullet-list group titles, callout box titles, etc.

A group-level 📊 implies the whole block/column/row is data-backed, which smuggles inferred/directional content into the 📊 tier via visual grouping. Either (a) omit the group-level label entirely (preferred when content mixes tiers), or (b) use the LOWEST confidence present inside (🔍 if any underlying content is 🔍; 💡 if any is 💡). This is a universal output-quality rule — it applies regardless of which fallback path (if any) was triggered.

Emoji reservation rule (closely related): The three confidence symbols 📊 🔍 💡 are RESERVED for confidence labeling. NEVER use them as decorative prefixes on section headers, table headers, or any aggregate element — even when you also include a correct confidence suffix on the same line. Example:

• ❌ WRONG: ## 📊 Overall Score — 27/100 · Grade F 🔍 (the leading 📊 reads as a data-backed claim even though the trailing 🔍 is correct)
• ✅ RIGHT: ## Overall Score — 27/100 · Grade F 🔍 (no decorative emoji, just the proper confidence suffix)
• ✅ RIGHT: ## 🎯 Overall Score — 27/100 · Grade F 🔍 (use non-reserved decorative icons like 🎯 🧭 📋 📝 📂 🏁 🚨 🏆 🔔 when a visual prefix is desired)

Decorative emoji ≠ confidence label — but from a reader's perspective, a leading 📊/🔍/💡 is indistinguishable from a confidence claim. Reserve these three symbols EXCLUSIVELY for confidence annotation to avoid ambiguity.

Data Provenance (required)#

Include a table at the end of every report:

DataEndpointKey ParamsNotes(e.g. Market Overview)markets/searchcategoryPath, topN=10📊 Top N sampling, sales are lower-bound............

Extract endpoint and params from _query in JSON output. Add notes: sampling method, T+1 delay, realtime vs DB, minimum review threshold, etc.

API Usage (required)#

EndpointCallsCredits(each endpoint used)NNTotalNN

Extract from meta.creditsConsumed per response. End with Credits remaining: N.

API Budget: ~20-30 credits#