A standard-library Python tool that ranks candidate keywords by rising search demand, then rejects the ones whose category is too entrenched, separately for consumer (B2C) and bulk (B2B) selling on Amazon India.
Open-Source Tools · How-To · Misc analysis
How to use amazon-product-selector: a gated shortlist of rising Amazon keywords you can actually enter
Revised
· v1.0.0 · what changed
Code: github.com/herrrickshaw/amazon-product-selector
Watch the walkthrough
Watch on YouTube: youtu.be/0bw4HayV4HU
Why it is useful
- Sellers who pick products by looking at the biggest category end up fighting incumbents; this tool asks two questions first, is demand rising and can a newcomer get in.
- Pass/fail gates run before ranking and every rejection records its reason, so you learn why a keyword failed (flat trend, price below the B2B floor) instead of just seeing a lower score.
- B2C and B2B run as separate analyses with their own search terms and thresholds, and the comparison shows terms that are open on only one side.
- Evidence from the run: 162 tests passed, and the offline dry run shortlisted 3 of 4 keywords for B2C and 2 of 4 for B2B with reasons for each rejection.
What it is for
The tool takes a list of candidate keywords, reads a weekly search-volume trend and a snapshot of competing listings, and writes a ranked shortlist plus a rejected list with reasons. India (amazon.in, INR) is the default marketplace.
The offline --dry-run mode uses built-in fixture data and makes no network call, so you can see the whole pipeline and report format before paying for any data API. This post ran only that mode; live runs need two third-party API keys and were not run.
Who it is for
- Small sellers and category analysts screening a long keyword list before spending on inventory
- Anyone who wants a transparent gate-then-rank method they can edit (thresholds live in one MARKETS table)
- Guaranteeing a product will sell: the volume scales for India are estimates and nothing is calibrated against observed data
- Reading an individual shopper's search history (no such API exists)
- Anyone expecting the dry-run numbers to describe the real market: they are fixtures
What you need
| Requirement | Why | How to get it |
|---|---|---|
| Python 3.11+ | runtime code uses only the standard library | python.org or your package manager |
| pytest | only for the test suite | pip install -r requirements.txt |
| NEXSCOPE_API_KEY and OPENWEB_NINJA_API_KEY | live trend and competition data (not needed for --dry-run) | sign up with those providers; paid plans may apply; not run here |
Get the code and an AI assistant
You do not have to be a programmer. Get the repository, give it to an AI assistant, and ask in plain language. Any of these routes works:
| Tool | What you need | Best for |
|---|---|---|
| GitHub | Free account to fork or star; git to clone, or the green Code button, then Download ZIP, or open in Codespaces | Getting the code and keeping up with updates |
| Claude Code | Claude subscription or API key; run claude inside the cloned folder | Letting the AI read and run the whole repo |
| Gemini CLI | Google account; run gemini inside the cloned folder | The same hands-on workflow with Gemini |
| Claude.ai, Gemini or ChatGPT in the browser | A chat account; upload README.md and the files you care about (or paste the output of git ls-files) | Understanding the project and asking questions without installing anything |
| Other tools (Copilot Chat, Cursor, Codex CLI) | Open the cloned folder in the tool and point it at README.md first | Editing and extending the code |
git clone https://github.com/herrrickshaw/amazon-product-selector.git
cd amazon-product-selector
claude # or: geminiInstall
- Clone and install the test dependency.
git clone https://github.com/herrrickshaw/amazon-product-selector.git cd amazon-product-selector pip install -r requirements.txt
Quick start: commands and what you should see
Offline demo, no keys, no network
python3 amazon_selector/shortlist.py --dry-runPrints a B2C section, a B2B section and a B2C-vs-B2B comparison, then lists the report files it wrote under reports/.
Run the tests
python3 -m pytest -q162 passed, 2 skipped on the demo run.
Live run on the India universe (needs keys)
export NEXSCOPE_API_KEY=... NEXSCOPE_PROXY_BASE=https://api.nexscope.ai/
export OPENWEB_NINJA_API_KEY=...
python3 amazon_selector/shortlist.py --keywords-file candidates_in.txt --profile bothNot run for this post. Cached responses expire (24h competition, 168h trend).
Sample outputs
Real output from a run on the date shown in the sources line; trimmed to fit.
B2C shortlist and rejection (dry run, fixture data)
python3 amazon_selector/shortlist.py --dry-run
=== B2C — consumer retail · IN (INR) ===
--- shortlist (3 of 4) ---
1. giloy juice score 0.789 (growth 0.50 demand 0.93 openness 0.94 headroom 1.00)
2. aloe vera gel score 0.445 (growth 0.50 demand 1.00 openness 0.07 headroom 0.00)
3. moringa oil score 0.375 (growth 0.50 demand 0.00 openness 0.50 headroom 0.50)
--- rejected (1) ---
chyawanprash trend is 'flat', not in ['RISING']Fixture keywords, not market data.
B2B gates and the comparison
python3 amazon_selector/shortlist.py --dry-run
--- rejected (2) ---
aloe vera gel trend is 'flat', not in ['RISING']
moringa oil median price 18.99 below 2000
=== B2C vs B2B ===
shortlisted in both: giloy juice
B2C only: aloe vera gel, moringa oil
B2B only: chyawanprashThe B2B price floor is INR 2,000, so a cheap consumer item fails it.
Test suite
python3 -m pytest -q
162 passed, 2 skipped, 6 warnings in 5.30sWarnings include a deprecated datetime.utcfromtimestamp call.
Ways to use it
| Method | How it works |
|---|---|
| Screen a long list | Put your own keywords in a text file and pass --keywords-file. |
| Compare channels | Use --profile both and read the B2C-only and B2B-only lines. |
| Retune thresholds | Edit the MARKETS table after your first real run. |
Sample prompts for your AI assistant
Copy, paste and edit the parts in [brackets].
- Read README.md and explain the gate-then-rank method in plain language.
- Run the dry run and explain why chyawanprash is B2B-shortlisted with a 0.000 score.
- Help me write a candidates file of 30 keywords for my product niche.
- Explain the cache expiry settings and when to use --from-cache.
- Review the MARKETS thresholds and tell me which are estimates.
Limits and honest caveats
- Volume scales for India are estimates and uncalibrated, per the README.
- Observed quirk in the dry run: chyawanprash is B2B-shortlisted with every component score at 0.000, so shortlisted does not mean strong.
- Live mode depends on two third-party APIs whose terms and prices change; not run here.
- Dry-run data is fixture data and must not be read as a market finding.
- This is a research aid, not business or investment advice.
Sources: the amazon-product-selector README, docs/DATA_SOURCES.md and tests; --dry-run and pytest run on 19 October 2026 on a fresh clone in a scratch virtualenv. Live API mode not run.
- v1.0.0 — 19 October 2026 — first published.
About this article: Researched, written and edited by Umashankar Triplicane Dwarakanathan, with AI research assistance; every figure is meant to trace to the primary source cited. See the Editorial Policy for how sourcing, AI use and corrections work.
