Pangolinfo Amazon Niche Finder

Find low-competition Amazon niches and category opportunities before you source or launch a product.

First win in 30 seconds

If your Pangolinfo credentials are already configured, run this first:

python3 scripts/pangolinfo.py --api category-search --keyword "yoga mat"

What success looks like

A successful first run gives you:

• matching Amazon categories in English and Chinese
• category IDs you can drill into immediately
• sellable and hasChild signals for fast triage
• a clear next step: path lookup, tree browsing, or deeper niche filtering

What to do next

1. Browse the category tree

python3 scripts/pangolinfo.py --api category-tree

2. Resolve full category paths

python3 scripts/pangolinfo.py --api category-paths --category-ids "2619526011,172282"

3. Validate higher-conviction niche opportunities (costs 10 credits)

python3 scripts/pangolinfo.py --api niche-filter --marketplace-id US --niche-title "yoga mat"

Use when

• you want to validate a product idea before sourcing or launch
• you need to explore Amazon category trees and subcategories
• you want to compare demand vs competition across categories and niches
• you are looking for low-competition or blue-ocean opportunities
• you need to decide which categories deserve deeper metric filtering

Do not use this skill for Amazon product scraping, keyword SERP scraping, or review extraction. Use pangolinfo-amazon-scraper for those tasks.

Compatible agent frameworks

• OpenClaw
• Claude Code / Cursor
• LangChain / LangGraph
• AutoGen / CrewAI

🌐 多语言适配 (Multi-language Support)

• 🇨🇳 中文适用场景: 亚马逊底层选品类目挖掘与 BSR 追踪。通过细分市场过滤器定位蓝海类目，辅助卖家数据决策。
• Agent Directive: Always output the final analysis/report in the language of the user's prompt (e.g., reply in Chinese if asked in Chinese).

First-use execution preference for AI agents

• On first invocation or vague requests, start with category-search or category-tree, not niche-filter.
• Use category-paths next when the user needs structural context or browse-node resolution.
• Use category-filter or niche-filter only when the user explicitly asks for metric-based filtering or deeper validation.
• Warn before niche-filter; it costs 10 credits.

Pangolinfo Amazon Niche Data

Query Amazon category and niche intelligence via Pangolinfo's 利基数据 (niche data) APIs. Covers 5 endpoints under /api/v1/amzscope/* for category exploration, search, path resolution, and advanced filtering by business metrics.

When to Use This Skill

Do not use for Amazon product scraping, keyword search, or reviews -- those require the pangolinfo-amazon-scraper skill.

Prerequisites

• Python 3.8+ (stdlib only, no pip install needed)
• Pangolinfo account at pangolinfo.com
• Environment variables: PANGOLINFO_API_KEY (recommended) OR PANGOLINFO_EMAIL + PANGOLINFO_PASSWORD

Security: Credentials are held in-memory only by default. The script will not write any key or password to disk unless you explicitly opt in via --cache-key (or PANGOLINFO_CACHE=1), which persists the API key to ~/.pangolinfo_api_key (mode 600).

macOS SSL error? Run: /Applications/Python\ 3.x/Install\ Certificates.command

Script Execution

python3 scripts/pangolinfo.py --api category-search --keyword "yoga mat"

Intent-to-Command Mapping

1. Browse Category Tree (top-level)

python3 scripts/pangolinfo.py --api category-tree

2. Browse Children of a Specific Node

python3 scripts/pangolinfo.py --api category-tree --parent-path "2619526011"

Nested nodes use /-joined paths: --parent-path "2619526011/18116197011".

3. Search Categories by Keyword

python3 scripts/pangolinfo.py --api category-search --keyword "yoga mat"

Matches both English and Chinese category names.

4. Batch Resolve Category Paths

python3 scripts/pangolinfo.py --api category-paths --category-ids "2619526011,172282"

Also accepts JSON array: --category-ids '["2619526011","172282"]'.

5. Filter Categories by Business Metrics

python3 scripts/pangolinfo.py --api category-filter \
  --marketplace-id US --time-range l7d --sample-scope all_asin

Single-category detail:

python3 scripts/pangolinfo.py --api category-filter \
  --marketplace-id US --time-range l7d --sample-scope all_asin \
  --category-id 979832011

With advanced filters via --extra:

python3 scripts/pangolinfo.py --api category-filter \
  --marketplace-id US --time-range l30d --sample-scope all_asin \
  --extra 'buyBoxPriceAvgMin=1000' \
  --extra 'buyBoxPriceTiers=["mainstream","premium"]' \
  --extra 'sortField=unitSoldSum' \
  --extra 'sortOrder=desc'

6. Filter Niches by Business Metrics

python3 scripts/pangolinfo.py --api niche-filter --marketplace-id US

Search by title:

python3 scripts/pangolinfo.py --api niche-filter \
  --marketplace-id US --niche-title "yoga mat"

With advanced range filters:

python3 scripts/pangolinfo.py --api niche-filter \
  --marketplace-id US \
  --extra 'searchVolumeT90Min=1000' \
  --extra 'sortField=searchVolumeT90' \
  --extra 'sortOrder=desc'

Smart Defaults

1. Pagination defaults -- page=1, size=10 if not specified
2. Filter APIs cap -- size max 10 and page max 10 for category-filter and niche-filter
3. --extra is JSON-parsed -- numbers become ints, arrays become arrays, strings stay strings
4. Marketplace default -- no default; must be explicitly provided for filter APIs

All CLI Options

APIs

Marketplace IDs

Cost

Credits consumed on success only (API code 0). Empty results are not charged. Auth checks are free.

Output Format

JSON to stdout on success, error JSON to stderr on failure.

Success

{
  "success": true,
  "api": "searchCategoriesAPI",
  "items": [
    {
      "browseNodeId": "9059094011",
      "browseNodeName": "Headphones",
      "browseNodeNameCn": "耳机",
      "sellable": 1,
      "hasChild": 0
    }
  ],
  "total": 33,
  "page": 1,
  "size": 10,
  "totalPages": 4,
  "results_count": 10
}

Error (stderr)

{
  "success": false,
  "error": {
    "code": "API_ERROR",
    "api_code": 1002,
    "message": "Invalid Parameter: keyword is required",
    "hint": "Check required fields for this API. See references/error-codes.md."
  }
}

Response Presentation

Match the user's language. Never dump raw JSON.

• Category Tree: hierarchical list with node name (EN/CN), sellable indicator
• Category Search: numbered list with category path, sellable, hasChild
• Category Paths: table of ID -> full path (EN/CN)
• Category Filter: metric summary card with sales, views, trends, price tier
• Niche Filter: niche overview with search volume, product count, brand count, growth
• Empty results: suggest loosening filters, checking marketplace, broadening search

Exit Codes

Error Reference

Script Error Codes

Pangolinfo API Error Codes

Self-Test

Run bash scripts/self_test.sh to validate all 5 APIs. This consumes up to ~21 credits (Tree 2 + Search 2 + Paths 2 + CategoryFilter 5 + NicheFilter 10). Auth check is free. Only run when you need to verify connectivity.

First-Time Setup

See references/setup-guide.md for interactive setup instructions.

Quick start:

export PANGOLINFO_API_KEY="your-api-key"
python3 scripts/pangolinfo.py --auth-only

Important Notes for AI Agents

1. Never dump raw JSON. Parse and present per the Response Presentation guidelines.
2. Match the user's language.
3. Default to a cheap first win. On first invocation or broad requests, start with category-search or category-tree before expensive filters.
4. Use progressive drill-down. category-paths is usually the second step; category-filter and niche-filter come later when the user asks for deeper validation.
5. Credit awareness. niche-filter costs 10 credits -- warn before using it, especially in loops or bulk scans.
6. Use --extra for advanced filters. All metric range, tier, trend, and sort filters go via --extra key=value.
7. Default to US marketplace unless context implies another region.
8. Combine results intelligently. A typical deeper workflow is category-search → category-paths or category-filter → niche-filter.
9. Security. Never expose API keys or passwords.
10. Suggest next steps. After the first successful run, recommend one concrete follow-up command.

Advanced Filter Reference

See references/amazon-niche-api.md for the full list of --extra filter fields (numeric ranges, tiers, trends, quantile buckets) for Category Filter and Niche Filter APIs.

Output Schema

See references/output-schema.md for per-API field documentation.

🎯 Quick Start Prompts (Copy-Paste)

• "Search Amazon categories for 'standing desk' and tell me which subcategories are worth drilling into next."
• "Resolve the full category paths for these browse node IDs: 2619526011, 172282."
• "Validate whether 'yoga mat' looks promising in Amazon US, and warn me before any 10-credit niche filtering."

🛑 Boundaries & Error Handling

When NOT to use: Do not use for scraping individual product reviews (use amazon-scraper instead). Agent Instructions for Errors:

• 401/403 Auth Error: Ensure PANGOLINFO_API_KEY is injected into the environment.
• 429 Rate Limit: Pause execution for 5 seconds, then retry automatically.