amz-hot-keywords
从 AMZ123 抓取亚马逊品牌分析(ABA)周热搜词排名数据,输出包含关键词、本周排名、上周排名及趋势(上升/下降/持平)的结构化 CSV 文件,快速掌握搜索热度变化。
SKILL.mdskills/amz-hot-keywords/SKILL.md
GitHubAmazon Hot Keywords Scraper
Scrape ABA weekly search term rankings from AMZ123 for any keyword. Outputs structured CSV data with search term, current week rank, last week rank, and trend direction.
How It Works
AMZ123 is now a Nuxt.js SPA (since ~2025). The scraper uses the BrowserWorker daemon + Chrome extension plugin transport to:
- Navigate to AMZ123's US top keywords page with keyword search
- Wait 20s for Nuxt SSR + async API data to populate
window.__NUXT__ - Scroll to trigger virtual-scroll table rendering
- Extract rendered DOM rows inside the real browser through
browser.evaluate(...) - Fall back to
document.body.innerText+ Python regex when DOM row extraction fails - Calculate trend (up/down/flat/new) and save as timestamped CSV
The skill must not use the old Chrome/CDP attach flow. Browser control goes through BrowserWorker /execute with action_search_path=<skill>/scripts/actions.
Usage
Run the scraper script with the target keyword:
python <SKILL_DIR>/scripts/amz_scraper.py --keyword "women shoes"
Parameters
| Parameter | Required | Description | Example |
|---|---|---|---|
--keyword |
Yes | Search keyword (MUST be English for US site) | --keyword "women shoes" |
--max-results |
No | Max results to scrape (default: 200) | --max-results 100 |
--output-dir |
No | Output directory for CSV (default: current dir) | --output-dir ./data |
Output
The script produces a CSV file named amz123_hotwords_<keyword>_<timestamp>.csv:
| Column | Description |
|---|---|
| search_term | The keyword/search term |
| current_rank | This week's ranking position |
| last_rank | Last week's ranking position |
| trend | Calculated direction: up / down / flat / new |
Trend logic: rank number decreasing = rising popularity ("up"), rank number increasing = falling popularity ("down"), same = "flat", no previous rank = "new".
Pitfalls & Troubleshooting
1. Chinese Keywords Return 0 Results
Chinese keywords on the US site always return 0 results. AMZ123 US scrapes Amazon.com (English marketplace). Always convert to English:
| Chinese | English |
|---|---|
| 女鞋 | women shoes |
| 运动鞋 | sneakers |
| 瑜伽垫 | yoga mat |
| 手机壳 | phone case |
2. BrowserWorker HTTP Unavailable
The script uses Python stdlib urllib to POST to BrowserWorker /execute. Port discovery order:
BrowserWorker_PORTMANAI_BROWSER_CONTROL_PORTBrowserWorker_LOCK_FILEMANAI_WORKSPACE_ROOT/MANAI_HOME+storage/browser_daemon.lock- legacy
~/.BrowserWorker/BrowserWorker.lock - default
12321
If the daemon is down, the script attempts to start project-local BrowserWorker with --transport auto. Do not switch to CDP or direct Chrome control unless the user explicitly asks for CDP debugging.
3. Table Not Rendering (Timeout)
AMZ123 uses Nuxt.js with virtual scrolling. The table only renders after:
- API data loads into
window.__NUXT__.state - User scrolls (IntersectionObserver triggers render)
The current approach handles this with: 20s wait → scroll 800px → 3s wait → extract innerText. If this fails, increase wait time or try the Nuxt state extraction method below.
4. Nuxt State Extraction (Alternative)
When text extraction fails, extract directly from Nuxt SSR state in the browser:
const nuxt = window.__NUXT__;
const keys = Object.keys(nuxt.state).filter(k => k.includes('word'));
const data = nuxt.state[keys[0]]; // Contains { rows: [...], total: N }
Runtime Requirements
- Python 3.9+
- Project-local BrowserWorker daemon and extension
- No Playwright, Selenium, ChromeDriver, pandas, or beautifulsoup4 dependency is required by this skill
Data Source
AMZ123 US Top Keywords - sourced from Amazon Brand Analytics (ABA) weekly reports covering ~250,000 search terms.