name: pangolinfo-amazon-scraper
description: >
Scrape Amazon product data using Pangolin APIs. Use this skill when the user
wants to: look up Amazon products by ASIN, search Amazon by keyword, check
bestsellers/new releases, get product reviews or pricing, compare products
across Amazon regions, browse categories, or research sellers.
Requires PANGOLIN_EMAIL + PANGOLIN_PASSWORD env vars (or PANGOLIN_API_KEY).

Pangolinfo Amazon Scraper

Scrape Amazon product data via Pangolin's structured APIs. Returns parsed JSON with product details, search results, rankings, reviews, and more across 13 Amazon regions.

When to Use This Skill

Activate this skill when the user's intent matches any of these patterns:

Keywords that trigger this skill: Amazon, ASIN, B0-prefixed codes, product reviews, bestseller, new release, Amazon category, Amazon seller, amz_us/amz_uk/etc., product detail, Amazon search, price comparison across Amazon sites.

Prerequisites

Required

• Python 3.8+ (uses only the standard library -- zero external dependencies)
• Pangolin account at pangolinfo.com
• Environment variables (one of the following):
  • PANGOLIN_API_KEY -- API key (skips login), OR
  • PANGOLIN_EMAIL + PANGOLIN_PASSWORD -- auto-login with caching

macOS SSL Certificate Fix

On macOS, Python may fail with CERTIFICATE_VERIFY_FAILED because it ships without root certificates by default.

Symptoms: The script exits with error code SSL_CERT.

Solutions (pick one):

1. Run the certificate installer bundled with Python:

   /Applications/Python\ 3.x/Install\ Certificates.command

   (Replace 3.x with your Python version, e.g., 3.11)

2. Set SSL_CERT_FILE from the certifi package:

   pip3 install certifi
   export SSL_CERT_FILE=$(python3 -c "import certifi; print(certifi.where())")

3. Add the export to your shell profile (~/.zshrc or ~/.bashrc) so it persists.

First-Time Setup Guide

When a user tries to use this skill and authentication fails (error code MISSING_ENV), do not just repeat the error hint. Instead, walk the user through the full setup process interactively:

Step 1: Explain what's needed

Tell the user (in their language):

To use this skill, you need a Pangolin API account. Pangolin provides Amazon product data scraping through its APIs.

使用本技能需要 Pangolin API 账号。Pangolin 提供亚马逊商品数据抓取的 API 服务。

Step 2: Guide registration

1. Go to pangolinfo.com and create an account

2. After login, find your API Key in the dashboard

3. 访问 pangolinfo.com 注册账号

4. 登录后在控制台找到你的 API Key

Step 3: Collect credentials and authenticate automatically

When the user provides their credentials, you (the AI agent) should configure them securely. The script will automatically cache the API key at ~/.pangolin_api_key for all future calls.

If user provides an API key (recommended):
Write it directly to the cache file — avoids shell history entirely:

echo "<api_key>" > ~/.pangolin_api_key
chmod 600 ~/.pangolin_api_key 2>/dev/null
python3 scripts/pangolin.py --auth-only

If user provides email + password:
Set env vars in the session and clean up after auth:

export PANGOLIN_EMAIL="user@example.com"
export PANGOLIN_PASSWORD="their-password"
python3 scripts/pangolin.py --auth-only
unset PANGOLIN_EMAIL PANGOLIN_PASSWORD

This avoids passwords appearing in shell history (unlike inline VAR=x command syntax) and cleans up credentials after the API key is cached.

Both methods cache the API key automatically. After this one-time setup, no environment variables are needed — all future calls will use the cached API key at ~/.pangolin_api_key.

Step 4: Confirm and proceed

After auth returns "success": true:

1. Tell the user: "认证成功！API Key 已自动缓存，后续使用无需再次输入。" / "Authentication successful! API Key cached — no need to enter credentials again."
2. Immediately retry their original request.

Important

• The user only needs to provide credentials ONCE — the script caches the API key permanently at ~/.pangolin_api_key
• Do not ask the user to manually edit .bashrc or .zshrc — the script handles persistence automatically
• If the user doesn't have an account yet, explain Pangolin's credit system (1 credit per Amazon json request, 5 credits per review page) and direct them to pangolinfo.com
• If auth succeeds but credits are exhausted (error code 2001), tell the user to top up at pangolinfo.com
• The API key is permanent and does not expire unless the account is deactivated

Script Execution

The script is located at scripts/pangolin.py relative to this skill's root directory.

Path resolution: When invoking the script, resolve the absolute path from the skill directory. For example, if this skill is installed at /path/to/pangolinfo-amazon-scraper/:

python3 /path/to/pangolinfo-amazon-scraper/scripts/pangolin.py --content B0DYTF8L2W --mode amazon --site amz_us

Intent-to-Command Mapping

1. Product Detail by ASIN

User says: "Look up B0DYTF8L2W on Amazon" / "查一下 B0DYTF8L2W 这个产品"

python3 scripts/pangolin.py --content B0DYTF8L2W --mode amazon --site amz_us
# Or using the --asin shortcut:
python3 scripts/pangolin.py --asin B0DYTF8L2W --site amz_us

The script auto-detects 10-character alphanumeric codes as ASINs and selects amzProductDetail. The --asin flag is a convenience shortcut that sets --content and defaults to amzProductDetail parser automatically.

2. Keyword Search

User says: "Search Amazon for wireless mouse" / "在亚马逊搜索无线鼠标"

python3 scripts/pangolin.py --q "wireless mouse" --mode amazon --site amz_us

Non-ASIN text auto-selects amzKeyword parser.

3. Bestsellers

User says: "Show me electronics bestsellers" / "看看电子产品畅销榜"

python3 scripts/pangolin.py --content "electronics" --mode amazon --parser amzBestSellers --site amz_us

4. New Releases

User says: "What's new in toys on Amazon?" / "亚马逊玩具类有什么新品？"

python3 scripts/pangolin.py --content "toys" --mode amazon --parser amzNewReleases --site amz_us

5. Category Products

User says: "Browse category 172282 on Amazon" / "浏览亚马逊分类 172282"

python3 scripts/pangolin.py --content "172282" --mode amazon --parser amzProductOfCategory --site amz_us

6. Seller Products

User says: "Show products from seller A1B2C3D4E5" / "查看卖家 A1B2C3D4E5 的商品"

python3 scripts/pangolin.py --content "A1B2C3D4E5" --mode amazon --parser amzProductOfSeller --site amz_us

7. Follow Seller (Variant / Seller Options)

User says: "Show other seller options for B0G4QPYK4Z" / "查看 B0G4QPYK4Z 的其他卖家选项"

python3 scripts/pangolin.py --asin B0G4QPYK4Z --parser amzFollowSeller --site amz_us

Uses a dedicated API endpoint (/api/v1/scrape/follow-seller). Returns variant options including price, delivery, fulfillment, and seller info for the given ASIN.

8. Product Reviews

User says: "Get critical reviews for B00163U4LK" / "看看 B00163U4LK 的差评"

python3 scripts/pangolin.py --content B00163U4LK --mode review --site amz_us --filter-star critical

Star filter mapping:

Sort mapping:

Multiple pages: Add --pages N (each page costs 5 credits).

9. Product by URL (Legacy)

User says: "Scrape this Amazon page: https://www.amazon.com/dp/B0DYTF8L2W"

python3 scripts/pangolin.py --url "https://www.amazon.com/dp/B0DYTF8L2W" --mode amazon

The site code is auto-inferred from the URL domain.

10. Different Region

User says: "Check price on Amazon Japan" / "看看日本亚马逊的价格"

Region mapping:

Smart Defaults

The script automatically:

1. Detects ASINs -- 10-character alphanumeric strings like B0DYTF8L2W auto-select amzProductDetail
2. Detects keywords -- non-ASIN text like "wireless mouse" auto-selects amzKeyword
3. Defaults to amz_us if no --site is provided
4. Switches to review mode if --filter-star is used or --parser amzReviewV2 is set
5. Infers site from URL when using --url with an Amazon domain

You generally only need --parser for bestsellers, new releases, category, and seller lookups.

Output Format

Amazon Mode (product/keyword/ranking/category/seller)

{
  "success": true,
  "task_id": "02b3e90810f0450ca6d41244d6009d0f",
  "url": "https://www.amazon.com/dp/B0DYTF8L2W",
  "metadata": {
    "executionTime": 1791,
    "parserType": "amzProductDetail",
    "parsedAt": "2026-01-13T06:42:01.861Z"
  },
  "results": [ ... ],
  "results_count": 1
}

Review Mode

Same envelope structure. Each result object contains review fields: date, country, star, author, title, content, purchased, vineVoice, helpful, reviewId.

Error Output

All errors use a unified envelope written to stderr:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "hint": "Actionable suggestion"
  }
}

See references/output-schema.md for complete field documentation.

Response Presentation

When presenting results to the user, follow these guidelines per parser type. Always match the user's language (respond in Chinese if the user wrote in Chinese, etc.).

Product Detail (amzProductDetail)

Present as a structured product card:

• Title and brand
• Price (include strikethrough/coupon if present)
• Rating: star rating + number of reviews
• Stock status and delivery estimate
• Key features (bullet list, up to 5)
• Bestseller rank and category
• Include the product image if available
• Note Amazon's Choice badge if acBadge is present

Keyword Search (amzKeyword)

Present as a numbered list of products:

1. Title -- price -- star rating (N reviews) -- delivery info
2. ...

Highlight sponsored results. Show the total results count. If the user asked about a specific need, recommend the best match.

Bestsellers / New Releases (amzBestSellers / amzNewReleases)

Present as a ranked list:

1. #1: Title -- price -- star rating
2. #2: ...

Emphasize rank position. Note trends if multiple queries are compared.

Category / Seller Products (amzProductOfCategory / amzProductOfSeller)

Present as a numbered product list similar to keyword search. Group by price range or rating if the user is comparing.

Follow Seller (amzFollowSeller)

Present variant options clearly:

• Option 1: price, delivery, ships from, sold by
• Option 2: ...

Help the user compare variants (color, size, seller).

Reviews (amzReviewV2)

Present as:

1. Summary: average sentiment, common themes, verified purchase ratio
2. Individual reviews (top 3-5): star + title + excerpt + date + verified badge
3. Pattern analysis: recurring praise/complaints

Empty Results

If results_count is 0:

• Suggest checking the ASIN/keyword spelling
• Suggest trying a different Amazon region
• Suggest broadening the search terms

Error Results

If success is false:

• Present the error message in friendly, non-technical language
• Provide the hint from the error object
• Offer to retry or suggest an alternative approach

All CLI Options

Output Schema

See references/output-schema.md for the complete JSON output schema, including per-parser field documentation and guaranteed vs optional fields.

Amazon Parsers Reference

Amazon Sites Reference

Cost

Credits are only consumed on successful requests (API code 0). Average response time is approximately 5 seconds.

Exit Codes

Troubleshooting

API error codes from the server:

Important Notes for AI Agents

1. Never dump raw JSON to the user. Always parse and present results in a structured, readable format following the Response Presentation guidelines above.

2. Match the user's language. If the user writes in Chinese, respond in Chinese. If English, respond in English. This applies to product descriptions, error messages, and suggestions.

3. Be proactive. If a keyword search returns results, highlight the best match. If reviews show a pattern, summarize it. If a product is out of stock, say so immediately.

4. Handle multi-step requests. If the user says "compare this product on US and Japan Amazon," run two queries with different --site values and present a comparison table.

5. Credit awareness. Each request costs credits. Avoid unnecessary duplicate requests. If the user asks for reviews across multiple pages, warn them about the cost (5 credits per page).

6. Error recovery. If a request fails, check the error code and suggest a fix before retrying. Do not retry blindly.

7. ASIN detection. If the user provides a 10-character code starting with B0, it is almost certainly an ASIN. Auto-detect and use --content with no extra prompting.

8. Default to amz_us unless the user specifies a region or the context implies a different marketplace.

9. Security. Never expose API keys, passwords, or full API responses containing authentication data in the conversation.

10. Combine results. When the user asks a compound question (e.g., "find a good wireless mouse under $30 with good reviews"), run a keyword search first, then fetch reviews for the top candidates. Present a consolidated recommendation.