| name | aso-rank-monitor |
| description | Scheduled App Store rank tracking — run a keyword set on a cadence (weekly), append a dated snapshot to ranks.md, and report the delta vs. the previous run (↑/↓/new/lost). This is the automated tracker the paid tools (Astro, AppTweak) charge a subscription for, built on the free iTunes Search API. Use to watch whether a metadata change actually moved your rank over time, or to set up a recurring per-app rank check. Use when the user says "track my rank over time", "did my rank change since last week", "set up weekly rank tracking", "how did my rank move after the update", or "log a rank snapshot". |
aso-rank-monitor
The scheduled layer on top of aso-rank-check. Where rank-check is a one-shot
read, this runs on a cadence, keeps the time series in ranks.md, and tells you
what changed since last time — which is the whole point of rank tracking.
This is Astro / AppTweak's core product (weekly rank tracking + history + delta
alerts), with no subscription and no paid data: it's the free public iTunes
Search API plus a dated log in your repo, with git as the history.
Inputs
--app <slug> — names the log dir (marketing/aso/<app>/ranks.md).--bundle <id> — the app's bundle id (e.g. app.airowe.clarity).--keywords "a,b,c" — terms to track. Optional: if omitted, it reuses the
keyword set from the previous snapshot, so a scheduled run needs no arguments
once seeded.--country <US> · --root <repo> · --date <YYYY-MM-DD> (the snapshot date —
passed in, never read from a clock, so runs are reproducible).--json — emit the delta digest as JSON instead of writing ranks.md.
What it does
- Reads the latest snapshot block in
ranks.md to get the previous ranks.
- Runs
aso_rank_check for the keyword set (reusing the prior set if none given).
- Computes a delta per keyword:
↑ +N improved (rank number went down — lower is better)↓ -N dropped · new (was absent, now ranks) · lost (was ranking, gone)— unchanged · err (this term's fetch failed; the run still logs the rest)
- Appends a new dated block to
ranks.md and prints a one-line digest
(↑2, ↓1, new 1).
python3 lib/aso_rank_monitor.py \
--app heathen --bundle app.airowe.clarity --root . --date 2026-06-11
Run it on a schedule
Rank moves over weeks, so weekly is the right cadence. Two ways:
How it closes the loop
aso-keyword-research picks → aso-metadata-optimization ships → rank-monitor
watches. Feed the deltas back: a targeted keyword still lost/— after weeks
means the bet was too hard (demote it, reclaim the keyword-field chars); a
long-tail term trending ↑ is landing (consider promoting it toward the
subtitle). That feedback is what turns one-shot optimization into a loop.
Honest limits
Same as aso-rank-check: App Store only, the iTunes Search API's blended
relevance (weighs more than metadata alone), and a ~200-result ceiling beyond
which an app reads as —. A single snapshot is a starting line; the deltas
across snapshots are the signal.
No external dependency
Standard-library Python + the free public iTunes Search API. No paid ASO SaaS,
no key, no auth.
Want this to just happen? ShipASO — the hosted agent — runs the whole loop weekly: it tracks your rank, watches competitors, and pings you only when there's a real move to approve. Same engine, your store credentials never held. Monitoring is inherently recurring; the question is whether you remember to run it every week, forever. → https://app.shipaso.com
The plugin is complete and free; the hosted tier just sells not having to remember.
