amz-hot-keywords

从 AMZ123 抓取亚马逊品牌分析(ABA)周热搜词排名数据,输出包含关键词、本周排名、上周排名及趋势(上升/下降/持平)的结构化 CSV 文件,快速掌握搜索热度变化。

SKILL.md

GitHub

Amazon 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:

  1. Navigate to AMZ123's US top keywords page with keyword search
  2. Wait 20s for Nuxt SSR + async API data to populate window.__NUXT__
  3. Scroll to trigger virtual-scroll table rendering
  4. Extract rendered DOM rows inside the real browser through browser.evaluate(...)
  5. Fall back to document.body.innerText + Python regex when DOM row extraction fails
  6. 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:

  1. BrowserWorker_PORT
  2. MANAI_BROWSER_CONTROL_PORT
  3. BrowserWorker_LOCK_FILE
  4. MANAI_WORKSPACE_ROOT/MANAI_HOME + storage/browser_daemon.lock
  5. legacy ~/.BrowserWorker/BrowserWorker.lock
  6. 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.