aso-keyword-toolkit 0.1.0__tar.gz

aso_keyword_toolkit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gustavo Germano
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aso_keyword_toolkit-0.1.0/PKG-INFO

@@ -0,0 +1,495 @@
+Metadata-Version: 2.4
+Name: aso-keyword-toolkit
+Version: 0.1.0
+Summary: Free App Store keyword research and ASO metadata toolkit — per-storefront autocomplete data, competitor analysis, and App Store Connect sync. No subscription.
+Author: Gustavo Germano
+License: MIT
+Project-URL: Homepage, https://github.com/ggapp1/aso-keyword-toolkit
+Project-URL: Issues, https://github.com/ggapp1/aso-keyword-toolkit/issues
+Keywords: aso,app-store-optimization,keyword-research,app-store,app-store-connect,ios,aso-tools,mobile-marketing,itunes-search-api,app-store-keywords
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
+Classifier: Topic :: Software Development :: Localization
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: connect
+Requires-Dist: pyjwt>=2.0; extra == "connect"
+Requires-Dist: cryptography>=3.4; extra == "connect"
+Dynamic: license-file
+
+# ASO Keyword Toolkit — free App Store keyword research from the command line
+
+[![tests](https://github.com/ggapp1/aso-keyword-toolkit/actions/workflows/tests.yml/badge.svg)](https://github.com/ggapp1/aso-keyword-toolkit/actions/workflows/tests.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
+[![Zero dependencies](https://img.shields.io/badge/dependencies-none-brightgreen.svg)](pyproject.toml)
+
+**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.
+
+```bash
+pip install git+https://github.com/ggapp1/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](#what-the-numbers-mean).
+
+---
+
+## Installation
+
+Not on PyPI yet — install straight from GitHub:
+
+```bash
+pip install git+https://github.com/ggapp1/aso-keyword-toolkit
+```
+
+**pipx or uv** — if you want it as an isolated global tool:
+
+```bash
+pipx install git+https://github.com/ggapp1/aso-keyword-toolkit
+uv tool install git+https://github.com/ggapp1/aso-keyword-toolkit
+```
+
+**For development**, or if you want to read the code first:
+
+```bash
+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:
+
+```bash
+pip install "aso-keyword-toolkit[connect] @ git+https://github.com/ggapp1/aso-keyword-toolkit"
+```
+
+### Claude Code plugin
+
+The repo doubles as a [Claude Code](https://claude.com/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:
+
+```bash
+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:
+
+```bash
+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
+
+```bash
+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 |
+```
+
+| column | what it tells you |
+|--------|-------------------|
+| `pop` | autocomplete-derived ranking proxy — higher means Apple surfaces it sooner |
+| `ac-rank` | best position across every seed that surfaced it |
+| `seeds` | how many different seeds led to it (breadth of relevance) |
+| `comp` | competition tier 1–5, from median rating count of the top 5 apps |
+| `exact-title` | how many of the top 10 put this exact term in their title |
+| `our rank` | where your app currently sits, if it's in the top 50 |
+| `opp` | `pop + (5 - comp) * 2` — a sort key, not a verdict |
+
+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.
+
+### 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 `:`.
+
+---
+
+## 60 storefronts, every language
+
+```bash
+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.
+
+```bash
+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 word duplicated between name and subtitle
+- the same keyword listed twice
+- `a, b, c` spacing in the keyword field, which silently costs you characters
+
+This command needs no credentials, so it doubles as clean copy-paste output if
+you'd rather paste into the web UI.
+
+### Metadata rules worth knowing
+
+- Limits: **name 30, subtitle 30, keywords 100**, promotional text 170.
+- Never repeat a term across those three fields.
+- 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.
+
+---
+
+## 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:
+
+```bash
+export ASC_KEY_ID=XXXXXXXXXX
+export ASC_ISSUER_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+export ASC_PRIVATE_KEY_PATH=~/.appstoreconnect/AuthKey_XXXXXXXXXX.p8
+```
+
+```bash
+asokit metadata status                  # is a version editable right now?
+asokit metadata push de.json            # dry run — shows exactly what would change
+asokit metadata push de.json --apply    # write it
+```
+
+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 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
+
+| command | what it does |
+|---------|--------------|
+| `asokit init --app-id ID` | write a config with seeds derived from your live listing |
+| `asokit doctor` | check config, Apple connectivity, and credentials |
+| `asokit storefronts` | list all 60 storefronts |
+| `asokit storefronts --check de` | verify one storefront against the live endpoint |
+| `asokit research --market de` | expand and score keywords for one market |
+| `asokit research --all` | run every market in your config |
+| `asokit metadata check FILE` | validate limits and duplication |
+| `asokit metadata status` | show which version and locales are editable |
+| `asokit metadata push FILE` | dry-run the sync |
+| `asokit metadata push FILE --apply` | write metadata to App Store Connect |
+
+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`.
+
+**Why isn't it on PyPI?**
+It will be. Until then `pip install git+https://github.com/ggapp1/aso-keyword-toolkit`
+installs the same package and gives you the `asokit` command.
+
+---
+
+## How it works
+
+| source | what it provides | cost |
+|--------|------------------|------|
+| App Store autocomplete (`MZSearchHints`) | Apple's per-storefront suggestion ranking | free, no auth |
+| iTunes Search API | ranked apps per query per country, with rating counts | free, official |
+| App Store Connect API | reading and writing localized metadata | free, your own key |
+
+Nothing is proxied through a third party. Every request goes from your machine
+to Apple.
+
+---
+
+## Development
+
+```bash
+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), `asc` (App Store Connect), `report`
+(rendering), `suggest` (seed derivation).
+
+Contributions welcome — especially additional storefront verifications,
+stopwords for languages not yet covered, and app-name punctuation conventions
+from stores you know better than I do.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+Not affiliated with, endorsed by, or connected to Apple Inc. "App Store" and
+"App Store Connect" are trademarks of Apple Inc.