asokit is a small command-line tool (two direct dependencies) that tracks where your apps rank in App Store search for a set of keywords, across storefronts, over time. It stores each measurement locally in SQLite so you can watch keywords move up and down.
It's built for App Store Optimization (ASO) work: pick the keywords you care
about, run asokit run on a schedule, and see the trend — in the terminal or in
the built-in web dashboard (asokit serve).
$ asokit report --trend
KEYWORD POSITION TREND AS OF
calm #1 = 2026-11-06 12:12
meditation #3 ▲ 2 2026-11-06 12:12
sleep #4 ▼ 1 2026-11-06 12:12
asokit reads results from Apple's public iTunes Search API and records the position of your app for each keyword.
Important: the Search API returns a relevance ordering of apps. It is not the exact, personalized, ad-influenced ranking a user sees in the App Store app. Treat the position asokit reports as a ranking proxy — it is reliable for tracking movement over time for a keyword, but it is not an absolute "you are #N in the App Store" number. This is a deliberate trade-off: the Search API is free, needs no account, and works for any app.
Because fetches are capped at 200 results, "not in top results" means your app was not in the top 200 for that term — not that it is entirely unranked. A term that returns the full 200 is shown as "200+", since 200 is a ceiling, not a true total; a term returning fewer is a narrower, lower-competition term.
asokit does not report search volume or popularity. The only legitimate source for that is Apple Search Ads' popularity score, which is out of scope here. No column or field is a volume estimate.
On each run asokit also keeps the top results per keyword (configurable via
store_top, default 50) and derives two scores, stored per snapshot. They are
heuristics for comparing keywords and tracking change over time, not
official Apple data.
- Difficulty (0–100) — how contested a term looks, from its top-10
landscape. A weighted blend (defaults in
internal/metrics, overridable) of: the median rating count (log-scaled, weight 0.5), the share of top-10 titles that contain the term (0.3), and the median app age (0.2). Higher = harder. - Relevance (0–10) — how on-topic the term is for your app: how many of
the top 10 (excluding you) are the same type, i.e. share your App Store
category or carry one of your
title_terms. Higher = the top results are genuinely your category.
You can also list competitors and see their rank per keyword (derived from
the stored results, no extra requests). See asokit.example.yaml
for all fields. Title matching is Unicode-safe (Turkish dotted/dotless i, German
umlaut/ß, CJK).
Click any keyword on the dashboard to expand its detail: the current top 10 (with your app highlighted) and each competitor's rank over time.
Screenshots use the demo app Calm with neutral keywords.
Track more than one app from a single config and database. Each app keeps its own
markets (storefronts), keywords, competitors and relevance settings — and its own
history. The dashboard shows an app switcher (each app's icon and name) above
the market tabs; run sweeps every app, while report --app <id> and
export --app <id> focus on one. Old single-app configs (a top-level app_id
with markets:) are migrated automatically.
Each market can split its terms into two groups: keywords (single words like
calm) and phrases (multi-word searches like sleep sounds). They are
searched identically — both go to the same API call and get the same metrics;
the split only changes how they are grouped in the report and dashboard. The point
is readability and ASO strategy: single keywords are broad and contested, while
phrases are longer-tail — fewer rivals, clearer intent — so keeping them apart lets
you see at a glance where you fight for position and where you win easily. Moving a
term between the two groups never affects its metrics.
$ asokit report --competitors
KEYWORD POSITION DIFF REL RESULTS Headspace AS OF
meditation #3 80 9 200+ #2 2026-11-10 14:19
sleep sounds #7 77 9 188 — 2026-11-10 14:19
With Go 1.26+:
go install github.com/omervaroglu/asokit/cmd/asokit@latestOr build from source:
git clone https://github.com/omervaroglu/asokit
cd asokit
make build # produces ./asokit-
Create a config from the example:
cp asokit.example.yaml asokit.yaml
app_id: 571800810 # the "id" from the App Store URL (shared across markets) markets: - country: us # one entry per storefront, each with its own keywords keywords: - meditation - sleep - calm - country: de keywords: - meditation - schlaf
The same app is often marketed with different keywords per country/language, so each market (storefront) has its own keyword list and its own history. (Old single-market configs with a top-level
country:+keywords:are read and migrated automatically.) -
Take a measurement — this fetches each keyword and stores a snapshot:
asokit run
-
See the latest positions, or the movement since the previous run:
asokit report asokit report --trend
| Command | Description |
|---|---|
asokit run |
Fetch and store the current position for every keyword in config |
asokit once |
One-off lookup of a single term without touching the database |
asokit report |
Latest position per keyword, with difficulty/relevance/results columns (--trend for movement, --competitors for competitor ranks, --compare YYYY-MM-DD to diff against an earlier run, --country xx to pick a market) |
asokit export |
Export all stored snapshots as CSV, incl. difficulty/relevance/narrow (--out file.csv) |
asokit serve |
Serve the local web dashboard (default http://localhost:8080) |
asokit version |
Print the version |
Quick one-off without a config file:
asokit once --app-id 571800810 --country us "meditation"
# term="meditation" app=571800810 country=us -> #3 (of 192 results)--config(defaultasokit.yaml) — config path--db(defaultasokit.db) — SQLite database path--delay(default3s,runonly) — pause between keyword requests to stay friendly to the API. On throttling (HTTP 429/403) and transient failures (timeouts, HTTP 5xx) asokit backs off and retries, so one flaky request doesn't drop a keyword from the run.
You can run the whole thing from the browser — no config file editing, no
terminal commands after serve:
asokit serve # http://localhost:8080 (loopback only)
asokit serve --addr 127.0.0.1:9000 # custom portOn first launch, if there's no config yet, the dashboard opens a setup form:
enter the App Store ID, country and keywords, and Save (this writes
asokit.yaml). Then click Run now to fetch the current positions. Settings
reopens the form later. If you prefer the terminal, asokit run and a
hand-written asokit.yaml work exactly the same — they share one config file.
Multiple markets: the tabs at the top switch storefronts (TR · DE · …). + Market adds another country with its own keywords; each market keeps its own charts and history, so adding Germany never touches your Turkey data. "Run now" fetches the market you're viewing.
It's a single self-contained page (HTML/CSS/SVG, no build step, no external assets — everything is embedded in the binary). Each keyword gets a small "rank over time" chart with the current position, movement and the difficulty / relevance / results metrics; click a card for its top-10 and competitor sparklines. App version dates are drawn as dashed markers on the charts. A sortable Table view and light/dark themes are built in.
The server binds to loopback (
127.0.0.1) by default and writes files / makes outbound requests on your behalf — expose it beyond localhost only if you understand that.
Because asokit writes to a local SQLite file, you can run it from cron:
0 9 * * * cd /path/to/project && /usr/local/bin/asokit run >> asokit.log 2>&1A GitHub Actions workflow that runs daily and commits a CSV export is included
as a template at .github/workflows/track.yml
(disabled by default — enable the schedule trigger when you're ready).
make test # run tests
make lint # go vet + golangci-lint (if installed)
make build # build ./asokitMIT © Ömer Faruk Varoğlu

