Pangolinfo Amazon Niche Finder

Find profitable Amazon niches and category opportunities with structured category tree data, niche filters, category path lookup, and marketplace-level business metrics. Use when you need an Amazon niche finder, category research API, product opportunity discovery, low-competition niche analysis, demand-vs-competition validation, or blue-ocean subcategory discovery before launching on Amazon. Helpful for requests like "find a low-competition niche", "validate a product idea before sourcing", "browse Amazon category trees", "find promising subcategories", or "is there a skill that can analyze Amazon categories for me".

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

Intent (EN)	Intent (CN)	Action
Browse Amazon category tree	浏览亚马逊类目树	Category Tree
Search for an Amazon category	搜索亚马逊类目	Category Search
Get full path of category IDs	批量查询类目路径	Category Paths
Filter categories by metrics	按指标筛选类目	Category Filter
Find Amazon niches	查找亚马逊利基市场	Niche Filter
Analyze category sales/trends	分析类目销量/趋势	Category Filter
Find low-competition niches	寻找低竞争利基	Niche Filter

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

Flag	Description	Default
--api	API to call (see APIs below)	required
--page	1-based page number (max 10 for filter APIs)	1
--size	Items per page (max 10 for filter APIs)	10
--parent-path	category-tree: parent node path	--
--keyword	category-search: search term (EN or CN)	--
--category-ids	category-paths: comma-separated or JSON array	--
--marketplace-id	Marketplace code (e.g. US, UK, DE)	--
--time-range	Aggregation range (e.g. l7d, l30d, l90d)	--
--sample-scope	Sample scope (e.g. all_asin)	--
--category-id	category-filter: single-category detail	--
--niche-id	niche-filter: specific niche ID	--
--niche-title	niche-filter: keyword match on title	--
--extra	Extra field as key=value (repeatable, JSON-parsed)	--
--auth-only	Auth check only (no credits)	--
--raw	Output raw API response	--
--timeout	Timeout in seconds	120
--cache-key	Persist API key to ~/.pangolinfo_api_key	off

APIs

API	--api value	Required fields	Endpoint	Credits
Category Tree	category-tree	--	/api/v1/amzscope/categories/children	2
Category Search	category-search	--keyword	/api/v1/amzscope/categories/search	2
Category Paths	category-paths	--category-ids	/api/v1/amzscope/categories/paths	2
Category Filter	category-filter	--marketplace-id --time-range --sample-scope	/api/v1/amzscope/categories/filter	5
Niche Filter	niche-filter	--marketplace-id	/api/v1/amzscope/niches/filter	10

Marketplace IDs

Code	Region	Code	Region
US	United States	JP	Japan
UK	United Kingdom	IT	Italy
CA	Canada	ES	Spain
DE	Germany	MX	Mexico
FR	France	AU	Australia
IN	India	BR	Brazil
AE	UAE	SA	Saudi Arabia

Cost

API	Credits
Category Tree	2
Category Search	2
Category Paths	2
Category Filter	5
Niche Filter	10

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

Code	Meaning
0	Success
1	API error
2	Usage error (bad arguments)
3	Network error
4	Authentication error

Error Reference

Script Error Codes

Code	Meaning	Resolution
MISSING_ENV	No credentials	Set env vars
AUTH_FAILED	Wrong credentials	Verify email/password
RATE_LIMIT	Too many requests	Wait and retry
NETWORK	Connection issue	Check internet
SSL_CERT	Certificate error	See macOS SSL fix
API_ERROR	Pangolinfo API error	Check api_code and hint
PARSE_ERROR	Invalid API response	Retry
USAGE_ERROR	Bad arguments	Fix CLI args

Pangolinfo API Error Codes

Code	Meaning	Resolution
1002	Invalid parameter	Check required fields for the API
1004	Invalid token	Auto-retried by script
2001	Insufficient credits	Top up at pangolinfo.com
2005	No active plan	Subscribe at pangolinfo.com
2007	Account expired	Renew at pangolinfo.com
2009	Usage limit reached	Wait for next billing cycle
4029	Rate limited	Reduce request frequency
9100	Service disabled	Retry later
9101	Data source unavailable	Retry later
9102	Quota exceeded	Contact support

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.