amazon-review-insights

Amazon product review intelligence analysis tool for global e-commerce sellers. Core capabilities:fetch Amazon reviews, AI-powered negative review analysis, quantify high-frequency issues, discover hidden negative feedback in 5-star reviews, generate improvement suggestions, track review trends, inc

AstrMap Review Insights Skill

Language

• Reply in English if user input is in English or non-Chinese (as this is the unified language)
• Reply in 中文 if user input is in Chinese

Configuration

API Key

All API calls require an API Key for authentication.

Note: The API endpoint is fixed at https://api.astrmap.com and is not configurable.

Recommended: Set the environment variable in ~/.zshrc or ~/.bashrc:

bash

export CUSTOMER_INSIGHTS_API_KEY="your-api-key-here"

To obtain an API Key: Download and install the AstrMap desktop client from https://www.astrmap.com/, log in, click User Menu (bottom-left) → API Keys, create and copy your API Key.

Important: If CUSTOMER_INSIGHTS_API_KEY is not set or no API Key is provided, ask the user first:

"Please provide your AstrMap API Key (download at https://www.astrmap.com/, log in, click User Menu → API Keys to create one)"

Then pass it via --api-key parameter for all subsequent commands.

Security Notice: This Skill sends the API Key to AstrMap servers (api.astrmap.com) for authentication. The API Key will not be used to access other services.

Feature Tiers

Feature	Requires Collection Channel (desktop client recommended; browser extension requires user environment ready, see below)	Requires API Key
Query completed analysis results	No	Yes
Create collection-only task	Yes (online)	Yes
Create auto-analysis task	Yes (online)	Yes
Incremental fetch	Yes (online)	Yes
Manual trigger analysis	No	Yes

Tip: If you only need to query completed analysis results, you can use the API Key directly without downloading the desktop client.

Collection Channel: Desktop Client (Recommended)

Creating tasks requires a collection channel running online. The AstrMap desktop client is recommended (download/install/login guide below):

The browser extension can also collect at the system level (check_device may return an online endpoint with endpoint_type=extension), but it depends on the user's browser environment (extension installed + Amazon account logged in on Chrome + proxy enabled), which the Agent cannot verify; When creating tasks via Skill/API, use the desktop client as the recommended channel unless the user explicitly confirms the extension is ready.

When the collection channel is offline (check_device returns is_alive=false with endpoint_id/endpoint_type null — a normal response, not an error code):

1. Ask the user: "No collection device is online. Have you installed and started the AstrMap desktop client?"
2. If not installed: Ask if you should help download, then guide through extraction and startup
3. If installed but not running: Prompt the user to start the desktop client
4. Re-check: Run check_device again; confirm is_alive=true before creating the task

Desktop Client Download & Installation

1. Get Download Links

bash

python scripts/api_client.py --action get_download_links

2. Extraction Notes

Important: Do not use Windows built-in extraction tools (may cause issues). Use 7-Zip, WPS Extraction, or similar tools instead.

3. Startup Guide

macOS: Move the folder to "Applications" directory, right-click Astrmap.app → "Open", if blocked go to "System Settings → Privacy & Security → General" → "Still open".

Windows: Right-click "launch.vbs" → "Run with PowerShell" or double-click to start.

4. Initial Setup

After launching:

1. Log in to your AstrMap account
2. Log in to your Amazon buyer account (do not use your seller account)
3. Ensure Amazon access is working

Security & Verification

For detailed security verification, privacy risk statement, Amazon account security, and API Key safety guidelines, read {baseDir}/references/security.md.

Dependency Installation

bash

pip install -r requirements.txt

Important Notes

Points System

• Create task (auto mode): Free review collection, AI analysis deducts points
• Create task (collection-only mode): Free review collection, no point deduction
• Incremental fetch: Fetch latest reviews and re-analyze, deducts points
• Query results: View completed results, no point deduction

Prerequisites (only for creating tasks)

1. AstrMap desktop client is logged in
2. Desktop client is logged in to Amazon buyer account
3. Amazon access is working

Querying completed task results has no restrictions and can be called directly.

Workflow

Invocation

bash

python scripts/api_client.py --action <action> [--params...]

1. Check Device Online

bash

python scripts/api_client.py --action check_device --api-key "your-key"

Response: {is_alive: true, endpoint_id: "xxx", endpoint_type: "desktop", status: "idle"}

v2.2 field rename: online → is_alive, device_id → endpoint_id, plus new endpoint_type. When offline, is_alive is false and endpoint_id / endpoint_type are null.

2. Create Task

Note: Creating a task deducts points. Before executing, inform the user and wait for confirmation: "About to create task. Current points: {points}. This will deduct points. Continue?"

Create Task Flow:

1. --action check_device → Check device online status
2. --action get_points → Check account points
3. Inform user of point consumption, wait for confirmation
4. Confirm prerequisites, then --action create_task --asin <ASIN> --site <site> [--is-auto false]

Run Mode:

Parameter	Description
--is-auto true (default)	Auto mode: automatically trigger AI analysis after collection
--is-auto false	Collection-only mode: stops at "pending analysis" status

Site Mapping: US/CA/UK(English), DE(German), FR(French), IT(Italian), ES(Spanish), JP(Japanese)

Command Examples:

bash

python scripts/api_client.py --action create_task --api-key "your-key" --asin "B09V3KXJPB" --site US

3. Poll Task Status

After submission, poll every 6 minutes:

bash

python scripts/api_client.py --action get_task_detail --api-key "your-key" --task-id "TSK_xxx"

Status Flow:

Auto Mode (is_auto=true): PENDING → DISPATCHING → COLLECTING → PROCESSING → ANALYZING → SUCCESS/FAILED/CANCELLED

Collection-only Mode (is_auto=false): PENDING → DISPATCHING → COLLECTING → COLLECTED

Status Prompts:

Status	User Message
PENDING	"Task submitted, waiting for scheduling..."
DISPATCHING	"Allocating device..."
COLLECTING	"Fetching Amazon review data, please wait (usually 20~120 seconds)"
PROCESSING	"Review data fetched, processing..."
ANALYZING	"Data processing complete, AI analyzing..."
SUCCESS	"Analysis complete! Fetching results..."
FAILED	"Task failed. Please check device status and network connection."
CANCELLED	"Task cancelled"
COLLECTED	"Collection complete! In pending analysis state."

If task does not complete after a long time (over 18 minutes), prompt user to check if desktop client is online.

4. Get Analysis Results

bash

# AI Insights Summary
python scripts/api_client.py --action get_ai_insights --api-key "your-key" --task-id "TSK_xxx"
# Category-Tag Distribution
python scripts/api_client.py --action get_category_tag_distribution --api-key "your-key" --task-id "TSK_xxx"
# Basic Statistics
python scripts/api_client.py --action get_basic_statistics --api-key "your-key" --task-id "TSK_xxx"
# Negative Reviews List
python scripts/api_client.py --action get_negative_reviews --api-key "your-key" --task-id "TSK_xxx" --page 1 --page-size 20

Note: Querying completed task results does not deduct points and has no prerequisites.

5. Incremental Fetch

Note: Incremental fetch deducts points. Before executing, inform user and wait for confirmation.

Incremental Fetch Flow:

1. Check device and points
2. Inform user of point consumption, wait for confirmation
3. --action create_incremental --task-id <task_id>
4. Poll status (same as create task)

6. Manual Trigger Analysis (Collection-only Mode)

Tasks in collection-only mode (is_auto=false) stop at COLLECTED status, requiring manual AI analysis trigger:

bash

python scripts/api_client.py --action trigger_analysis --api-key "your-key" --task-id "TSK_xxx"

Status flow: COLLECTED → PROCESSING → ANALYZING → SUCCESS

All Available Actions

action	Description	Required Parameters
get_download_links	Get desktop client download links	-
check_device	Check if device is online	-
create_task	Create task	--asin, --site
create_incremental	Incremental fetch	--task-id
rename_task	Rename a task	--task-id, --name
trigger_analysis	Manual trigger analysis	--task-id
get_task_detail	Query task details	--task-id
get_task_list	Get task list	-
get_ai_insights	Get AI insights	--task-id
get_basic_statistics	Get basic statistics	--task-id
get_representative_reviews	Get representative reviews	--task-id
get_category_tag_distribution	Get category-tag distribution	--task-id
get_negative_reviews	Get negative reviews list	--task-id
get_trend	Get review trends	--task-id
get_related_comments	Get comments associated with tag/category	--task-id, --association-type
get_comments	Get raw comments	--task-id
get_comments_overview	Get comments overview	--task-id
get_points	Query points balance	-

Error Handling

Note: api_client throws API Error: {msg} for any non-zero code — rely on the returned msg for diagnosis; an offline collection channel is not an error code, but check_device's normal is_alive=false response.

Error Code	Description	Handling
Device offline	check_device returns is_alive=false (normal response, not an error code)	No collection channel online; guide the user to install/start the desktop client (recommended)
1002	Insufficient points	Prompt user to recharge at https://www.astrmap.com/
2001	Invalid API Key	Check if API Key is correct
2002	API Key disabled	Prompt user to create new API Key
2003	API Key expired	Prompt user to create new API Key
2004	Insufficient permissions	Check API Key permission configuration
2005	Request rate exceeded	Prompt user to retry later
InvalidTaskStatus	Task status is not COLLECTED	Only collection-only tasks with COLLECTED status can trigger analysis

Detailed API Documentation

For detailed API endpoint documentation, request parameters, and response formats, see API Reference.

Usage Examples

Scenario 1: Create New Task

text

User: Help me get and analyze reviews for B09V3KXJPB
AI Agent:
1. Check API Key → if not configured, ask user to provide
2. Check device and points
3. Inform point consumption, wait for confirmation
4. Create task
5. Poll status every 6 minutes, provide real-time progress
6. After analysis complete, get results

Scenario 2: Collection-only Mode + Manual Trigger Analysis

text

User: Help me collect reviews only, don't analyze for now
AI Agent:
1. Check API Key and device
2. Create task with --is-auto false
3. Poll status until COLLECTED
4. After user confirms analysis, run trigger_analysis (API Key only, no desktop client required)

Scenario 3: Query Completed Task

text

User: View analysis results for TSK_xxx
AI Agent:
1. Check API Key
2. Get analysis results directly (no device or prerequisites required)