| name | aso-keyword-research |
| description | App Store Optimization keyword research using the public iTunes Search API. Computes keyword popularity (5-100) and difficulty (1-100) scores based on RespectASO algorithms. Use when the user asks to research ASO keywords, find keyword opportunities, check keyword difficulty, analyze App Store competition, optimize App Store keywords, or find sweet spot keywords. Triggers on "ASO", "keyword research", "keyword difficulty", "keyword popularity", "App Store keywords", "App Store optimization keywords". |
ASO Keyword Research
Compute App Store keyword popularity and difficulty scores using the public iTunes Search API (no API key needed).
Quick Start
python3 scripts/aso_research.py "seed oil" --country us
python3 scripts/aso_research.py --batch "seed oil,allergen,food dye,preservative" --country us
Output
Each keyword returns:
- popularity (5-100): Estimated search volume based on competitor landscape
- difficulty (1-100): How hard it is to rank for this keyword
- verdict: SWEET SPOT / HIGH COMPETITION / HIDDEN GEM / AVOID
- top_5_apps: Top competing apps with review counts and ratings
Arthur's Golden Ratio
From the ASO Playbook: target keywords with popularity > 20 and difficulty < 50.
| Verdict | Popularity | Difficulty | Action |
|---|
| SWEET SPOT | >= 20 | < 50 | Target these |
| HIDDEN GEM | < 20 | < 50 | Use if relevant, low volume |
| HIGH COMPETITION | >= 20 | >= 50 | Avoid unless you have traction |
| AVOID | < 20 | >= 50 | Skip entirely |
ASO Rules (from Arthur's Playbook)
- Never repeat keywords across title, subtitle, and keyword field
- Use singular forms only (Apple handles plurals)
- Keyword field is 100 characters max, comma-separated
- Check both popularity AND revenue of top 5 apps (avoid vanity keywords)
- Iterate keywords weekly (scores shift over time)
Country Codes
Common: us, gb, de, fr, br, jp, kr, no, se, dk, es, it, au, ca
How Scores Are Computed
Based on the open-source RespectASO project (AGPL-3.0). Both scores are derived entirely from iTunes Search API results (25 competitor apps per keyword).
Popularity uses 6 signals: result count, leader strength (top app reviews), title match density, market depth (median reviews), keyword specificity penalty (multi-word penalty), exact phrase match bonus.
Difficulty uses 7 weighted factors: rating volume (30%), dominant players (20%), review velocity (10%), rating quality (10%), market age (10%), publisher diversity (10%), title relevance (10%). Post-processing applies caps for small result sets and weak leaders.
Rate Limiting
The iTunes Search API has no authentication but rate limits apply. The script sleeps 2 seconds between requests. For batch analysis of 10+ keywords, expect ~20-30 seconds.
