What is the home storefront?
The home storefront isapp.country, and it comes from the URL you imported. A URL such as apps.apple.com/de/app/... imports a de home market, and the import dialog lets you override it. A bare iTunes id, or a URL with no country segment, falls back to DEFAULT_COUNTRY, which defaults to us.
Country codes are two lowercase letters, and each one must be a storefront of the app’s store. See Which codes are storefronts?
The home storefront drives everything that asobeast stores once per app.
The iOS keyword field is kept once per App Store localization rather than per app or per market. See How does asobeast keep a keyword field per localization?
A keyword is judged against the listing its own storefront serves. See What is a market listing?
How does one search serve everyone?
A position check searcheskeyword.country, not app.country. From that single search asobeast records positions for the primary app and for every competitor attached to it in that storefront.
That is why adding a competitor costs no extra store requests. Ten competitors on a keyword are still one search.
What does a market cost?
The same phrase tracked inus and in pl is two keyword rows, checked by two searches. Markets multiply, keywords multiply, and both draw on the same fixed request budget.
Rankings, difficulty and popularity all differ per storefront, so the second market is real data rather than a copy.
Two places show you the cost before it bites.
- The settings page shows the platform operator a daily request budget card with the estimated requests broken down by kind, the capacity and a utilization meter.
GET /jobs/budgetreturns the same estimate, and the dashboard warns the platform operator when the daily pipeline would exceed 85 percent of capacity.
GET /jobs/budget reports them as marketListings, a part of apps.
A seeded market adds its keywords as daily searches like any keyword you track. The countries step of the guided setup and GET /apps/{id}/market-suggestions show what a market would cost before you add it: the listing reads a day, for the app and each competitor, and the requests each keyword adds.
When you are over budget, remove keywords or markets, or raise SCRAPE_ITUNES_RPM and accept the risk. See The daily pipeline and rate limits.
What is a market listing?
A store serves a different listing in each storefront. The App Store returns the title, the description and the rating count of the storefront you ask, so the same app can have a German title, a Japanese title and a Brazilian one, and a rating count that differs in each. asobeast captures that listing, as its own snapshot, for every market where you track at least one keyword, for your app and for each of its competitors.
A keyword is then judged against the listing of its own market: its coverage on the metadata page and its relevance next to the opportunity score. Until a market has a listing, a keyword is judged against the home listing, as every keyword was before.
What about storefronts that default to English?
Sixty five App Store storefronts show their listing in English by default although local users mostly read another language: Poland, Türkiye, Czechia, Greece, Saudi Arabia, Vietnam, India and Canada among them. Their search reads the English default and the native localization alike. For these storefronts asobeast asks for each native localization of the listing too, for your app and for each competitor, and keeps it as its own snapshot next to the default one when the store serves one.
A localization the app does not have is answered by the store with the default text, so asobeast stores nothing for it. That includes a page that repeats the default title, description, screenshots and release notes and only shows its translated category where the default has a subtitle. asobeast still reads such a page every run to learn whether the app gained a localization, so it stays in the
localizations count of GET /jobs/budget. Once stored, a localization is captured on every refresh, so removing it shows up as a change. An upgrade deletes the localizations that earlier versions stored from pages that only echoed the default.
A market capture also reads every localization your app ships that the storefront reads besides its default, so French and Italian in Switzerland, Catalan in Spain or Spanish (Mexico) in the United States are captured once the app ships them. It stores one only when the store serves its own text, exactly as for a native localization, and the budget counts each read under localizations. Competitors are captured with the native localizations only, because the localizations on the list are your app’s. See Which localizations does an app ship?
The native localizations are captured with the listing they belong to: when you import an app, when you refresh a listing and in the daily run. Each one costs one more listing read, and GET /jobs/budget reports them as localizations, a part of apps. India reads eleven localizations, so a market there costs the most.
Coverage judges a keyword within each localization, because the words of one localization combine into phrases only with each other: a keyword in the Polish title is covered even when the English title does not contain it, and the metadata page names the localization that covers it. Auto tracked keywords take phrases from every localization of the home storefront in turn, native first, up to the same limit. The keyword field you saved for a localization is judged with that localization too. Changes to a native localization are recorded in that localization only and send no alert.
A market listing carries its own screenshots. On the App Store their captions are read with that storefront’s language, and the Screenshot text column of a keyword reads the captions of the same listing that judged the keyword. See Read screenshot captions.
Some things are still read once, from the home storefront, because they need more than the listing: category ranks, reviews and the ratings history, the ASO audit and the keywords asobeast tracks for you from your listing. Top charts are different: any storefront’s chart can be read, followed or captured. See Read top charts. The Action Center rules that judge coverage, lint and staleness also read the home listing. See Action Center.
A keyword judged against a market listing is covered by the title and subtitle of every localization that storefront reads, and by the keyword field of each of those localizations you saved. A keyword whose market has no listing yet is judged against the whole home listing, keyword field included.
A market whose keywords you all removed keeps its last listing readable in the switcher, but asobeast stops refreshing it, and the Refresh button says why instead of refreshing.
If an app is not published in a market, asobeast tries again the next day and stores nothing, so a market with keywords and no listing simply shows no switcher entry.
What does the overview count?
The market switcher on the app overview, labelled Market, also scopes the keyword numbers. Until you choose a market it shows All markets: visibility, the tracked keyword count, the rank distribution, the movers and both history charts count every market the app tracks keywords in, as the portfolio dashboard does. An app with a single listing has no switcher and always counts every market. The Ratings by market card ignores the switcher’s scope and lists every market, marking the one you chose. See Compare ratings across markets. Choosing a market counts only the keywords tracked in it, and the 7 and 30 day changes are measured from that market’s own latest check. The metadata coverage card counts every market whichever you choose, because it judges keywords against the home listing. The API takes the same choice as an optionalcountry on GET /apps/{id}/summary, GET /apps/{id}/visibility-history and GET /apps/{id}/rank-distribution-history, and counts every market when it is omitted. The summary’s coverage block counts every market either way.
How do you add a market?
The countries step of the guided setup suggests storefronts from the languages your home listing declares, groups them by localization and lets you tick the ones to track. Each ticked storefront can be seeded with up to 15 keywords from its own title and subtitle, so the keyword monitor, the coverage check and the wasted words check have something to show on day one. A storefront whose default is the localization is ticked for seeding by default; one that reads it as an additional language is not.
A phrase the app already tracks in that market, active or paused, is left as it is, so seeding a market twice tracks nothing new. Seeding spends one refresh from your on demand allowance once the store is asked. See A spent on demand allowance names its action.
Later, on the keyword monitor, switch markets with the country filter, which shows the keyword count per market, then add keywords into the market you selected. A market with no keywords yet shows an empty state with an add button. The first keyword you add there asks for the market’s listing, so the market appears in the listing market switcher after the next job runs.
The API has the same two steps.
GET /apps/{id}/market-suggestions lists the suggested storefronts, each with its localization, its role, whether the app already tracks keywords there and its daily cost. POST /apps/{id}/market-seed with a country seeds one market and answers seeded, skipped and a status that is unavailable when the store has no listing of the app in that storefront.
Why are storefronts suggested from languages, not availability?
The store lookup reports the languages a listing ships, and asobeast knows which localization every storefront reads, so joining the two costs no store request. The store has no call that lists where an app is published: availability is one request per storefront, 175 of them on the App Store, and a storefront can carry the app with the default listing only, so availability would answer a different question. Seeding captures the listing anyway and reports a storefront without the app from that same request. English is never suggested, because every storefront reads an English localization and your home market already covers it. An app whose listing declares English only, a competitor and every Google Play app get no suggestions, and the setup step keeps its country code field.Which codes are storefronts?
A home storefront and every keyword market must be a place where the app’s store operates. asobeast checks the code against the store before it reaches it, so a code that is not a storefront is refused at once instead of failing every job it would have queued.
The two lists differ, so the check is made per store.
pw is an App Store storefront that Google Play does not list, and 51 codes such as ad, bd and li are Google Play locations without an App Store storefront. Kosovo is xk in both stores.
The refusal names the store, for example zz is not an App Store storefront or pw is not a Google Play location. It applies to importing an app, adding keywords, reactivating a paused keyword, deep search, keyword suggestions, the market availability check and saving the selected markets of the guided setup. A store URL whose country segment or gl parameter names no storefront is refused the same way.
An upgrade pauses any keyword that was already tracked in a code that is not a storefront. Its history stays, and it stops producing failed jobs.
The selected markets of the guided setup are checked against the store of the app when you save them (PATCH /apps/{id}/setup answers 400 for a code that is not a storefront). A code the setup already holds, and the home storefront of the app, are kept as they are, so saving a list you read back never fails; remove a code you do not want from the setup.
Which localizations does a storefront read?
Apple publishes, for every App Store storefront, a default language and the additional languages it supports, in App Store localizations. asobeast carries that table unchanged, for the same 175 storefronts it accepts.
Many ASO guides still name only Spanish (Mexico) for the United States. asobeast follows Apple’s table.
Apple’s page lists languages; it does not describe search. In practice, App Store search in a storefront reads the title, subtitle and keyword field of every localization on that storefront’s list, and the words of one localization combine into phrases only with each other. Each additional language is therefore extra room: its own 30 character title, 30 character subtitle and 100 character keyword field.
How does asobeast keep a keyword field per localization?
App Store Connect has one private keyword field per localization, and a new localization starts with it empty. asobeast keeps one keyword field per localization too, and it is edited in one place: the App Store localizations section of the metadata page, which has one editor for each localization your app ships. A storefront counts the fields of every localization it reads. The German field counts in Germany, Austria, Switzerland and Luxembourg, and the Spanish (Mexico) field counts in Mexico and in the United States. The keywords page never edits a field. Its What search reads card reports what one market reads and links each row to the editor. See What does a market read?
You can tick only markets of your app whose storefront reads the localization. A market of your app is your home storefront and every storefront where you track at least one keyword.
The field you saved before keyword fields were kept per localization is the field of your home storefront’s default localization, English (U.S.) for an app whose home storefront is the United States. If your home storefront defaults to English and you had pasted the field of its native localization, such as Polish in Poland, save it again under that localization and empty the default one. See Edit the iOS keyword field.
Which localizations does an app ship?
An app ships a localization when it has its own text in App Store Connect. asobeast cannot read App Store Connect, so it keeps a list of its own. A localization is on the list for one of three reasons.
Saving a non-empty keyword field for a localization ships it, because writing a field for a language means shipping that language. A detected localization stays detected when you save its field. Emptying a field keeps the localization on the list. Only Remove localization takes one off, and it refuses the home localization and a localization that is not on the list.
Find localizations asks the store, for each language that one of your markets reads, that is not on the list yet and that your home listing says the app supports, whether it serves that localization’s text. The questions are store lookups that run behind the daily run, and each language is asked at most once a day, so a second click on the same day queues nothing. Finding localizations spends one refresh from your on demand allowance, and only when it queues at least one lookup. See A spent on demand allowance names its action. A localization the store proves is added as detected. If you removed it, it comes back the next time you run Find localizations, because the store still says you ship it.
asobeast also asks the store on its own. The lookups queue after the first capture of a market’s listing, for the localizations that market reads, and once a week for every App Store app (
CRON_LOCALIZATION_SWEEP, Monday 07:00 UTC, see the configuration reference). Neither spends your allowance, so Find localizations is for when you want the answer today. A detected localization you removed comes back only if the store still serves it.
The default localization of a market needs no lookup. Every capture of a market’s listing compares it with your home listing and with every additional localization read in that market at the same time. When it differs from all of them, the store is serving the market’s own language, and that localization is added as detected. Germany tracked with a German listing adds German after its next capture, so by the next daily run at the latest, or at once when you press Refresh on that market. A market whose listing repeats your home text adds nothing, because the store is not serving its language; add it by hand if you ship it with the same words.
asobeast also records a native localization when it first captures one, which is how English storefronts such as Poland or India add their native languages without a click. See What about storefronts that default to English?
What asobeast still cannot know:
- A store page whose text equals the default listing looks the same as a page for a language you do not ship, so a localization with the default text is never detected. The store answers a language you do not ship with your app’s primary text, so Find localizations never detects a localization whose text equals your home listing either, even in a market whose default language is another one. The default localization itself is never detected. Add such a localization by hand.
- The keyword field of a localization is private, so asobeast never learns its contents. A localization you ship starts with an empty field until you type it.
- A localization you never added, never saved a field for and the store never proved is not on the list. The list is what asobeast can prove or what you tell it.
Which markets read a localization?
A market of your app reads a localization when the localization is on its storefront’s list. That market is a reader of the localization, and it has a role: Default when the localization is the first on the storefront’s list, Additional otherwise. Spanish (Mexico) is the default in Mexico and an additional language in the United States. The matrix at the top of the App Store localizations section crosses your shipped localizations with your markets and shows Default, Additional or nothing in each cell. It appears once the app has two markets or two shipped localizations. Each editor lists its readers as chips. A shipped localization that none of your markets reads is still editable. Its editor says so and names storefronts that read it, and saving it tracks nothing, because no market of yours reads it. Add one of those storefronts as a keyword market to track its phrases there. See How do you add a market?What does a market read?
The keywords page card What search reads follows the market you selected. It lists, in read order, the shipped localizations that storefront reads, each with its role, the characters its field uses of the 100 available, and an Edit link to its editor. The localizations the storefront reads that your app does not ship are folded into a line you can open, with the room they would add, 100 characters each. A market that is not an App Store storefront says so and asks for nothing. Two hints on the card are diagnostics. They never change coverage, the audit or an Action Center rule.- Words read twice. A word saved in the keyword fields of two or more localizations that this market reads spends characters twice, because search combines the words of a localization only with each other and gains nothing from the repeat. Stopwords are skipped.
- Split phrases. A tracked phrase of two or more words in this market, whose words are all read by the market but sit in different localizations, cannot match as typed. The card names the localization that holds each word. The words of a localization are those of its keyword field, its title and its subtitle where asobeast captured them.