ASO Keyword Toolkit — free App Store keyword research from the command line

App Store Optimization keyword research, competitor analysis, and App Store Connect metadata automation — for 60 countries, from your terminal, for free.

Find the keywords real users type in any App Store storefront. See who ranks for them and how beatable they are. Discover where your app is already winning and where it's invisible. Then write, validate, and publish localized metadata without touching the App Store Connect web UI.

pip install aso-keyword-toolkit
asokit init --app-id 1234567890 --markets de,fr,jp
asokit research --all

That's it. No account, no API key, no subscription, no trial. The research path uses two public Apple endpoints and has zero dependencies.

Why this exists

ASO tools start around $19/month and climb into the hundreds. A large part of what they sell is packaging of two Apple endpoints that are open to anyone: the App Store's autocomplete and the iTunes Search API. This gives you direct access to both, adds the analysis layer on top, and connects the result straight to the App Store Connect API so the whole loop runs from one command.

It is genuinely useful on its own, and it is also an honest floor: it will never invent a search-volume number that Apple does not publish. More on that in What the numbers mean.

Installation

pip install aso-keyword-toolkit

pipx or uv — if you want it as an isolated global tool:

pipx install aso-keyword-toolkit
uv tool install aso-keyword-toolkit

For development, or if you want to read the code first:

git clone https://github.com/ggapp1/aso-keyword-toolkit
cd aso-keyword-toolkit && pip install -e .

App Store Connect sync needs two extra libraries for JWT signing. Keyword research does not:

pip install "aso-keyword-toolkit[connect]"

Rendering App Store creatives (asokit assets render) also needs Pillow:

pip install "aso-keyword-toolkit[connect,render]"

Claude Code plugin

The repo doubles as a Claude Code plugin marketplace. Installing it gives your agent a six-phase ASO playbook with review gates, wired to this CLI:

/plugin marketplace add ggapp1/aso-keyword-toolkit
/plugin install aso-keyword-toolkit@aso-toolkit

The skill calls the asokit CLI, so install that too (above). Then ask Claude to research a market, or invoke the skill directly with /aso-keyword-toolkit:aso-localize. It runs the research, reads the report, drafts metadata that respects Apple's character and duplication rules, and stops for your review before anything is published.

Getting started in one command

If your app is already on the App Store, let the toolkit write your config:

asokit init --app-id 1234567890 --markets de,fr,jp

It reads your live listing, looks at the apps ranking alongside you, and derives starter seed keywords from what those apps actually call themselves:

reading your listing in the US store...
  Budget Expense Tracker — Finance
looking at apps that rank alongside it (this takes a moment)...
  read 68 competitor listings

wrote asokit.json with 16 seeds and 3 market(s)

Suggested seeds:
  expense tracker
  budget planner
  money manager
  spending
  receipts
  savings
  ...

Your app ID is the number in your App Store URL (apps.apple.com/app/id1234567890). Starting from scratch instead? asokit init writes a template you can fill in by hand.

Check everything is ready before a long run:

asokit doctor

config      asokit.json — 3 market(s)
apple api   reachable — 10 suggestions for a test query
connect     not configured (only needed to push metadata)

ready

App Store keyword research

asokit research --market de

Every seed goes through the App Store's autocomplete for that specific storefront, harvesting what Apple suggests to users in that country. Every candidate is then scored against the top 50 ranked apps there.

Real output from the German App Store, tracking a budgeting app:

| # | keyword                    | pop | ac-rank | seeds | comp | median top-5 ratings | exact-title | our rank | opp |
|---|----------------------------|-----|---------|-------|------|----------------------|-------------|----------|-----|
| 1 | kostenkontrolle            |  10 |       1 |     1 |    1 |                   23 |           1 |        — |  18 |
| 2 | savings goals              |  10 |       1 |     1 |    2 |                  240 |           1 |        — |  16 |
| 3 | ausgaben tracker           |  11 |       1 |     2 |    3 |                2,697 |           1 |        1 |  15 |
| 4 | geld sparen                |  11 |       1 |     2 |    3 |                1,899 |           1 |       13 |  15 |
| 5 | haushaltsbuch              |   9 |       2 |     1 |    3 |                8,592 |           8 |        1 |  13 |

A term at comp 1 whose top-5 apps have two dozen ratings is a real opening. A term at comp 5 belongs to someone with a marketing budget.

Each run also prints the headline takeaways so you don't have to read the whole table:

aso/de/report.md
  least contested:  kostenkontrolle, savings goals
  you already rank: ausgaben tracker (#1), haushaltsbuch kostenlos (#1), budget planner (#2)
  winnable gaps:    kostenkontrolle, savings goals

Responses are cached on disk, so re-running the same market weeks later to measure whether your changes worked costs almost nothing.

After a multi-market run, asokit digest prints every market in one block — the top targetable terms by opportunity, what you already rank for, and the off-category terms to ignore — which is the view you want open while writing metadata for many locales. It reads the scores.json files; no network.

Competitor analysis

Every report ends with the apps that kept appearing across your queries. A rival's title is their keyword strategy, stated publicly:

| app                            | ratings | top-5 appearances | best rank |
|--------------------------------|---------|-------------------|-----------|
| Ausgaben Budget Planner Fleur  |   1,899 |                20 |         1 |
| Monefy: Ausgaben manager       |   4,710 |                18 |         2 |
| Haushaltsbuch MoneyStats       |  22,435 |                18 |         2 |

Autocomplete mixes competitor app names in with genuine queries, which quietly corrupts keyword research. Those are detected and listed separately rather than scored as opportunities — including in Japanese and Chinese listings, which join name and tagline with ・ and ： instead of :.

Off-category detection

Some terms score beautifully and belong to somebody else entirely. Searching moodle in the US store looks like a strong lead for a mood app; it returns Education software. tracker detect returns AirTag finders. self-help credit union returns a bank.

When your config has an appId, the toolkit reads your App Store category and compares it against the apps actually ranking for each term. Anything answered by a different category is moved to its own section:

| term                   | pop | comp | who actually ranks |
|------------------------|-----|------|--------------------|
| moodle                 |  10 |    1 | Education          |
| self-help credit union |   9 |    5 | Finance            |

Real output — both scored well enough to top the list for a health app, and neither is worth a character.

60 storefronts, every language

asokit storefronts              # list all of them
asokit storefronts --check jp   # verify one against the live endpoint

Japan (jp) header=143462-4,29
  suggestions for '家計簿': 家計簿, 家計簿アプリ, 家計簿 無料 人気, 家計簿 レシート, 家計簿 共有

Country selection uses the X-Apple-Store-Front header. The cc= query parameter you'll find in older blog posts does not work — Apple accepts it and silently returns US results, which is an excellent way to ship a German keyword set built entirely from American data. This toolkit gets it right and gives you --check to prove it.

Non-Latin scripts, accents, and compound-word languages are first-class. Diacritics matter more than people expect: in the Spanish App Store, credito and crédito return different suggestion sets.

ASO metadata validation

The most expensive mistake in App Store metadata is repetition. Apple indexes your app name, subtitle, and keyword field as a single pool and combines words across them. Repeating a term you already used buys nothing and burns part of a 100-character budget you can't extend.

asokit metadata check de.json

--- name (26/30) ---
Budgeteer: Expense Tracker

--- subtitle (24/30) ---
Haushaltsbuch & Finanzen

--- keywords (71/100) ---
budgetplaner,ausgaben,sparen,kostenkontrolle,quittungen,einnahmen,konto

All fields within limits. No repetition across name, subtitle and keywords.

It catches what actually goes wrong:

• fields over the 30 / 30 / 100 character limits
• a keyword that already appears in your name or subtitle
• a keyword that shares a stem with one — track versus tracker
• a word duplicated between name and subtitle
• the same keyword listed twice
• a, b, c spacing in the keyword field, which silently costs you characters
• a localization with no description, which blocks submission outright

That last one is the trap in a research-driven workflow: you localize name, subtitle and keywords from research data and leave the long-form copy alone. App Store Connect does not fall back to your primary locale for the fields you skip — it stores them empty, and an empty description means the version cannot be submitted. Nothing surfaces that until submission fails. Use --allow-partial when you are deliberately updating a subset of fields on a locale whose description is already live, and --strict to also require release notes.

The same is true of the support and privacy-policy URLs: a new localization starts with both empty, and an empty one blocks submission. check cannot know what is already live, so it prints a note naming the locales whose file entry has neither; asokit metadata diff checks them against the live listing.

This command needs no credentials, so it doubles as clean copy-paste output if you'd rather paste into the web UI.

Stemming is per-language. Apple matches on stems, but morphology is not universal, and English suffix rules applied everywhere are worse than no stemming at all: they truncate German Zucker to zuck and Wasser to wass, inventing collisions between unrelated words while still missing the real German plurals, which are formed in -en and with umlaut. Rules exist for English, Spanish, Portuguese, Catalan, Galician, French and Dutch, plus the languages that mark no plural suffix at all (Japanese, Korean, Chinese, Thai, Vietnamese, Indonesian, Malay). Every other locale is compared as exact words, and metadata check prints a note naming them rather than letting a clean run read as a verdict on locales it never really checked.

Metadata rules worth knowing

• Limits: name 30, subtitle 30, keywords 100, promotional text 170.
• Never repeat a term across those three fields.
• Watch stems, not just words. Apple matches Track and Tracker as the same term, so a title saying "Tracker" makes a subtitle saying "Track" dead weight. metadata check catches these; exact-string comparison does not.
• No spaces after commas in the keyword field.
• Use singular forms — Apple handles plurals.
• Apple combines words across fields, so prefer distinct single words in the keyword field over repeating a phrase from your title.
• Compound-word languages (German, Dutch, Finnish) can't have compounds assembled from parts across fields, so each compound must appear whole. Budget for it: Haushaltsbuch costs 13 of your 30 subtitle characters.

Drafting the keyword field

Between a research report and a validated metadata file sits the step that is actually hard: packing terms into 100 characters without wasting budget.

asokit metadata pull > baseline.json          # capture what is live first
asokit metadata suggest --market de --baseline baseline.json

de -> de-DE  (38/100 characters)
  blutzucker,wasser,tracker,fodmap,hba1c
  dropped: competitor app-name fragments (balloon, uab, zuckerheld); stopwords (app, der, und)

It shows its work rather than presenting a field as magic. What it handles:

• Phrases become words. Apple combines words across fields, so listing stool tracker and poop tracker buys tracker twice.
• Stopwords. with, and, free eat characters and target nothing.
• Competitor brand fragments. looksLikeAppName filters whole terms, but splitting phrases into words leaks balloon, uab and inc out of rival app names — which is where trademark trouble starts.
• Scripts with combining marks. Tokenizing splits on separators rather than matching \w, because Python's \w excludes nonspacing marks and shreds Thai and Devanagari at every tone mark and matra. Scripts written without spaces deliberately stay one token; segmenting them properly needs a dictionary this tool does not have.
• Terms you already rank for. Live keywords from --baseline rejoin the pool at the lowest priority, so a hand-picked term that is already working is not discarded just because autocomplete never proposed it.

--block word,word is the escape hatch for junk no rule reaches — a beverage brand surfacing in health autocomplete is neither off-category by Apple's genre data nor an app name, but it is still not a keyword you want.

When the list differs by market, keep it in a file and pass --block-file blocklist.json. "*" applies everywhere, a language code to every locale of that language, a full locale code to that locale only; keys starting with _ are notes:

{"*": ["balloon"], "it": ["dell"], "fr-FR": ["map"], "_notes": {"map": "fragment of a rival's name"}}

Draft every market at once and validate the result:

asokit metadata suggest --all --baseline baseline.json --json --out draft.json
asokit metadata check draft.json
asokit metadata push draft.json          # dry run first

With --baseline, the draft carries the rest of each localization through unchanged and swaps only the keyword field, so what comes out is a complete, pushable file rather than a fragment. Without one you get keywords alone, which check will flag as unsubmittable — correctly, since a locale carrying keywords and no description is exactly the shape that cannot be submitted.

The output is a starting point, not an answer. Read it before you push it.

App Store Connect automation

Localized metadata is split across two different API resources and is only writable while a version sits in an editable state — the kind of detail that makes hand-rolling this annoying. The toolkit handles both, creates locales that don't exist yet, and dry-runs by default.

Create a key at App Store Connect → Users and Access → Integrations → App Store Connect API with the App Manager role:

export ASC_KEY_ID=XXXXXXXXXX
export ASC_ISSUER_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
export ASC_PRIVATE_KEY_PATH=~/.appstoreconnect/AuthKey_XXXXXXXXXX.p8

asokit metadata status                  # is a version editable right now?
asokit metadata pull > baseline.json    # capture the current listing FIRST
asokit metadata push de.json            # dry run — shows exactly what would change
asokit metadata push de.json --apply    # write it

See the change before you make it. asokit metadata diff de.json reads the live listing and prints, field by field, what the push would change — short values inline, long ones as changed lines — and names any locale that has no support or privacy URL in the file or live, which would block submission. It writes nothing.

Pull before you push. metadata pull emits the same {locale: {field: value}} shape that check and push consume, so push baseline.json is your undo. It is the cheapest safety step available and the only rollback path there is.

Validation runs before anything is sent, so a bad file fails locally rather than halfway through a batch. Credentials are read from the environment only; .p8 keys are gitignored by default.

A multi-locale push is re-runnable. Creating an appInfoLocalization makes App Store Connect auto-create the paired appStoreVersionLocalization, so the follow-up create collides with a resource that now exists; push adopts it and patches instead of aborting, and reports adopted rather than claiming it created something. Each locale is printed as it lands, flushed, so a redirected log is a live record — and if a run does fail partway, the output tells you exactly which locales were already written. Re-running converges.

asokit doctor also checks that your app is actually on sale in every market you configured. Researching a storefront nobody can buy in is an hour of wasted scoring, and assuming the opposite quietly drops markets you already sell in.

Subscriptions from one declarative file

Creating a subscription group, its subscriptions and their prices by hand is the part of setup that does not scale — and pricing is the worst of it. There is no endpoint that applies one price to every storefront: the documented path is one POST per territory, roughly 175 writes per subscription. products apply reads a file that describes the finished state and makes App Store Connect match it.

{
  "groups": [{
    "referenceName": "Pro",
    "localizations": {
      "en-US": {"name": "Pro"},
      "pt-BR": {"name": "Pro"}
    },
    "subscriptions": [{
      "productId": "com.example.pro.annual",
      "name": "Pro Annual",
      "subscriptionPeriod": "ONE_YEAR",
      "groupLevel": 1,
      "familySharable": false,
      "reviewNote": "Pro unlocks unlimited logging…",
      "availability": {"allTerritories": true},
      "price": {"baseTerritory": "USA", "customerPrice": "24.99"},
      "localizations": {
        "en-US": {
          "name": "Pro Annual",
          "description": "Unlimited logging, all year."
        }
      }
    }]
  }]
}

asokit products status                  # what exists in App Store Connect now
asokit products check products.json     # limits and structure, offline
asokit products apply products.json     # dry run — every action it would take
asokit products apply products.json --apply

It is a diff, not a script. Each run reads live state first and writes only what differs, so a second run against an unchanged file writes nothing — including the 175 price rows. That is the property that makes it safe to re-run after a partial failure.

A new subscription is put on sale before it is priced. App Store Connect rejects a price for a territory the subscription is not sold in (a 409, "An error occurred while processing the pricing information"), so availability is always written first.

Three things it will not do, each on purpose:

• Change what cannot be changed. productId and subscriptionPeriod are fixed at creation. If the file disagrees with a live product, the run stops and tells you, before anything is sent.
• Narrow where you sell. availability is required on every subscription, and must be {"allTerritories": true}. false is rejected rather than obeyed, because the file cannot express a smaller set — restrict territories by hand in App Store Connect instead. It is required rather than optional because a subscription provisioned without it comes out priced in every territory and on sale in none, and no later run repairs that.
• Finish the submission. Every new subscription lands in MISSING_METADATA until it has a review screenshot. Add those in App Store Connect, then submit the subscriptions alongside your next app version.

Text-only changes to products that already exist stay with products push, which keeps taking the flat {productId: {locale: {field: value}}} format.

App Store creatives, custom product pages and nominations

Everything below goes through Apple's App Store Asset Library: images are uploaded once to the app's library, then placed on a surface — the default product page's editable version, or a custom product page. Rendering creatives needs Pillow; everything that talks to App Store Connect needs the connect extra:

pip install 'aso-keyword-toolkit[connect,render]'

Every write command follows the same shape as metadata push: a dry run unless --apply, validation before anything is sent, and uploads finished before any surface is touched. Concretely:

• Uploads first, writes second. Every file in scope is uploaded (or reused) and processed before the first placement changes. A failure there leaves every live surface as it was.
• Identical bytes upload once. Files are matched by content hash. A copy App Review rejected blocks reuse of those exact bytes — change the image — unless an accepted or approved twin of the same bytes exists. FAILED placements are replaced, not kept.
• Group limits are checked before writing, so a run never stops halfway through a group because it ran out of slots.
• Nothing is ever deleted from the library, and no page is ever deleted. Only placements are removed, and page localizations only with --prune.

Rendering creatives from assets.json

assets render writes two files per locale:

• the universal image, exactly 5244 × 2950, which serves search results (and the header too, when no header file exists). The headline and one or two device captures sit inside the intersection of the 21:9 and 3:2 crops;
• a dedicated product-page header image, exactly 3840 × 1646.

Why two: App Store Connect previews (October 2026) show the universal image whole and uncropped in search results on iPhone and iPad, but the product-page header crops it hard — iPhone keeps only the centre ~53% of the width, iPad the full width but only the top ~55% of the height, iPhone Duo the centre ~65% — and the status bar, Dynamic Island, back/share buttons and iPad tab bar cover the top band and corners. A left-aligned headline gets cut on iPhone. The header file centres the headline in a zone every device shows (x 940–2900, y 380–1150 — inside the iPhone crop, about x 902–2938, with a margin) and puts one phone at each far side, fully outside the centre band (x 677–3163), so the iPhone crop shows a clean headline. Search keeps the universal file. assets.json lives next to asokit.json by default (--assets PATH points elsewhere):

{
  "canvas": {"width": 5244, "height": 2950},
  "safeInset": 0.03,
  "brand": {"background": "#4338CA", "text": "#FFFFFF", "frame": "#1C1C1E"},
  "fonts": {
    "default": {"path": "/Library/Fonts/SF-Pro-Display-Black.otf"},
    "ja": {"path": "/System/Library/Fonts/ヒラギノ角ゴシック W8.ttc", "index": 0},
    "ar-SA": {"path": "/System/Library/Fonts/SFArabic.ttf", "variation": "Bold"}
  },
  "noSpaceWrap": ["ja", "zh-Hans", "zh-Hant"],
  "rtl": ["ar-SA", "he"],
  "type": {"verb": {"size": 360, "min": 220, "step": 10, "lines": 2, "leading": 1.02},
           "descriptor": {"size": 220, "min": 150, "step": 6, "lines": 2, "leading": 1.12},
           "tight": {"verb": 260, "descriptor": 170}},
  "header": {"enabled": true, "canvas": {"width": 3840, "height": 1646},
             "zone": [940, 380, 2900, 1150], "centreBand": [677, 3163], "deviceTop": 200, "minDevice": 0.4,
             "type": {"verb": {"size": 260, "min": 150, "step": 10, "lines": 1, "leading": 1.02},
                      "descriptor": {"size": 130, "min": 80, "step": 6, "lines": 1, "leading": 1.12},
                      "tight": {"verb": 190, "descriptor": 100}}},
  "variants": {
    "default": {
      "captures": ["{ui}/01-log-home.png", "{ui}/03-stats-insights.png"],
      "capturesRoot": "screenshots/store/src",
      "headlines": {"from": "screenshots/store/headlines.json", "slot": "hero", "fallbackSlot": 0}
    },
    "bpd": {
      "captures": ["{ui}/06-add-entry-details.png", "{ui}/02-stats-patterns.png"],
      "capturesRoot": "screenshots/store/src",
      "headlines": {"en-US": ["LOG MOOD SWINGS", "Triggers, symptoms & patterns"], "en-GB": {"same": "en-US"}},
      "ui": "en"
    }
  }
}

type is optional; the values shown are the defaults. Overrides merge per key, so {"verb": {"size": 400}} changes the size and keeps the rest. Fonts are keyed by locale with default covering the rest.

header is optional too; the values shown are the defaults, and its type merges the same way (the top-level type applies only to the universal file). The header uses the same brand colours, fonts, headline sources and lint as the universal file. Its headline is centred in zone — verb on one line, descriptor on one line. Each phone is centred in the space outside centreBand, at or below deviceTop, and may run off the bottom edge. Phones shorter than minDevice × the canvas height are dropped rather than drawn too small to read. The left phone shows the first capture and the right phone the second, or the first again when there is only one; RTL locales swap them. When a side is too narrow for a legible phone, the header has no phones and the report says header-no-devices — phones and their shadows never enter the band. canvas must stay 3840 × 1646 for anything you upload: assets push and cpp check/cpp push reject a header file of any other size (that is the size Apple's catalog accepts for the header placement). Change it only for experiments. "header": {"enabled": false} renders the universal file only (and removes a header file left over from an earlier render, so it can't be placed by mistake).

Headlines come either inline ([verb, descriptor] or {"same": locale}) or from a headlines file via from, where slot is an index or a named slot and fallbackSlot covers locales that lack it. A named slot that some locales have and others don't falls back per locale, and the report flags each fallback; a slot name that is in neither the file's _slots nor on any locale — a typo like "heor" — is an error, not a silent fallback for every locale. The same goes for a misspelt fallbackSlot.

Right-to-left layout is per locale. Inline headlines are drawn RTL only when their locale is in the top-level rtl list; headlines read from a file use that locale entry's own "rtl": true.

asokit assets render                          # every variant, every locale it can resolve
asokit assets render --variant bpd --locales en-US,en-GB

Output goes to assets-out/<variant>/<locale>.png and assets-out/<variant>/header/<locale>.png (change the root with --out), plus contact sheets per variant at assets-out/_contact/<variant>.png and assets-out/_contact/<variant>-header.png. Review them before uploading anything. The report flags TIGHT and header-TIGHT locales whose type had to shrink below the tight thresholds, locales that used the fallback headline, and header-no-devices.

A locale that can't be rendered properly fails on its own. If its text won't fit the safe box (or the header zone) at the minimum size and line count, its headline fails the lint, or its font has no glyph for a character in the headline, that locale is reported, and its old universal and header files are both deleted (so a stale image can't be uploaded by mistake). The other locales still render.

The glyph check exists because Pillow draws a font's placeholder box for a missing character and reports success. It is easy to hit: SF Hebrew and SF Arabic have no Latin comma, so "הרגל, יום אחר יום" renders with a striped block where the comma should be. Reword the headline, or point fonts.<locale> at a font that covers it. The lint catches what App Review rejects on creatives: prices and offers, URLs, rank and award claims, other platforms, medical claims — including third-person ones such as "detects", "predicts", "diagnoses", "cures". Languages without a word list get a warning, which --strict-lint turns into an error; --no-lint skips it. Right-to-left locales need Pillow built with libraqm; without it, a variant with any RTL locale in scope stops before drawing anything — the whole variant, not just that locale.

The files must be 8-bit RGB PNGs (colour type 2) with no alpha channel and no tRNS chunk, at exactly 5244 × 2950 (universal) or 3840 × 1646 (header). Rendered output already is; files you export from a design tool are checked the same way before upload.

Placing creatives

asokit assets status                          # library, asset states, header/search placements
asokit assets status --catalog                # Apple's placement and spec catalog
asokit assets push assets-out/default --target default           # dry run
asokit assets push assets-out/default --target default --apply   # header + search asset
asokit assets push assets-out/bpd --target "cpp:BPD tracker" --apply
asokit assets submit assets-out/default --apply                  # review them on their own

push reads DIR/<locale>.png and, when it exists, DIR/header/<locale>.png. With a header file, the header file goes to the product-page header placement and the universal file to the search-results placement (uploaded as header-<locale>.png and <locale>.png). Without one, the universal file goes to both placements, as before. A header file with no universal file beside it is a validation error. --target default writes to the editable App Store version — the asset ships with your next release; --target cpp:<name> writes to a custom product page that already has an editable version (run cpp push first — assets push never creates page versions). Pushes to the default page refuse while a product page optimization test is running.

assets submit sends the uploaded creatives to App Review by themselves, placing nothing, so they can be approved ahead of the version they will ride with. It runs a read-only preflight before uploading anything and skips assets already in or past review. Header files are submitted with them.

Custom product pages from cpp.json

Custom product pages can now be assigned keywords, which makes them show up in organic search as well as in Apple Ads. cpp.json describes the pages you want; cpp push makes App Store Connect match it. Like assets.json, it is read from next to asokit.json unless --file PATH says otherwise.

{
  "protectedKeywords": {"*": ["cyclothymia", "depression", "hypomania", "mania", "episode"]},
  "pages": [
    {
      "name": "BPD tracker",
      "deepLink": null,
      "template": "appStoreVersion",
      "locales": {
        "en-US": {
          "promotionalText": "…",
          "keywords": ["bpd", "borderline"],
          "screenshots": [
            {"dir": "screenshots/store/out/en-US", "order": ["06", "02", "03", "01"], "display": "APP_IPHONE_67"}
          ],
          "creative": "bpd"
        },
        "en-GB": {"same": "en-US", "keywords": ["bpd", "borderline"]}
      }
    }
  ]
}

• name is the join key with live pages: unique and at most 30 characters.
• template: "appStoreVersion" starts the page from your current version, so every device family inherits the default screenshots and screenshots only replaces the families it lists. Without a template, every family the live version has must be listed.
• screenshots[].order picks and orders files by name prefix; creative names a rendered variant, read from <creative-root>/<variant>/<locale>.png (--creative-root, default assets-out). When <creative-root>/<variant>/header/<locale>.png exists, it becomes the header placement and the universal file serves search only. cpp check validates its size, and cpp push compares each placement against its own file, so changing only the header resyncs the media (or opens a new version on a live page).
• same copies promotionalText, screenshots and creative — never keywords (deepLink is set once per page, not per locale). Keyword pools differ by locale, so keywords are always explicit.
• There is no visible field on purpose. Visibility changes only through cpp publish.

Keyword rules. cpp check enforces two rules that are stricter than Apple's:

• Ownership: within a locale, a keyword belongs to at most one page — counting live pages that aren't in your file. Pages with no keywords are fine. Every keyword must also be in that locale's keyword field on the latest approved version; one missing from the editable version is a warning, because the page stops ranking for it when that version ships.
• Protected keywords: anything in protectedKeywords["*"] or protectedKeywords["<locale>"] is an error unless named with --allow-protected kw1,kw2. Use it for the terms your default page has to keep winning.

The lifecycle is four explicit steps. For a new page, organic routing changes only at the last one. The one exception is a page you have already published — see Live below:

asokit cpp check                                   # offline + online validation
asokit cpp push --apply                            # pages created HIDDEN
asokit cpp submit --pages "BPD tracker" --apply    # send to App Review
asokit cpp publish --pages "BPD tracker" --apply   # after approval: visible, routing goes live
asokit cpp publish --pages "BPD tracker" --hide --apply

What cpp push does to a page depends on its state:

• Missing — created hidden, with its localizations, keywords, screenshots and creative.
• Live — promotional text and keyword changes are edited in place on the live version, with no new version and no review. On a page that is already visible (published), that means they take effect at push: keyword edits reroute organic search immediately and new promotional text is shown immediately. Push refuses keyword edits on a visible, live page unless you pass --allow-live-routing; the dry run labels such actions VISIBLE — routing changes now, and the summary names every page whose routing changed. On a hidden page the same edits change nothing until you publish. Screenshot, creative or deep-link changes open a new version for review.
• Visible but never approved — a page that is visible with no approved version (a lost create response or a failed hide) is hidden first, before anything else in the run, so approval can't start routing on its own.
• In review — skipped until review finishes.
• Unchanged — nothing is written; a second push is a no-op.

Across all pages in a run, keyword removals happen before additions, so moving a keyword from one page to another never trips ownership. --pages and --locales scope a push; --locales never deletes anything. With --pages, a page outside the scope keeps its live keywords, so moving a keyword from page A to page B needs both in scope (--pages A,B); cpp check --pages B reports the same problem. --prune deletes page localizations missing from the file, but never a page's last localization.

cpp submit and cpp publish require --pages and validate every named page before doing anything. submit refuses if a locale or device family declared in the file isn't actually placed on the page (a declared creative needs both its header and search placement), refuses a new version of a live page that would drop a locale, a screenshot display class, or a header/search placement the live version has (approval replaces the live version whole), refuses a page that is visible but has never been approved (hide it with cpp publish --pages NAME --hide --apply), and won't add pages to a draft submission that already holds something else, such as your app version. publish refuses pages that aren't approved.

--ads-export ads-groups.csv on cpp status or cpp push writes one row per page and locale — page id, URL, visibility, state, keywords, deep link — for building matching Apple Ads ad groups. After --apply it re-reads the live pages, so the CSV has the ids of pages the run just created.

Featuring nominations from nominations.json

{
  "nominations": [
    {
      "name": "MoodSync — new product page & localizations",
      "type": "APP_ENHANCEMENTS",
      "description": "…",
      "publishStartDate": "2026-11-16",
      "deviceFamilies": ["IPHONE", "IPAD"],
      "locales": ["en-US", "de-DE", "fr-FR"],
      "notes": "…",
      "supplementalMaterialsUris": []
    }
  ]
}

asokit nominations check                              # offline validation
asokit nominations push --apply                       # create or update DRAFTS
asokit nominations push --submit --name "MoodSync — new product page & localizations" --apply

nominations.json is read from next to asokit.json unless --file PATH says otherwise. name, type, description and publishStartDate are required; name is at most 60 characters and description at most 1000. type is APP_LAUNCH, APP_ENHANCEMENTS or NEW_CONTENT. Dates are YYYY-MM-DD, and publishStartDate must be at least 14 days out — Apple's recommended notice — unless --force. relatedApps defaults to the app in asokit.json; if you set it, it must include that app.

push matches nominations by name: missing ones are created as drafts, drafts that differ are updated, submitted ones are left alone. If two nominations in App Store Connect already share a name, push refuses rather than guess which one you meant. --submit --name N submits exactly that one, after every draft in the file has been written.

Screenshots

screenshots push DIR replaces the screenshot sets of the editable version from DIR/<locale>/*.png, files in name order:

asokit screenshots status                       # sets per locale on the editable version
asokit screenshots push out/                    # dry run: what would be deleted and uploaded
asokit screenshots push out/ --locales he,ar-SA --apply
asokit screenshots push out/ --mirror APP_IPAD_PRO_3GEN_129 --mirror-from en-US --apply

Pixel sizes and the ten-per-set limit are checked before anything is sent, and an applied run waits until Apple has processed every upload. --display names the display family of the PNGs (default APP_IPHONE_67); --mirror copies other families, such as the iPad set, from one locale into all the others. Only subfolders named like a locale (de, en-US, zh-Hans) are read — anything else in DIR, such as ipad-en-US or a contact-sheet folder, is skipped and listed.

Screenshots through the Asset Library

screenshots push keeps using the older screenshot-set API by default. The Asset Library engine is opt-in:

asokit screenshots status --engine library
asokit screenshots push out/ --engine library                      # dry run
asokit screenshots push out/ --engine library --mirror APP_IPAD_PRO_3GEN_129 --mirror-from en-US --apply

Same flags and the same validation, with two differences: it diffs, so an unchanged group isn't rewritten, and --mirror re-places the source locale's assets by id instead of downloading and re-uploading them. A mirrored display wins over local files for the same display.

The default switches to library in a later release, once two things hold: screenshots status prints identical output under both engines, and one full-locale --engine library push has been verified in App Store Connect.

The ledger

Every applied write appends one JSON line to asokit-ledger.jsonl, next to asokit.json — creates, placements, keyword changes, submissions, publishes, nominations. Dry runs write nothing.

{"action": "publish", "command": "cpp publish", "page_id": "…", "page_name": "BPD tracker", "ts": "2026-11-02T09:14:00Z", …}

Commit it with your app. App Analytics reports each custom product page separately (Acquisition, by product page), but it doesn't tell you when a page went live or when its keywords changed. The ledger does: filter Analytics from the publish timestamp for a page, and compare before and after an add_keywords line (which carries page_name and locale) for that page. Placement lines ("action": "place") are keyed by surface instead: they carry locale, surface (appStoreVersionLocalization for the default page, appCustomProductPageLocalization for a custom product page), parent_id (that localization's id), placement_type and group. Match them to a page by the command (cpp push, assets push), the locale and the timestamp of the same run's create_page/create_version lines, or look the parent_id up in App Store Connect. cpp status prints each page's last publish date from the ledger alongside its live state.

A worked example: budgeting apps in the German App Store

A real run — 16 seeds, 40 candidates scored — tracking one of the established German budgeting apps. Every number below came out of the tool.

It already owns the German expense vocabulary. Rank #1 for haushaltsbuch, ausgaben tracker, ausgaben tracker kostenlos, and haushaltsbuch kostenlos; #2 for expense tracker, budget planner, and budgetplaner. That's a defended position, and the first job of any metadata change is not to break it.

But it's invisible where the competition is weakest. kostenkontrolle scored competition tier 1 — the median top-5 app there has 23 ratings — and this app doesn't rank for it at all. Compare haushaltsbuch, where the median top-5 app has 8,592 ratings and eight of the top ten put the word directly in their title. Same category, wildly different economics.

The read: the contested compound is already won and should be protected. The cheap opening is the term nobody is fighting for.

The competitor table shows the strategy behind the rankings:

| Ausgaben Budget Planner Fleur  |   1,899 |                20 |         1 |
| Monefy: Ausgaben manager       |   4,710 |                18 |         2 |
| Haushaltsbuch MoneyStats       |  22,435 |                18 |         2 |

Three of the strongest apps put Ausgaben in their title. That isn't something you have to guess at — it's their keyword bet, published.

One thing the numbers alone would get wrong. In the US store, mint looks like an obvious budgeting keyword. The top result is Mint Mobile, a wireless carrier. Ranking there buys traffic from people shopping for a phone plan. A popularity score rates the query, not who answers it — which is exactly why every report shows you who currently ranks.

What the numbers mean

pop is a ranking proxy derived from Apple's own autocomplete ordering, not a search-volume estimate. Apple does not publish search volume through any free endpoint. Tools that show you "volume: 4,400/mo" from these sources are modelling, not measuring.

This matters practically. Autocomplete ordering is real signal — it is Apple telling you what people in that country type — and it is excellent for ranking candidates against each other. It cannot tell you a term's absolute traffic. Use it to narrow hundreds of candidates down to a handful, then validate those few against Apple Search Ads if you need absolute numbers.

Relevance stays a human judgment. The toolkit filters competitor app names out of your results, but no heuristic can tell you that a term in your category serves a different audience. That's what the competitor table is for — read it.

Command reference

Each research run writes report.md plus the raw scores.json and expansion.json, so you can build your own analysis on the data.

FAQ

Is this really free? Yes. Keyword research uses public Apple endpoints that need no account. Publishing metadata uses your own App Store Connect API key, which Apple issues free to developers. There is no hosted service and nothing to sign up for.

Do I need an Apple Search Ads account? No. Apple Search Ads is one way to get official popularity scores, but this toolkit doesn't require it and doesn't use it.

How is this different from paid ASO tools? Paid tools add Apple Search Ads popularity scores, historical rank tracking, and dashboards. This gives you the per-storefront keyword discovery, competitor analysis, and metadata publishing that most of the workflow actually consists of — scriptable, inspectable, and free. Many people need the second thing far more often than the first.

Does it work for Google Play? Not currently. Everything here is App Store specific: Apple's endpoints, the 30/30/100 character model, and the App Store Connect API.

Will Apple block this? These endpoints are public and used by the App Store itself. The toolkit sets a descriptive user agent, spaces requests to respect the iTunes Search API's roughly 20-requests-per-minute limit, and caches everything so repeat runs make almost no requests. Be reasonable and you'll be fine.

Can I use it in CI? Yes. Everything is non-interactive with meaningful exit codes — asokit metadata check fails the build on a validation error, which makes a good pre-submission gate.

What Python version do I need? 3.9 or newer, tested on 3.9, 3.11 and 3.13. Research has no dependencies at all; only App Store Connect sync adds pyjwt and cryptography, and rendering creatives adds Pillow.

How it works

Nothing is proxied through a third party. Every request goes from your machine to Apple.

Development

git clone https://github.com/ggapp1/aso-keyword-toolkit
cd aso-keyword-toolkit
pip install -e .
python3 -m unittest discover -s tests -t .

The codebase is small and deliberately boring: storefronts (the country table), sources (HTTP and caching), research (expansion and scoring), metadata (pure validation, no I/O), packing (keyword-field selection, also pure), asc (App Store Connect), report (rendering), suggest (seed derivation). The App Store Connect write paths follow the same split — pure modules plan, executors write: library (Asset Library uploads and placements), creative (creative file checks and lint, pure), render (creative rendering, optional Pillow), cpp (custom product page validation and planning, pure), cpp_apply (custom product page executor), review (review submissions), nominations (featuring nominations), ledger (the append-only write log).

Contributions welcome, and two tables in particular are built to be extended by people who know a language better than I do:

• metadata._RULES — stemming suffixes per language. Locales absent from it are compared as exact words, which under-reports repetition but never invents it. Adding a language is a few (suffix, replacement) pairs; the bar is that the rule must not truncate ordinary stems, which is what the old English-everywhere behaviour did to German.
• packing._LANGUAGE_FILLER — stopwords per language, applied only to Latin-script words. Under-filtering wastes a few characters; over-filtering deletes the keyword you were trying to rank for, so err toward leaving words in.

Storefront verifications and app-name punctuation conventions from stores you know better than I do are just as welcome.

License

MIT. See LICENSE.

Not affiliated with, endorsed by, or connected to Apple Inc. "App Store" and "App Store Connect" are trademarks of Apple Inc.