Skill: pangolinfo/pangolinfo-amazon-niche (version 2.0.4)

--- name: pangolinfo-amazon-niche description: > 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". metadata: openclaw: emoji: "🎯" os: ["darwin", "linux"] requires: env: - PANGOLINFO_API_KEY - PANGOLINFO_EMAIL - PANGOLINFO_PASSWORD primaryEnv: PANGOLINFO_API_KEY bins: ["python3"] notes: "Set PANGOLINFO_API_KEY (recommended). Alternative: set PANGOLINFO_EMAIL + PANGOLINFO_PASSWORD instead (optional, for email/password login). Credentials are NOT cached to disk by default; disk persistence only activates with explicit --cache-key flag or PANGOLINFO_CACHE=1." tags: [amazon, amazon-niche, niche-finder, niche-research, category-research, category-tree, category-intelligence, product-opportunity, product-validation, low-competition, blue-ocean, ecommerce] homepage: https://pangolinfo.com/?referrer=clawhub_amz_niche version: 2.0.4 --- # 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: ```bash 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 ```bash python3 scripts/pangolinfo.py --api category-tree ``` 2. Resolve full category paths ```bash python3 scripts/pangolinfo.py --api category-paths --category-ids "2619526011,172282" ``` 3. Validate higher-conviction niche opportunities (costs 10 credits) ```bash 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](https://pangolinfo.com/?referrer=clawhub_niche) - **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 ```bash python3 scripts/pangolinfo.py --api category-search --keyword "yoga mat" ``` ## Intent-to-Command Mapping ### 1. Browse Category Tree (top-level) ```bash python3 scripts/pangolinfo.py --api category-tree ``` ### 2. Browse Children of a Specific Node ```bash python3 scripts/pangolinfo.py --api category-tree --parent-path "2619526011" ``` Nested nodes use `/`-joined paths: `--parent-path "2619526011/18116197011"`. ### 3. Search Categories by Keyword ```bash python3 scripts/pangolinfo.py --api category-search --keyword "yoga mat" ``` Matches both English and Chinese category names. ### 4. Batch Resolve Category Paths ```bash 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 ```bash python3 scripts/pangolinfo.py --api category-filter \ --marketplace-id US --time-range l7d --sample-scope all_asin ``` Single-category detail: ```bash 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`: ```bash 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 ```bash python3 scripts/pangolinfo.py --api niche-filter --marketplace-id US ``` Search by title: ```bash python3 scripts/pangolinfo.py --api niche-filter \ --marketplace-id US --niche-title "yoga mat" ``` With advanced range filters: ```bash 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` | -- | [REDACTED_SECRET] | 2 | | Category Search | `category-search` | `--keyword` | [REDACTED_SECRET] | 2 | | Category Paths | `category-paths` | `--category-ids` | [REDACTED_SECRET] | 2 | | Category Filter | `category-filter` | `--marketplace-id --time-range --sample-scope` | [REDACTED_SECRET] | 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 ```json { "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) ```json { "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](https://pangolinfo.com/?referrer=clawhub_niche) | | 2005 | No active plan | Subscribe at [pangolinfo.com](https://pangolinfo.com/?referrer=clawhub_niche) | | 2007 | Account expired | Renew at [pangolinfo.com](https://pangolinfo.com/?referrer=clawhub_niche) | | 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](references/setup-guide.md) for interactive setup instructions. Quick start: ```bash 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](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](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.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)