AppTail – ASO & Keyword Research

{'type': 'object', 'required': ['app'], 'properties': {'app': {'type': 'string', 'description': "The app to claim: an Apptail app_id, a full App Store URL, or the app's name. A URL is the reliable form — a name resolves against the whole store, and two apps can share one."}, 'country': {'type': 'string', 'description': 'Primary storefront for this app, ISO 3166-1 alpha-2 (e.g. US, DE). Defaults to US. This is the storefront its keywords and rankings are tracked in first; more can be added in the console.'}, 'dry_run': {'type': 'boolean', 'description': 'Resolve the app and report what would happen without claiming it. Worth doing when the user gave a name rather than a URL, so they can confirm it is the right app before it counts against their plan.'}}}

{'type': 'object', 'required': ['status', 'country', 'apps_used', 'apps_limit', 'connected'], 'properties': {'app': {'type': ['object', 'null'], 'required': ['app_id', 'is_competitor', 'hidden', 'unreleased', 'connected', 'stale'], 'properties': {'icon': {'type': ['string', 'null'], 'description': 'Absolute URL of the app icon.'}, 'name': {'type': ['string', 'null'], 'description': 'The app\'s title **as published in `country`** — the string a shopper in that storefront reads, which is also the string Apple indexes. It is not a translation of one canonical name: an app localised for Mexico has a different title there, and `get_app(country: "mx")` returning the US one is what makes an agent report a localised app as "not localized". Falls back to the app\'s canonical name when this storefront has not been crawled yet, and is null only while a freshly imported app is still being processed.'}, 'price': {'type': ['number', 'null'], 'description': "Download price in `country`, in that storefront's own currency and in major units — 9.99, never 999. 0 means free, which is what most apps are; `currency` names the money. Null when this storefront has no listing on file."}, 'stale': {'type': 'boolean', 'description': "True when the lag is past what Apple's delay explains. A stale app's recent numbers are not a quiet fortnight, they are a gap — say so instead of reporting a decline."}, 'store': {'enum': ['apple', 'google'], 'type': ['string', 'null'], 'description': 'Which store the app belongs to.'}, 'app_id': {'type': 'integer', 'description': 'Apptail app ID. This is the `app_id` every other tool expects.'}, 'hidden': {'type': 'boolean', 'description': 'True when the owner has set this app aside. It is still tracked and still crawled, but it is left out of every portfolio total in the console — so leave it out of yours, or say that you did not.'}, 'country': {'type': ['string', 'null'], 'description': 'Storefront the metrics below were read from. Defaults to `primary_country`.'}, 'is_mine': {'type': ['boolean', 'null'], 'description': 'True when this is one of the asking account\'s own apps. Null when the call carried no account — get_top_charts answers without a token — which is "not known here", not "no".'}, 'version': {'type': ['string', 'null'], 'description': 'Latest published version string.'}, 'currency': {'type': ['string', 'null'], 'description': 'ISO code of the currency `price` is in, derived from `country`. A price without it is a number, not an amount — several storefronts print a "$" and mean different money.'}, 'subtitle': {'type': ['string', 'null'], 'description': 'The subtitle under the title in `country` — thirty characters Apple indexes as heavily as the title, and the field most competitors leave generic. Null when the storefront listing has none, which is itself worth saying: an empty subtitle is unspent keyword weight.'}, 'bundle_id': {'type': ['string', 'null'], 'description': 'Store bundle identifier, e.g. "com.burbn.instagram".'}, 'connected': {'type': 'boolean', 'description': 'True when App Store Connect reports for this app. Only a connected app has measured impressions, downloads, sales or proceeds — get_performance returns them, and returns nothing for the rest rather than a zero.'}, 'unreleased': {'type': 'boolean', 'description': 'True when App Store Connect lists this app but no storefront does yet — a pre-release app the owner is preparing. Keywords, competitors, markets and SERPs all work for it; its own rank is -1 everywhere, and it has no ratings, reviews, listing or first-party figures. Treat every missing number as "not launched", never as a fault or a decline. The console switches it over the night it appears on a storefront.'}, 'console_url': {'type': ['string', 'null'], 'description': "Where to open this app in the AppTail console — the owner's own dashboard when `is_mine`, the research view otherwise. Null where this environment serves no console. End an answer about an app with it."}, 'apple_app_id': {'type': ['integer', 'null'], 'description': "Apple's own numeric app ID, as it appears in App Store URLs. Not interchangeable with `app_id`."}, 'data_through': {'type': ['string', 'null'], 'description': 'Last day Apple reported for this app. Null when it never has, which for a connection made today is normal and for an older one is a fault.'}, 'rating_count': {'type': ['integer', 'null'], 'description': 'Number of ratings in `country`.'}, 'data_lag_days': {'type': ['integer', 'null'], 'description': "How many days behind today that is. One or two is Apple's normal delay; more is worth mentioning before quoting recent figures."}, 'is_competitor': {'type': 'boolean', 'description': "True when this row is a rival tracked under one of the account's apps rather than an app of its own. **Never include one in a portfolio total.** False on every row unless `include_competitors` was set."}, 'rating_average': {'type': ['number', 'null'], 'description': 'Mean star rating (1-5) in `country`. Null if the app has no ratings there yet.'}, 'primary_country': {'type': ['string', 'null'], 'description': 'Lowercase ISO country code of the app\'s main storefront, e.g. "us".'}, 'primary_category': {'type': ['integer', 'null'], 'description': 'Store category ID. Pass this as `category` to get_top_charts.'}, 'listing_storefronts': {'type': 'array', 'items': {'type': 'string'}, 'description': 'One storefront per language the listing is localized in, `primary_country` first, e.g. ["ru", "us"]. An app published in two languages is searched for in two storefronts; keyword discovery and tracking are per storefront, so cover each of these rather than only `primary_country`.'}, 'competitor_of_app_id': {'type': ['integer', 'null'], 'description': "When `is_competitor` is true, the `app_id` of the account's own app it competes with."}, 'is_tracked_competitor': {'type': ['boolean', 'null'], 'description': 'True when the account already tracks this app as a competitor of one of theirs. False on a high-ranking rival is a suggestion worth making: add_competitors starts watching it. Null when the call carried no account.'}, 'primary_category_name': {'type': ['string', 'null'], 'description': 'Human-readable name of `primary_category`, e.g. "Health Fitness".'}}, 'description': 'The app as it now appears in the account. Null under dry_run only if nothing resolved.'}, 'note': {'type': ['string', 'null'], 'description': 'What happens next, when there is something the user should know.'}, 'status': {'enum': ['added', 'already', 'would_add'], 'type': 'string', 'description': '`added` when it is now in the account, `already` when it was there before this call, `would_add` under dry_run.'}, 'country': {'type': 'string', 'description': 'The storefront it was added for.'}, 'apps_used': {'type': 'integer', 'description': 'Own apps in the account after this call.'}, 'connected': {'type': 'boolean', 'description': 'Whether App Store Connect reports for this app. False for almost every freshly added app — say so, because get_performance will return nothing for it until it is connected in the console.'}, 'apps_limit': {'type': 'integer', 'description': 'How many the plan allows. -1 means unlimited.'}, 'console_url': {'type': ['string', 'null'], 'description': 'Where to open this app in the AppTail console.'}}}

{'type': 'object', 'required': ['app_id', 'competitors'], 'properties': {'app_id': {'type': 'integer', 'description': 'Apptail app id for one of YOUR apps — from get_account. The rivals are tracked FOR this app: competitor sets belong to an app, not to the account, so removing one later affects only this app.'}, 'country': {'type': 'string', 'description': 'Storefront to resolve names in, ISO 3166-1 alpha-2 (e.g. US, DE). Omit and it is guessed from the script the name is written in. Ignored for items given as an app_id.'}, 'dry_run': {'type': 'boolean', 'description': 'Resolve every item and report what would happen, without tracking anything. Use it when the user named apps ambiguously and you want to confirm you found the right ones before changing their account.'}, 'competitors': {'type': 'array', 'items': {'type': 'string'}, 'description': 'The rivals, up to 20. Each item is an Apptail app_id, a full App Store URL, or an app name in any language. Send all of them in one call — the plan limit is checked per item, so a batch that runs out of room still adds what fits and says which items did not.'}}}

{'type': 'object', 'required': ['app_id', 'dry_run', 'added_count', 'requested_count', 'outcomes'], 'properties': {'app_id': {'type': 'integer', 'description': 'The app these rivals are tracked against.'}, 'dry_run': {'type': 'boolean', 'description': 'True when nothing was written. Every outcome then reads `would_add`.'}, 'outcomes': {'type': 'array', 'items': {'type': 'object', 'required': ['ref', 'status'], 'properties': {'ref': {'type': 'string', 'description': 'What was asked for, exactly as it was sent — an id, a name or a store URL. Match outcomes to your request by this, not by order.'}, 'name': {'type': ['string', 'null'], 'description': "The app's name, so the answer can name it rather than quoting an id back."}, 'app_id': {'type': ['integer', 'null'], 'description': 'Apptail app id, once the reference resolved to one. Null when nothing matched.'}, 'status': {'enum': ['added', 'already', 'removed', 'not_tracked', 'not_found', 'refused', 'would_add'], 'type': 'string', 'description': 'What happened to this one. `added` / `removed` are done. `already` means it was there before this call and nothing changed — not a failure. `not_tracked` means it was not there to remove. `not_found` means nothing in the store matched. `refused` means a rule said no and `message` says which. `would_add` only appears under `dry_run`, and nothing was written.'}, 'message': {'type': ['string', 'null'], 'description': 'Why, when this one did not do what was asked. Written for a person — quote it rather than rewriting it.'}, 'console_url': {'type': ['string', 'null'], 'description': 'Where the owner can see this app in the AppTail console.'}}}, 'description': 'One row per item, in the order they were sent. Read `status` per row: a batch is rarely all one thing, and reporting it as "done" when two of five were refused is the failure this shape exists to prevent.'}, 'remaining': {'type': ['integer', 'null'], 'description': 'Competitor slots left for this app on this plan after the call. Null when the plan is unlimited. Zero means the next add will be refused — say so rather than letting the user find out.'}, 'added_count': {'type': 'integer', 'description': 'How many are now tracked that were not before.'}, 'requested_count': {'type': 'integer', 'description': 'How many items were sent.'}}}

{'type': 'object', 'required': ['app_id', 'country'], 'properties': {'app_id': {'type': 'integer', 'description': 'Apptail app id for one of YOUR apps — get it from get_account. Not the numeric id in an App Store URL (that is apple_app_id). Keywords are tracked per app.'}, 'country': {'type': 'string', 'description': 'Storefront to track these terms in, ISO 3166-1 alpha-2 (e.g. US, GB, DE). Required and not defaulted: a term tracked in the wrong storefront is a wasted keyword slot. Ranks are per storefront — the same term ranks differently in each.'}, 'dry_run': {'type': 'boolean', 'description': 'Report what would be added, and how many slots are left, without tracking anything. Nothing is written and nothing counts against the plan.'}, 'keywords': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Search terms to start tracking, as a user would type them into the App Store (e.g. ["fitness tracker", "workout app"]). Send the whole batch in one call rather than one term per call. Terms we have never seen are created. Every added term whose results are more than a day old is crawled straight away, and positions usually land within a few minutes: a get_keywords read made immediately after this call shows those terms as unmeasured, which means not crawled yet and not that the app is missing from the results. Either this or `keyword_ids` is required.'}, 'keyword_ids': {'type': 'array', 'items': {'type': 'integer'}, 'description': 'Apptail keyword ids to start tracking — the `keyword_id` on a discover_keywords row. Use this rather than the term whenever you have an id: a term is re-resolved and can land on a different keyword row than the one you were shown.'}}}

{'type': 'object', 'required': ['app_id', 'country', 'added', 'skipped', 'already_tracked', 'added_count', 'skipped_count', 'dry_run', 'limit'], 'properties': {'added': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Terms now being tracked. Under `dry_run` this is what would be added and nothing was written.'}, 'limit': {'type': 'integer', 'description': 'Keywords this plan allows per app. -1 means unlimited.'}, 'app_id': {'type': 'integer', 'description': 'The app these terms are tracked for.'}, 'country': {'type': 'string', 'description': 'The storefront they were tracked in.'}, 'dry_run': {'type': 'boolean', 'description': 'True when nothing was written.'}, 'skipped': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Everything not added: the union of `already_tracked` and the terms that could not be resolved in that storefront or that ran out of plan room. Do not report this count as a failure without reading `already_tracked` first.'}, 'remaining': {'type': ['integer', 'null'], 'description': 'Keyword slots left for this app on this plan after the call. Null when the plan is unlimited. Zero means the next add is refused.'}, 'added_count': {'type': 'integer', 'description': 'Size of `added`.'}, 'limit_reached': {'type': ['string', 'null'], 'description': "Set when the account's plan limit stopped the run before the whole list was added. A ceiling, not a fault — say what was capped rather than retrying."}, 'skipped_count': {'type': 'integer', 'description': 'Size of `skipped`, both reasons together. Subtract `already_tracked` before calling anything a problem.'}, 'already_tracked': {'type': 'array', 'items': {'type': 'string'}, 'description': 'The subset of `skipped` that the app was already tracking. **This is the end state that was asked for, not a fault** — a term already in the corpus needs no retry and no apology. What is in `skipped` but not here is the half worth mentioning: a term that does not exist in that storefront, or one the plan had no room for (see `limit_reached`).'}}}

{'type': 'object', 'required': ['app_id'], 'properties': {'limit': {'type': 'integer', 'description': 'Max suggestions, most-searched first. Default 60, capped at 200. The answer always says how many there were.'}, 'app_id': {'type': 'integer', 'description': "Apptail app id to suggest for. get_account for the user's own apps. Suggestions are derived from this app's listing, its rivals and its neighbours, so they are only meaningful for the app they were asked about."}, 'source': {'type': 'array', 'items': {'enum': ['competitors', 'similar', 'listing', 'store', 'ai', 'corpus', 'all'], 'type': 'string'}, 'description': 'Which sources to read. Omit for all five that need no argument — `competitors`, `similar`, `listing`, `store`, `ai`. `corpus` is a text match against terms AppTail already holds and does nothing without `contains`, which is why "all" does not silently include it. An unknown name is refused rather than ignored.'}, 'country': {'type': 'string', 'description': "Storefront to suggest for (e.g. US, DE). Defaults to the app's primary storefront — which is only one of them: an app localized into several languages is searched for in several storefronts, so call once per entry in get_app's `listing_storefronts`. Discovery is per storefront and never a blend: a German term is not a translation of an English one — `spritverbrauch` beats `kraftstoffverbrauch` by a margin no dictionary would tell you."}, 'contains': {'type': 'string', 'description': 'Only terms containing this text. With `source: ["corpus"]` this is a search of AppTail\'s keyword database. Note it searches terms AppTail holds, not the App Store: a phrase nobody has ever tracked returns nothing, and to start tracking a brand-new term you pass it straight to add_keywords.'}}}

{'type': 'object', 'required': ['app_id', 'country', 'sources', 'count', 'total', 'truncated', 'by_source', 'suggestions'], 'properties': {'count': {'type': 'integer', 'description': 'Suggestions returned.'}, 'total': {'type': 'integer', 'description': 'Suggestions found before the cap.'}, 'app_id': {'type': 'integer', 'description': 'The app these suggestions are for.'}, 'country': {'type': 'string', 'description': 'The storefront they apply to.'}, 'sources': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Sources actually read. A source not listed here was not consulted.'}, 'app_name': {'type': ['string', 'null'], 'description': 'Its name.'}, 'by_source': {'type': 'object', 'description': "How many suggestions each source produced, keyed by source name; a source with none is absent. **Read this before reporting an empty answer.** Five of the six need something on file — rivals, the store's similar-apps list, a mining job that runs fortnightly — so zero beside `competitors` is a fact about the account, not about the niche, and the fix is add_competitors rather than a different question."}, 'truncated': {'type': 'boolean', 'description': 'True when `count` is below `total`. Say the list is partial rather than presenting it as everything worth tracking.'}, 'console_url': {'type': ['string', 'null'], 'description': "The app's keyword screen in the console, where the same list can be reviewed and added by hand."}, 'suggestions': {'type': 'array', 'items': {'type': 'object', 'required': ['keyword_id', 'name', 'source', 'pending'], 'properties': {'name': {'type': 'string', 'description': 'The term itself, lowercased.'}, 'source': {'enum': ['competitors', 'similar', 'store', 'ai', 'corpus'], 'type': 'string', 'description': "Why this term is here. `competitors` — a tracked rival ranks for it. `similar` — an app the store calls similar does. `store` — the store's own mining surfaced it for this listing. `ai` — read off this app's own title, subtitle and description, which is the only source that works on an app added minutes ago. `corpus` — a text match against terms AppTail already holds, and only when `contains` was sent. When two sources agree, the most actionable one is named."}, 'country': {'type': ['string', 'null'], 'description': 'Storefront this suggestion is for. Discovery is per storefront and a German term is not a translation of an English one.'}, 'pending': {'type': 'boolean', 'description': "True when this term's popularity has been queued for measurement but not yet collected. Say the figure is coming rather than quoting a null as a zero."}, 'keyword_id': {'type': 'integer', 'description': "Apptail keyword ID. **Pass this to add_keywords as a `keyword_id`, never the term.** Re-resolving a suggestion's text lowercases and strips punctuation and can land on a different row, so the account ends up tracking something this list never named."}, 'popularity': {'type': ['integer', 'null'], 'description': 'Apple search popularity (roughly 5-100), higher is more searched. **Null means not measured yet, never "nobody searches for it"** — see `pending`.'}, 'console_url': {'type': ['string', 'null'], 'description': 'Where to open this term in the AppTail console.'}, 'results_count': {'type': ['integer', 'null'], 'description': 'How many apps the store returns for the term. A rough crowding signal.'}}}, 'description': 'The terms, most-searched first. Add them with add_keywords using their `keyword_id`, never their text.'}}}

{'type': 'object', 'required': ['market_id', 'country'], 'properties': {'add': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Terms to pin, as somebody would type them into the App Store. Send the batch in one call. Terms already in the corpus come back under `already_present` rather than as an error.'}, 'remove': {'type': 'array', 'items': {'type': 'integer'}, 'description': 'Keyword ids to take out of the corpus — the `keyword_id` on ANY get_market corpus row. A term the heuristic found is also recorded as excluded so rebuilds do not re-derive it; `add` on the same term later clears that again.'}, 'country': {'type': 'string', 'description': "Which storefront's corpus, ISO 3166-1 alpha-2 (e.g. US, DE). Required and not defaulted: a corpus belongs to one storefront, and there is no market-wide term list to add to."}, 'market_id': {'type': 'integer', 'description': 'Apptail market id — from list_markets or save_market.'}}}

{'type': 'object', 'required': ['market_id', 'country', 'pinned', 'already_present', 'refused', 'removed', 'excluded', 'not_removed', 'terms', 'cap', 'caveats'], 'properties': {'cap': {'type': 'integer', 'description': "The most terms this storefront may hold, from the account's plan. A market's storefronts each get their own — the cap is per storefront, not shared across the market."}, 'terms': {'type': 'integer', 'description': "How many terms this storefront's corpus holds now."}, 'pinned': {'type': 'array', 'items': {'type': 'object', 'properties': {'term': {'type': 'string', 'description': 'The term as the store stores it: lower case, punctuation stripped.'}, 'keyword_id': {'type': 'integer', 'description': 'Pass it to get_keyword_serp, or to add_keywords to track it against one of your own apps.'}}}, 'description': 'Terms added to the corpus by this call, with `origin: "manual"`. A term Apptail has never seen is created and queued for crawling, so its ranks appear within minutes rather than immediately.'}, 'caveats': {'type': 'array', 'items': {'type': 'string'}, 'description': 'What the caller needs to hear before reporting success — that ranks are not in yet, or that the cap cut the list.'}, 'country': {'type': 'string', 'description': 'The storefront that was edited. A corpus belongs to one storefront and is never shared between them.'}, 'refused': {'type': 'array', 'items': {'type': 'string'}, 'description': "Terms not added because the storefront is at `cap`. Unpin something or drop a storefront; the account's plan sets the number."}, 'removed': {'type': 'array', 'items': {'type': 'integer'}, 'description': 'Keyword ids taken out of the corpus by this call.'}, 'excluded': {'type': 'array', 'items': {'type': 'integer'}, 'description': 'The subset of `removed` that will ALSO be kept out of every future rebuild. A term the heuristic found is re-derived from the seeds every 72 hours, so removing it has to be recorded outside the corpus to last; a hand-pinned term needs no such record because nothing re-adds it. Pinning a term with `add` clears it from this list again.'}, 'market_id': {'type': 'integer', 'description': 'The market this corpus belongs to.'}, 'console_url': {'type': ['string', 'null'], 'description': "This market's corpus in the console."}, 'not_removed': {'type': 'array', 'items': {'type': 'object', 'properties': {'reason': {'type': 'string', 'description': "Why it stayed — normally that the id is not in this storefront's corpus at all."}, 'keyword_id': {'type': 'integer'}}}, 'description': 'Ids that were sent to `remove` and are still in the corpus, each with the reason.'}, 'already_present': {'type': 'array', 'items': {'type': 'object', 'properties': {'term': {'type': 'string'}, 'origin': {'type': 'string', 'description': 'How it got there: seed | competitor | related | manual.'}}}, 'description': 'Terms that were already in this corpus, and where they came from. Not an error — it is the state the caller asked for, and a `competitor` term is NOT re-recorded as `manual`, because the origin says who put the term here.'}}}

{'type': 'object', 'properties': {'to': {'type': 'string', 'description': 'End date, `YYYY-MM-DD`, inclusive. Send it alone and the window is the three years before it.'}, 'from': {'type': 'string', 'description': 'Start date, `YYYY-MM-DD`, inclusive. Overrides `period` when both are sent. Send it alone and the window runs to today.'}, 'app_id': {'type': 'integer', 'description': "Narrow to one of the account's own apps — get_account lists them. Omit for the whole portfolio, which excludes apps the owner has hidden."}, 'period': {'type': 'string', 'description': 'The window to report on. A calendar month as `2026-07`, a calendar year as `2026`, `last_month`, `this_month`, `last_year`, or a trailing window: `today`, `7d`, `14d`, `30d`, `90d`, `180d`, `365d`, `730d`, `1095d`. Defaults to `last_month`. A calendar period is compared against the calendar period before it — July against June, not against the 31 days ending 30 June. Three years is the ceiling.'}, 'compare': {'enum': ['none', 'previous', 'year_ago'], 'type': 'string', 'description': 'What to read the period against. `previous` (the default) is the period immediately before — for a calendar month, the calendar month before. `year_ago` is the same dates a year earlier, for comparison with the corresponding period in the previous year.'}, 'country': {'type': 'string', 'description': "Storefront for the keyword half only; the money is reported across all of them with a per-storefront split. Defaults to the app's primary storefront. Ranks only exist per storefront."}}}

{'type': 'object', 'required': ['window', 'app_ids', 'headline', 'signals', 'reviews', 'caveats'], 'properties': {'digest': {'type': ['object', 'null'], 'properties': {'week': {'type': ['integer', 'null'], 'description': 'ISO week it covered.'}, 'moves': {'type': 'array', 'items': {'type': 'object', 'properties': {'id': {'type': 'string'}, 'cause': {'type': ['string', 'null']}, 'title': {'type': 'string', 'description': 'The finding, in the words the email used.'}, 'app_id': {'type': ['integer', 'null']}, 'metric': {'type': ['string', 'null']}}}, 'description': 'The moves it asked the customer to look at, as sent. Empty on a quiet week.'}, 'numbers': {'type': ['object', 'null'], 'properties': {'proceeds': {'type': 'object', 'properties': {'value': {'type': 'number'}, 'previous': {'type': 'number'}}}, 'downloads': {'type': 'object', 'properties': {'value': {'type': 'number'}, 'previous': {'type': 'number'}}}, 'page_views': {'type': 'object', 'properties': {'value': {'type': 'number'}, 'previous': {'type': 'number'}}}, 'impressions': {'type': 'object', 'properties': {'value': {'type': 'number'}, 'previous': {'type': 'number'}}}}, 'description': 'The four numbers it led with, each against the week before. **Null when the account has no App Store Connect connection** — that digest never carried them, and null here is "not measured", not a flat week.'}, 'sent_at': {'type': 'string', 'description': 'When the most recent weekly digest went out, ISO timestamp.'}, 'subject': {'type': ['string', 'null'], 'description': "The subject line as sent — the week's one finding, or the numbers."}, 'connected': {'type': ['boolean', 'null'], 'description': 'Whether the digest had App Store Connect figures in it at all. False means the letter led with `visibility` below and showed the four metric tiles locked.'}, 'covered_to': {'type': ['string', 'null'], 'description': 'Sunday of that week.'}, 'visibility': {'type': 'array', 'items': {'type': 'object', 'properties': {'moved': {'type': 'integer', 'description': 'How many of the tracked terms moved in the week.'}, 'top10': {'type': 'integer', 'description': 'Terms the app is in the top ten for there.'}, 'app_id': {'type': 'integer'}, 'country': {'type': 'string', 'description': 'The storefront the ranks were read in.'}, 'tracked': {'type': 'integer', 'description': 'Terms the account tracks for that app. Zero is real: the ranks are crawled either way.'}}}, 'description': "Where the digest said the apps rank, from AppTail's own crawl. This is what the letter leads with when there is no App Store Connect connection."}, 'covered_from': {'type': ['string', 'null'], 'description': 'Monday of that week.'}}, 'description': '**What the customer was last mailed** — the weekly digest, sent Wednesdays, that leads with the measured week and at most three moves. Null when none has gone out yet. Anything here is breakfast reading, not news: say "as your digest said" rather than presenting it as a discovery, and lead with what happened since `sent_at`.'}, 'window': {'type': 'object', 'required': ['from', 'to', 'days', 'label'], 'properties': {'to': {'type': 'string', 'description': 'Last day covered, inclusive.'}, 'days': {'type': 'integer', 'description': 'Length of the window in days.'}, 'from': {'type': 'string', 'description': 'First day covered, inclusive.'}, 'label': {'type': 'string', 'description': 'What names this window — the period key, or `custom`.'}}, 'description': 'The window actually read, which is not always the one asked for: an inverted range is swapped, a range past three years is shortened, and first-party figures are pulled back to the last day App Store Connect reported. Quote these dates, not the requested ones.'}, 'app_ids': {'type': 'array', 'items': {'type': 'integer'}, 'description': 'The apps this covers.'}, 'caveats': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Everything the reader has to hear before this reads as a complete picture: apps with no connection, a window shortened to the last day Apple reported, a corpus larger than the movers shown. **Pass these on.** A composed answer that drops them is the confident-and-wrong failure this tool exists to avoid.'}, 'reviews': {'type': 'object', 'properties': {'total': {'type': 'integer', 'description': 'Reviews that arrived in the period, across every storefront.'}, 'critical': {'type': 'integer', 'description': 'How many of them were 1–2★.'}, 'positive': {'type': 'integer', 'description': 'How many were 4–5★.'}, 'previous_total': {'type': ['integer', 'null'], 'description': 'Arrivals in the comparison period. Null when nothing was compared.'}, 'previous_critical': {'type': ['integer', 'null'], 'description': 'Critical arrivals in the comparison period.'}}, 'description': "Review arrivals — a flow, counted over the period. Not the backlog of unanswered reviews, which has no window and is on the console's reviews screen."}, 'signals': {'type': 'object', 'properties': {'items': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'date', 'detected_at', 'type', 'severity', 'headline', 'evidence', 'app_id', 'app_name', 'owner_app_id', 'is_own_app', 'asks_action', 'storefronts', 'measure', 'to', 'improved'], 'properties': {'id': {'type': 'string', 'description': 'A stable id for this finding. The same string a digest email records, which is what makes `already_sent` an exact answer rather than a guess.'}, 'to': {'type': 'number', 'description': "What it is now, in the storefront named by `country`. Across a finding that spans storefronts the figures differ — Apple's price tiers are per currency — so `headline` states the range and these two stay one storefront's checkable numbers."}, 'date': {'type': 'string', 'description': 'The day the change happened, `YYYY-MM-DD` — not the day it was noticed. Detectors run after the crawl wave, so the two differ by hours.'}, 'from': {'type': ['number', 'null'], 'description': 'What it was, in the storefront named by `country`. Null only for a first observation, which says so in `evidence`.'}, 'type': {'enum': ['rank.move', 'chart.enter', 'review.spike', 'competitor.release', 'price.change', 'traffic.shift', 'conversion.shift', 'downloads.drop', 'review.new', 'rating.change'], 'type': 'string', 'description': "What kind of change this is. The first five are store-side and cover rivals; `traffic.shift`, `conversion.shift`, `downloads.drop`, `review.new` and `rating.change` are first-party (App Store Connect, the user's own reviews and ratings) and exist only for the user's own apps. A type this list does not name is not something the product watches for."}, 'app_id': {'type': 'integer', 'description': "The app this is ABOUT. Equal to `owner_app_id` when it is one of the user's own; otherwise it is a competitor they track."}, 'country': {'type': ['string', 'null'], 'description': "Storefront, or null for an event that is not per-storefront — a release is one event for the whole store, not 122 of them. When `storefronts` is above 1 this is the loudest of them, and `from`, `to` and `evidence` are that storefront's own figures; `countries` names the rest."}, 'keyword': {'type': ['string', 'null'], 'description': 'That term, when the keyword row still exists. A signal outlives the keyword it was written about, so null here means the term is no longer tracked, not that the finding is invalid.'}, 'measure': {'type': 'string', 'description': 'What `from` and `to` are in: `rank`, `chart_position`, `price`, `critical_reviews`, `days_between_releases`, `weekly_total` (of the metric `subject` names), `install_rate_pct`, `daily_downloads` (`from` is the trailing median), `stars` or `rating`. Never guess the unit from the type.'}, 'sent_at': {'type': ['string', 'null'], 'description': 'When the digest carrying it went out. Null when it never did, or when `include_sent` was not asked for.'}, 'subject': {'type': ['string', 'null'], 'description': 'What the row is about when it is not a keyword: a version string for a release, a chart id for a chart entry. Empty for the rest.'}, 'app_name': {'type': 'string', 'description': 'Name of that app.'}, 'evidence': {'type': 'string', 'description': 'The figures behind the headline in one sentence — what it moved from, over how long, against what baseline. This is the sentence a reader checks the product against.'}, 'headline': {'type': 'string', 'description': 'What happened, in one clause, with its numbers in it — the same sentence the console shows. Quote it rather than rewriting it; it is the finding, and it is checkable against `from` and `to`.'}, 'improved': {'type': 'boolean', 'description': 'Whether the move was in the good direction. Rank and chart position invert — #4 beats #19 — so a falling number is an improvement there and a rising one is not. Read this rather than comparing `from` and `to` yourself.'}, 'severity': {'enum': ['neutral', 'opportunity', 'warning', 'critical'], 'type': 'string', 'description': 'How loudly it speaks. Assigned from the size of the move, never from the type: a two-place slide and a slide out of the top ten are the same type and not the same news. `neutral` is worth knowing and not worth interrupting for.'}, 'countries': {'type': ['array', 'null'], 'items': {'type': 'string'}, 'description': 'Every storefront the finding covers, when it covers more than one — the whole list, never a sample. Null when there is only `country` to name.'}, 'is_own_app': {'type': 'boolean', 'description': "True when the subject is one of the user's own apps. False means a competitor moved, which is context rather than something they did."}, 'keyword_id': {'type': ['integer', 'null'], 'description': 'The term this is about, for a `rank.move`. Pass it to get_keywords or get_keyword_serp to find out who took the places. Null for every other type.'}, 'asks_action': {'type': 'boolean', 'description': "Whether this is a **task** or a **thing to know**. True means something of the user's moved — their app, or their tracked term — and there is a next step. False means it is intelligence: a competitor's 1–2★ wave, price cut or chart entry is worth knowing and has no move attached to it, because nothing of theirs changed. Lead an answer with the true ones and report the rest as context; the console draws exactly this line, so a briefing that ignores it disagrees with the screen the user is looking at."}, 'console_url': {'type': ['string', 'null'], 'description': "Where in the console this finding is shown. Always a page inside the user's own app, even for a finding about a competitor. End the answer with it."}, 'detected_at': {'type': 'string', 'description': 'When the detector wrote it, as an ISO timestamp.'}, 'storefronts': {'type': 'integer', 'description': "How many storefronts this ONE finding covers. A price re-tier is a single decision applied to up to 122 of them, so it is one finding here and not 122 — the console's feed shows it as one line for the same reason. 1 is the ordinary case; 0 means the event is not per-storefront at all."}, 'already_sent': {'type': ['boolean', 'null'], 'description': 'Whether this finding already went out in an alert digest the user has read. **Null means nobody asked** — set `include_sent` to find out. When it is true, lead with what is new instead of repeating what they read over breakfast.'}, 'owner_app_id': {'type': 'integer', 'description': "The app of the user's this hangs under. A rival's signal hangs under the app it was added as a competitor of, which is how a finding about somebody else is still a finding inside one of your niches."}}}, 'description': 'The findings, newest first, each with the sentence that states it. The rest is get_signals.'}, 'total': {'type': 'integer', 'description': 'Findings in the period, before the list below was capped.'}, 'by_type': {'type': 'object', 'properties': {'rank.move': {'type': 'integer'}, 'review.new': {'type': 'integer'}, 'chart.enter': {'type': 'integer'}, 'price.change': {'type': 'integer'}, 'review.spike': {'type': 'integer'}, 'rating.change': {'type': 'integer'}, 'traffic.shift': {'type': 'integer'}, 'downloads.drop': {'type': 'integer'}, 'conversion.shift': {'type': 'integer'}, 'competitor.release': {'type': 'integer'}}, 'description': 'The shape of the period by kind. A key is absent when there were none.'}, 'already_sent': {'type': 'integer', 'description': 'How many of the returned findings the customer has already been mailed in an alert digest. **Lead with the ones that are new** — repeating breakfast reading as news is how an assistant stops being believed.'}}, 'description': 'What the product itself detected. A stored record, not a reconstruction — quote these sentences rather than re-deriving them from the numbers.'}, 'headline': {'type': 'array', 'items': {'type': 'string'}, 'description': 'The two or three sentences a person would open with, each carrying its own figures. Lead with these; everything below is the evidence for them.'}, 'keywords': {'type': ['object', 'null'], 'properties': {'fell': {'type': 'integer', 'description': 'Terms that lost places or left the results.'}, 'held': {'type': 'integer', 'description': 'Terms that were measured and ended where they started.'}, 'rose': {'type': 'integer', 'description': 'Terms that gained places or entered them.'}, 'movers': {'type': 'array', 'items': {'type': 'object', 'required': ['keyword_id', 'name', 'app_id', 'current_position', 'start_position'], 'properties': {'name': {'type': 'string', 'description': 'The search term.'}, 'app_id': {'type': 'integer', 'description': 'The app this rank belongs to.'}, 'movement': {'type': ['object', 'null'], 'properties': {'delta': {'type': 'integer', 'description': 'Places moved. Meaningful only when both ends are real ranks.'}, 'status': {'enum': ['new', 'up', 'down', 'out'], 'type': 'string', 'description': '"up" = a better (smaller) rank, "down" = worse, "new" = arrived, "out" = left the results.'}}, 'description': 'How it moved. Null when it ended where it started.'}, 'keyword_id': {'type': 'integer', 'description': 'Apptail keyword id. Pass it to get_keywords for the history, or get_keyword_serp for who else ranks.'}, 'popularity': {'type': ['integer', 'null'], 'description': 'Apple search popularity, roughly 5-100. A collapse on a term nobody searches is not the story.'}, 'console_url': {'type': ['string', 'null'], 'description': 'The keyword screen for this app.'}, 'start_position': {'type': 'integer', 'description': 'Rank on the first day the term was crawled in this period, same scale.'}, 'current_position': {'type': 'integer', 'description': 'Rank on the last day the term was crawled, 1 = top. -1 means it was not in the results then.'}}}, 'description': 'The biggest movers, worst first. Their histories, tags and competitor ranks are in get_keywords; this is the shortlist.'}, 'country': {'type': ['string', 'null'], 'description': 'Storefront the ranks were read in.'}, 'tracked': {'type': 'integer', 'description': 'Terms tracked in that storefront — the denominator for the four counts below, which are over all of them and not over the `movers` shortlist.'}, 'unmeasured': {'type': 'integer', 'description': 'Terms crawled on no day of the period. Not folded into `held`: a term nobody looked at has no rank to have held. A large number here is a crawl gap, not a quiet month — get_keywords `coverage` has the detail.'}, 'visibility': {'type': ['object', 'null'], 'properties': {'top10': {'type': ['integer', 'null'], 'description': 'Terms in the top 10 at the end of the period.'}, 'top100': {'type': ['integer', 'null'], 'description': 'Terms in the top 100 at the end of the period.'}, 'top10_change': {'type': ['integer', 'null'], 'description': 'Change against the period before. Null means no earlier day was rolled up — no history, which is not a change of nothing.'}, 'top100_change': {'type': ['integer', 'null'], 'description': 'Change against the period before.'}}, 'description': 'The number that survives a corpus changing size, unlike a mean rank. Null when nothing has been rolled up for these apps yet.'}}, 'description': 'The keyword half. Null when the account tracks no apps.'}, 'performance': {'type': ['object', 'null'], 'properties': {'totals': {'type': 'array', 'items': {'type': 'object', 'required': ['key', 'is_estimate', 'precision'], 'properties': {'key': {'type': 'string', 'description': 'Which metric: `impressions`, `store_views`, `downloads`, `iap` (in-app purchase transactions), `sales` (gross), `proceeds` (what Apple actually pays out) or `conversion` (downloads over impressions, as a percentage).'}, 'note': {'type': ['string', 'null'], 'description': 'Something the reader has to know before quoting the figure — most often that the window was only measured part-way, or that connecting App Store Connect would replace the estimate with a measurement.'}, 'as_of': {'type': ['string', 'null'], 'description': 'For a measurement, the last day App Store Connect reported. For an estimate, the day the vendor was scraped.'}, 'value': {'type': ['number', 'null'], 'description': 'The figure. **Null means unknown, never zero** — no connection, or no data for these days. Also null when `precision` is `bucketed`, where the source only gave an upper bound.'}, 'source': {'enum': ['appstoreconnect', 'sensortower', 'appmagic', 'scraped', 'mock'], 'type': ['string', 'null'], 'description': "Where the figure came from. `appstoreconnect` is Apple's own measurement of an app the account has connected; `sensortower` and `appmagic` are third-party models. Null when nothing covers it."}, 'window': {'type': ['string', 'null'], 'description': 'What the figure covers: `2026-07-01..2026-07-31` for a measurement, or the literal `rolling_30d` for a vendor estimate, which is a thirty-day total snapshotted on scrape day and must never be pro-rated into a requested period.'}, 'previous': {'type': ['number', 'null'], 'description': 'The same metric over the comparison window. Null when nothing was compared.'}, 'delta_pct': {'type': ['number', 'null'], 'description': 'Percentage change against `previous`. A base of zero reads +100% when the figure arrived and −100% when it went away, matching the console — so it is a convention at that end rather than a measured proportion, and the figures themselves are in `value` and `previous`. Null when there is nothing to compare, or when the two figures are not the same kind of claim (a modelled estimate against a measurement).'}, 'precision': {'enum': ['exact', 'bucketed', 'none'], 'type': 'string', 'description': '`exact` = the number is the number. `bucketed` = the source only said "under N"; read `upper_bound` and do not invent a midpoint. `none` = not known at all.'}, 'is_estimate': {'type': 'boolean', 'description': "True for a vendor model, false for a measurement. **Never compare a true against a false without saying so** — measured July against a rival's rolling-30-day model is a confident wrong answer that reads exactly like a right one."}, 'lower_bound': {'type': ['integer', 'null'], 'description': 'Floor of a bucketed figure, when the source claimed one.'}, 'upper_bound': {'type': ['integer', 'null'], 'description': 'Ceiling of a bucketed figure — "under 5,000" arrives as 5000.'}}}, 'description': 'Measured impressions, store views, downloads, sales and proceeds, each against the comparison period and each carrying where it came from.'}, 'coverage': {'type': 'object', 'properties': {'apps': {'type': 'integer', 'description': 'Own apps in scope.'}, 'excluded': {'type': 'array', 'items': {'type': 'integer'}, 'description': 'App ids left out for having no connection. Omitted, never counted as zero.'}, 'connected': {'type': 'integer', 'description': 'How many App Store Connect reports for.'}}, 'description': 'What the money covers. Quote it whenever `connected` is below `apps`.'}, 'by_country': {'type': 'array', 'items': {'type': 'object', 'required': ['key', 'label'], 'properties': {'key': {'type': 'string', 'description': 'Storefront code (`us`, `de`) for a country split, or the numeric traffic-source id for a source split.'}, 'label': {'type': 'string', 'description': 'What to call it in an answer — the country\'s name, or "App Store search" / "App Store browse" / "App referrer" and so on.'}, 'proceeds': {'type': ['number', 'null'], 'description': 'Proceeds in this row, in USD.'}, 'delta_pct': {'type': ['number', 'null'], 'description': 'Change in downloads against the comparison window. Null when nothing was compared, or when this row had no downloads to compare against.'}, 'downloads': {'type': ['number', 'null'], 'description': 'Downloads in this row.'}, 'share_pct': {'type': ['number', 'null'], 'description': "This row's share of the split's own downloads, not of the grand total. Apple names only the storefronts it chooses to per metric, so the rows can fall short of the total — taking a share against the total would leave a gap nobody can explain."}, 'conversion': {'type': ['number', 'null'], 'description': 'Downloads over impressions for this row, as a percentage.'}, 'impressions': {'type': ['number', 'null'], 'description': 'Impressions in this row.'}, 'store_views': {'type': ['number', 'null'], 'description': 'Product page views in this row — the listing opened, not merely shown.'}}}, 'description': 'Biggest storefronts by downloads. Rows need not add up to the total.'}, 'data_through': {'type': ['string', 'null'], 'description': 'Last day App Store Connect reported. Quote `window`, not the request, when this is earlier than the period asked for.'}}, 'description': 'The measured half. **Null when the account has no apps at all**, and present with null figures when it has apps but no App Store Connect connection — those are different answers, and the caveats say which.'}, 'comparison_window': {'type': ['object', 'null'], 'required': ['from', 'to', 'days'], 'properties': {'to': {'type': 'string', 'description': 'Last day of the comparison period.'}, 'days': {'type': 'integer', 'description': 'Its length in days.'}, 'from': {'type': 'string', 'description': 'First day of the comparison period.'}}, 'description': 'What everything here is read against. Null when `compare` was `none`.'}}}

{'type': 'object', 'properties': {'include_hidden': {'type': 'boolean', 'description': 'Also return apps the owner has set aside. Default true, because they are still tracked and still answerable — each one is marked `hidden: true`, and they must be left out of portfolio totals. Set false for just the working portfolio.'}, 'include_competitors': {'type': 'boolean', 'description': "Also return the rival apps tracked under this account's apps, each marked `is_competitor`. Default false: including them makes any portfolio total wrong, and get_competitors is the tool that answers questions about them."}}}

{'type': 'object', 'required': ['plan', 'connection', 'focus_countries', 'count', 'apps'], 'properties': {'apps': {'type': 'array', 'items': {'type': 'object', 'required': ['app_id', 'is_competitor', 'hidden', 'unreleased', 'connected', 'stale'], 'properties': {'icon': {'type': ['string', 'null'], 'description': 'Absolute URL of the app icon.'}, 'name': {'type': ['string', 'null'], 'description': 'The app\'s title **as published in `country`** — the string a shopper in that storefront reads, which is also the string Apple indexes. It is not a translation of one canonical name: an app localised for Mexico has a different title there, and `get_app(country: "mx")` returning the US one is what makes an agent report a localised app as "not localized". Falls back to the app\'s canonical name when this storefront has not been crawled yet, and is null only while a freshly imported app is still being processed.'}, 'price': {'type': ['number', 'null'], 'description': "Download price in `country`, in that storefront's own currency and in major units — 9.99, never 999. 0 means free, which is what most apps are; `currency` names the money. Null when this storefront has no listing on file."}, 'stale': {'type': 'boolean', 'description': "True when the lag is past what Apple's delay explains. A stale app's recent numbers are not a quiet fortnight, they are a gap — say so instead of reporting a decline."}, 'store': {'enum': ['apple', 'google'], 'type': ['string', 'null'], 'description': 'Which store the app belongs to.'}, 'app_id': {'type': 'integer', 'description': 'Apptail app ID. This is the `app_id` every other tool expects.'}, 'hidden': {'type': 'boolean', 'description': 'True when the owner has set this app aside. It is still tracked and still crawled, but it is left out of every portfolio total in the console — so leave it out of yours, or say that you did not.'}, 'country': {'type': ['string', 'null'], 'description': 'Storefront the metrics below were read from. Defaults to `primary_country`.'}, 'is_mine': {'type': ['boolean', 'null'], 'description': 'True when this is one of the asking account\'s own apps. Null when the call carried no account — get_top_charts answers without a token — which is "not known here", not "no".'}, 'version': {'type': ['string', 'null'], 'description': 'Latest published version string.'}, 'currency': {'type': ['string', 'null'], 'description': 'ISO code of the currency `price` is in, derived from `country`. A price without it is a number, not an amount — several storefronts print a "$" and mean different money.'}, 'subtitle': {'type': ['string', 'null'], 'description': 'The subtitle under the title in `country` — thirty characters Apple indexes as heavily as the title, and the field most competitors leave generic. Null when the storefront listing has none, which is itself worth saying: an empty subtitle is unspent keyword weight.'}, 'bundle_id': {'type': ['string', 'null'], 'description': 'Store bundle identifier, e.g. "com.burbn.instagram".'}, 'connected': {'type': 'boolean', 'description': 'True when App Store Connect reports for this app. Only a connected app has measured impressions, downloads, sales or proceeds — get_performance returns them, and returns nothing for the rest rather than a zero.'}, 'unreleased': {'type': 'boolean', 'description': 'True when App Store Connect lists this app but no storefront does yet — a pre-release app the owner is preparing. Keywords, competitors, markets and SERPs all work for it; its own rank is -1 everywhere, and it has no ratings, reviews, listing or first-party figures. Treat every missing number as "not launched", never as a fault or a decline. The console switches it over the night it appears on a storefront.'}, 'console_url': {'type': ['string', 'null'], 'description': "Where to open this app in the AppTail console — the owner's own dashboard when `is_mine`, the research view otherwise. Null where this environment serves no console. End an answer about an app with it."}, 'apple_app_id': {'type': ['integer', 'null'], 'description': "Apple's own numeric app ID, as it appears in App Store URLs. Not interchangeable with `app_id`."}, 'data_through': {'type': ['string', 'null'], 'description': 'Last day Apple reported for this app. Null when it never has, which for a connection made today is normal and for an older one is a fault.'}, 'rating_count': {'type': ['integer', 'null'], 'description': 'Number of ratings in `country`.'}, 'data_lag_days': {'type': ['integer', 'null'], 'description': "How many days behind today that is. One or two is Apple's normal delay; more is worth mentioning before quoting recent figures."}, 'is_competitor': {'type': 'boolean', 'description': "True when this row is a rival tracked under one of the account's apps rather than an app of its own. **Never include one in a portfolio total.** False on every row unless `include_competitors` was set."}, 'rating_average': {'type': ['number', 'null'], 'description': 'Mean star rating (1-5) in `country`. Null if the app has no ratings there yet.'}, 'primary_country': {'type': ['string', 'null'], 'description': 'Lowercase ISO country code of the app\'s main storefront, e.g. "us".'}, 'primary_category': {'type': ['integer', 'null'], 'description': 'Store category ID. Pass this as `category` to get_top_charts.'}, 'listing_storefronts': {'type': 'array', 'items': {'type': 'string'}, 'description': 'One storefront per language the listing is localized in, `primary_country` first, e.g. ["ru", "us"]. An app published in two languages is searched for in two storefronts; keyword discovery and tracking are per storefront, so cover each of these rather than only `primary_country`.'}, 'competitor_of_app_id': {'type': ['integer', 'null'], 'description': "When `is_competitor` is true, the `app_id` of the account's own app it competes with."}, 'is_tracked_competitor': {'type': ['boolean', 'null'], 'description': 'True when the account already tracks this app as a competitor of one of theirs. False on a high-ranking rival is a suggestion worth making: add_competitors starts watching it. Null when the call carried no account.'}, 'primary_category_name': {'type': ['string', 'null'], 'description': 'Human-readable name of `primary_category`, e.g. "Health Fitness".'}}}, 'description': "The account's apps. `app_id` here is what every other tool takes; the numeric id in an App Store URL is `apple_app_id` and will not work."}, 'plan': {'type': 'object', 'required': ['key', 'name', 'apps', 'keywords_per_app', 'competitors_per_app', 'features'], 'properties': {'key': {'type': 'string', 'description': '`free`, `starter` or `pro`.'}, 'apps': {'type': 'object', 'required': ['used', 'limit'], 'properties': {'used': {'type': 'integer', 'description': 'Own apps tracked, hidden ones included.'}, 'limit': {'type': 'integer', 'description': 'How many this plan allows. -1 means unlimited.'}}, 'description': 'The tracked-apps ceiling.'}, 'name': {'type': 'string', 'description': 'What the plan is called to a customer.'}, 'features': {'type': 'object', 'required': ['advanced_metrics', 'developer_emails', 'history_months'], 'properties': {'history_months': {'type': 'integer', 'description': 'How far back rating history is kept for this plan.'}, 'advanced_metrics': {'type': 'boolean', 'description': 'Whether the ratings, charts and popularity sections of get_app are available. False on the free plan, where they are refused.'}, 'developer_emails': {'type': 'boolean', 'description': 'Whether developer contact addresses are returned.'}}, 'description': 'What the plan includes at all, as opposed to how much of it.'}, 'keywords_per_app': {'type': 'object', 'required': ['limit'], 'properties': {'limit': {'type': 'integer', 'description': 'Tracked keywords allowed per app. -1 means unlimited.'}}, 'description': 'The ceiling add_keywords enforces. Check it before adding a long list — the call is refused as a whole if the batch would exceed it.'}, 'competitors_per_app': {'type': 'object', 'required': ['limit'], 'properties': {'limit': {'type': 'integer', 'description': 'Tracked competitors allowed per app. -1 means unlimited.'}}, 'description': 'The ceiling add_competitor enforces.'}}, 'description': 'The plan and its ceilings, read from the services that enforce them — so a refusal cannot disagree with this. Tell the user what was capped rather than working around a limit.'}, 'count': {'type': 'integer', 'description': 'Number of apps returned.'}, 'connection': {'type': 'object', 'required': ['status', 'severity', 'headline', 'detail', 'apps_total', 'apps_connected'], 'properties': {'action': {'type': ['string', 'null'], 'description': '`connect`, `reconnect`, `wait`, or null when there is nothing to do.'}, 'detail': {'type': 'string', 'description': 'What it means, and what to do about it if anything.'}, 'status': {'type': 'string', 'description': '`healthy`, `partial`, `none`, `pending`, `failed` or `stale`. `pending` means the owner has said they invited AppTail into their developer account and Apple has not listed it yet — a normal wait of minutes to a day, not a fault and not something to advise about.'}, 'headline': {'type': 'string', 'description': 'One line stating the state, written for a person.'}, 'severity': {'type': 'string', 'description': '`ok`, `warn` or `alert`. Anything but `ok` is worth saying before quoting first-party figures.'}, 'apps_total': {'type': 'integer', 'description': 'Apps the verdict speaks for — hidden ones excluded.'}, 'apps_connected': {'type': 'integer', 'description': 'How many of those Apple reports for.'}}, 'description': 'App Store Connect health for the account. A `failed` or `stale` connection looks exactly like a quiet fortnight in the numbers, which is why it is stated separately rather than left to be inferred. `none` means Apple has never been connected — impressions, page views, downloads and proceeds do not exist for this account and never did, so say that rather than reporting a decline; everything AppTail crawls itself (ranks, charts, reviews, ratings, releases, prices, markets) works exactly as it does for anybody else. `pending` is the same absence with a connection already on its way: repeat the wait, not the setup instructions.'}, 'data_through': {'type': ['string', 'null'], 'description': 'Most recent day App Store Connect reported anywhere in the account. Per-app dates are on each app, and they differ — one healthy app keeps this recent while another has been silent for weeks.'}, 'focus_countries': {'type': 'array', 'items': {'type': 'string'}, 'description': 'The storefronts this account actually watches, in its own order. Every console screen narrows to these. Narrow your answers to them too unless the user asks otherwise — an answer across all 122 storefronts buries the one they wanted.'}}}

{'type': 'object', 'required': ['app_id'], 'properties': {'app_id': {'type': 'integer', 'description': "Apptail app id. get_account for the user's own apps, search_apps for any other app in the store. Not the numeric id in an App Store URL (that is apple_app_id)."}, 'country': {'type': 'string', 'description': "Storefront to read the listing in (e.g. US, GB, DE). Defaults to the app's primary storefront. Title, subtitle, price, rating and screenshots all differ per storefront, so this changes the answer rather than filtering it — the `name` you get back is the title as published *there*, which for a localised app is not the title in any other market. `ratings.overall`, `ratings.by_country`, `ratings.history` and the `prices` section ignore it — they are every storefront — and `charts` is returned for all of them regardless."}, 'include': {'type': 'array', 'items': {'enum': ['ratings', 'charts', 'popularity', 'developer', 'versions', 'screenshots', 'prices'], 'type': 'string'}, 'description': 'Extra sections to read. Omit for the listing alone, which is the cheap answer. `ratings`, `charts` and `popularity` need a Starter or Pro plan and are refused by name without one — the rest are free. Ask for what the question needs and nothing else: each section is a query.'}, 'history_days': {'type': 'integer', 'description': 'With `include: ["ratings"]`, also return the rating and the vote count day by day, this many days back from today, **and how each storefront moved over that window** — `ratings_gained` and `rating_change` on every row of `ratings.by_country`. Capped at 365. Ask for it whenever the question is whether a rating is *moving* or *where* it is moving: an average slides for weeks before enough people write about it, and a cross-section cannot tell a market that has always been low from one that fell this month. Ignored without the `ratings` include.'}}}

{'type': 'object', 'required': ['app_id', 'includes'], 'properties': {'icon': {'type': ['string', 'null'], 'description': 'Absolute URL of the app icon.'}, 'name': {'type': ['string', 'null'], 'description': 'The app\'s title **as published in `country`** — the string a shopper in that storefront reads, which is also the string Apple indexes. It is not a translation of one canonical name: an app localised for Mexico has a different title there, and `get_app(country: "mx")` returning the US one is what makes an agent report a localised app as "not localized". Falls back to the app\'s canonical name when this storefront has not been crawled yet, and is null only while a freshly imported app is still being processed.'}, 'tier': {'type': ['integer', 'null'], 'description': 'Apptail activity tier for `country`: 1 = currently charting, 2 = shipped more than two updates in the last 180 days.'}, 'price': {'type': ['number', 'null'], 'description': "Download price in `country`, in that storefront's own currency and in major units — 9.99, never 999. 0 means free, which is what most apps are; `currency` names the money. Null when this storefront has no listing on file."}, 'store': {'enum': ['apple', 'google'], 'type': ['string', 'null'], 'description': 'Which store the app belongs to.'}, 'app_id': {'type': 'integer', 'description': 'Apptail app ID. This is the `app_id` every other tool expects.'}, 'charts': {'type': 'array', 'items': {'type': 'object', 'properties': {'country': {'type': ['string', 'null'], 'description': 'Lowercase ISO code of the storefront this chart belongs to, e.g. "us".'}, 'category': {'type': ['integer', 'null'], 'description': 'Store category ID of the chart. Pass as `category` to get_top_charts.'}, 'position': {'type': ['integer', 'null'], 'description': 'Rank in this chart, 1 = top.'}, 'chart_type': {'enum': ['free', 'paid', 'grossing'], 'type': ['string', 'null'], 'description': 'Which chart: top free, top paid, or top grossing.'}, 'category_name': {'type': ['string', 'null'], 'description': 'Human-readable name of `category`, e.g. "Health Fitness".'}}}, 'description': 'Charts the app currently ranks in, across all countries and categories. Present only with `include: ["charts"]`; empty means it charts nowhere.'}, 'prices': {'type': ['object', 'null'], 'properties': {'free_in': {'type': 'integer', 'description': 'Storefronts where the download price is 0.'}, 'paid_in': {'type': 'integer', 'description': 'Storefronts where it costs money. **Read this before calling an app free.** A listing that is free in most markets and paid in four is a pricing experiment, and it is the four that are worth asking about.'}, 'by_country': {'type': 'array', 'items': {'type': 'object', 'required': ['country'], 'properties': {'price': {'type': ['number', 'null'], 'description': 'Download price in this storefront, in its own currency and in major units — 9.99, never 999. 0 means free. Null means the listing carries no price, which is not the same as free.'}, 'country': {'type': 'string', 'description': 'Lowercase ISO code of the storefront, e.g. "us".'}, 'currency': {'type': ['string', 'null'], 'description': 'ISO code of the money `price` is in, derived from the storefront. Quote it with the number or do not quote the number.'}}}, 'description': 'Every storefront with a listing, dearest first, each with its own currency. A storefront that has never been crawled is absent rather than free — count `storefronts`, never assume 122.'}, 'storefronts': {'type': 'integer', 'description': 'How many storefronts have a listing on file. Not 122: it is what AppTail has crawled for this app.'}}, 'description': 'What the app costs to download, per storefront. Present only with `include: ["prices"]`. This is the download price alone: `has_inapps` says whether there is more to pay after that, and get_app does not return in-app purchase tiers.'}, 'country': {'type': ['string', 'null'], 'description': 'Storefront the metrics below were read from. Defaults to `primary_country`.'}, 'is_mine': {'type': ['boolean', 'null'], 'description': 'True when this is one of the asking account\'s own apps. Null when the call carried no account — get_top_charts answers without a token — which is "not known here", not "no".'}, 'ratings': {'type': ['object', 'null'], 'properties': {'history': {'type': 'array', 'items': {'type': 'object', 'required': ['date', 'ratings_count', 'storefronts'], 'properties': {'date': {'type': 'string', 'description': 'The day, `YYYY-MM-DD`.'}, 'rating': {'type': ['number', 'null'], 'description': 'Average rating on that day, 1–5. Vote-weighted across storefronts when no `country` was asked for.'}, 'storefronts': {'type': 'integer', 'description': 'How many storefronts the figures cover on that day. It grows as new markets are first crawled, so a jump here explains a jump in `ratings_count` that no user caused.'}, 'ratings_count': {'type': 'integer', 'description': 'Total ratings on that day. It is a running total, not an arrival count — the day-on-day difference is how many arrived, and the store reads the total itself.'}}}, 'description': 'Rating and vote count per day, oldest first, when `history_days` was sent — **every storefront pooled**, like `overall` above it and regardless of `country`. Empty otherwise, and empty for an app with fewer than two snapshots. `ratings_count` here is a running total: the day-on-day difference is how many arrived. A storefront is crawled on its own schedule, so each day carries every market at its last known reading rather than only the markets crawled that day; for one market on its own, read `ratings_gained` and `rating_change` on its `by_country` row.'}, 'overall': {'type': 'object', 'properties': {'rating': {'type': ['number', 'null'], 'description': "The app's rating across every storefront it has votes in, weighted by each one's vote count. Null when nobody has rated it anywhere — never 0, which on a five-point scale is the worst score there is."}, 'storefronts': {'type': 'integer', 'description': 'How many storefronts it pools.'}, 'ratings_count': {'type': 'integer', 'description': 'Total ratings behind that figure.'}}, 'description': '**The honest answer to "what is this app rated".** Quote this, then name the markets in `by_country` that disagree with it: 4.7 in the US and 3.1 in Germany is a Germany problem, and an answer that says "4.6" has hidden it.'}, 'by_country': {'type': 'array', 'items': {'type': 'object', 'required': ['country', 'ratings_count'], 'properties': {'rating': {'type': ['number', 'null'], 'description': 'Average rating in this storefront, 1–5. Computed from the star buckets below, so it always agrees with them.'}, 'country': {'type': 'string', 'description': 'Lowercase ISO code of the storefront, e.g. "us".'}, 'distribution': {'type': ['object', 'null'], 'properties': {'1': {'type': ['integer', 'null'], 'description': 'Number of 1-star ratings.'}, '2': {'type': ['integer', 'null'], 'description': 'Number of 2-star ratings.'}, '3': {'type': ['integer', 'null'], 'description': 'Number of 3-star ratings.'}, '4': {'type': ['integer', 'null'], 'description': 'Number of 4-star ratings.'}, '5': {'type': ['integer', 'null'], 'description': 'Number of 5-star ratings.'}}, 'description': 'Ratings split by star bucket in this storefront. Null where no split has been crawled for it.'}, 'rating_change': {'type': ['number', 'null'], 'description': "Change in this storefront's average across the same window, in stars — first reading against last, so −0.4 means it fell four tenths of a star. Null on the same terms as `ratings_gained`. Rank by this to find the market dragging `overall` down; a market that is low and did not move is not the one that changed."}, 'ratings_count': {'type': 'integer', 'description': 'How many ratings that average is over. This is the weight to use when combining storefronts — never average the averages.'}, 'ratings_gained': {'type': ['integer', 'null'], 'description': 'Ratings this storefront gained across the `history_days` window — its last vote count less its first. Negative where Apple reset the count on a release. Null without `history_days`, and null for a market crawled fewer than twice in the window: unknown, not zero. **This is where growth actually comes from** — a pooled gain of 4,000 that is one market is a different story from one spread over thirty.'}, 'movement_readings': {'type': ['integer', 'null'], 'description': 'How many daily snapshots the two figures above are measured between. AppTail crawls each storefront on its own schedule, so a market with 3 readings over 90 days has moved by three readings and not over a quarter — say so rather than reporting it beside a market with 90.'}}}, 'description': 'Every storefront with ratings, most-rated first, each with its own split — and, when `history_days` was sent, how it moved over that window. Where a rating problem is actually visible, and now where it started.'}, 'distribution': {'type': 'object', 'properties': {'1': {'type': ['integer', 'null'], 'description': 'Number of 1-star ratings.'}, '2': {'type': ['integer', 'null'], 'description': 'Number of 2-star ratings.'}, '3': {'type': ['integer', 'null'], 'description': 'Number of 3-star ratings.'}, '4': {'type': ['integer', 'null'], 'description': 'Number of 4-star ratings.'}, '5': {'type': ['integer', 'null'], 'description': 'Number of 5-star ratings.'}}, 'description': 'Star split in `country` alone. The narrow field, not the headline — see `overall`.'}, 'history_days': {'type': 'integer', 'description': 'Days of history actually read, after the cap.'}}, 'description': 'Present only when `ratings` is in `include` — a section you did not ask for is absent from the answer entirely, which is not the same as it being empty.'}, 'version': {'type': ['string', 'null'], 'description': 'Latest published version string.'}, 'currency': {'type': ['string', 'null'], 'description': 'ISO code of the currency `price` is in, derived from `country`. A price without it is a number, not an amount — several storefronts print a "$" and mean different money.'}, 'includes': {'type': 'array', 'items': {'type': 'string'}, 'description': 'The sections actually read. A section absent from this list is absent from the answer because nobody asked for it — which is not the same as it being empty.'}, 'subtitle': {'type': ['string', 'null'], 'description': 'The subtitle under the title in `country` — thirty characters Apple indexes as heavily as the title, and the field most competitors leave generic. Null when the storefront listing has none, which is itself worth saying: an empty subtitle is unspent keyword weight.'}, 'versions': {'type': ['object', 'null'], 'properties': {'count': {'type': 'integer', 'description': 'Releases returned.'}, 'total': {'type': 'integer', 'description': 'Releases on file.'}, 'releases': {'type': 'array', 'items': {'type': 'object', 'properties': {'version': {'type': ['string', 'null'], 'description': 'Version string as published, e.g. "4.12.1".'}, 'released_at': {'type': ['string', 'null'], 'description': 'Date it shipped (YYYY-MM-DD). Null for a row imported without one — not a same-day release.'}}}, 'description': 'Newest first.'}, 'truncated': {'type': 'boolean', 'description': 'True when the list is shorter than `total`.'}}, 'description': 'Release history. Present only with `include: ["versions"]`. Cadence is the one competitor signal readable straight off the store: four releases in six weeks then eight months of nothing is a team that moved on.'}, 'bundle_id': {'type': ['string', 'null'], 'description': 'Store bundle identifier, e.g. "com.burbn.instagram".'}, 'developer': {'type': ['object', 'null'], 'required': ['developer_id', 'categories', 'languages', 'top_storefronts', 'top_apps'], 'properties': {'url': {'type': ['string', 'null'], 'description': "Publisher's website."}, 'name': {'type': ['string', 'null'], 'description': 'Publisher name shown on the store listing.'}, 'store': {'enum': ['apple', 'google'], 'type': ['string', 'null'], 'description': 'Which store this publisher profile belongs to.'}, 'country': {'type': ['string', 'null'], 'description': 'Lowercase ISO code of the country the publisher is based in, e.g. "de". **Usually inferred** from the website\'s domain suffix and the languages their apps ship in, so it is a guess and can be absent or wrong. `top_storefronts` is the measured answer to "where are their users".'}, 'top_apps': {'type': 'array', 'items': {'type': 'object', 'required': ['app_id'], 'properties': {'icon': {'type': ['string', 'null'], 'description': 'Absolute URL of the app icon.'}, 'name': {'type': ['string', 'null'], 'description': 'The app\'s title **as published in `country`** — the string a shopper in that storefront reads, which is also the string Apple indexes. It is not a translation of one canonical name: an app localised for Mexico has a different title there, and `get_app(country: "mx")` returning the US one is what makes an agent report a localised app as "not localized". Falls back to the app\'s canonical name when this storefront has not been crawled yet, and is null only while a freshly imported app is still being processed.'}, 'price': {'type': ['number', 'null'], 'description': "Download price in `country`, in that storefront's own currency and in major units — 9.99, never 999. 0 means free, which is what most apps are; `currency` names the money. Null when this storefront has no listing on file."}, 'store': {'enum': ['apple', 'google'], 'type': ['string', 'null'], 'description': 'Which store the app belongs to.'}, 'app_id': {'type': 'integer', 'description': 'Apptail app ID. This is the `app_id` every other tool expects.'}, 'country': {'type': ['string', 'null'], 'description': 'Storefront the metrics below were read from. Defaults to `primary_country`.'}, 'is_mine': {'type': ['boolean', 'null'], 'description': 'True when this is one of the asking account\'s own apps. Null when the call carried no account — get_top_charts answers without a token — which is "not known here", not "no".'}, 'version': {'type': ['string', 'null'], 'description': 'Latest published version string.'}, 'currency': {'type': ['string', 'null'], 'description': 'ISO code of the currency `price` is in, derived from `country`. A price without it is a number, not an amount — several storefronts print a "$" and mean different money.'}, 'subtitle': {'type': ['string', 'null'], 'description': 'The subtitle under the title in `country` — thirty characters Apple indexes as heavily as the title, and the field most competitors leave generic. Null when the storefront listing has none, which is itself worth saying: an empty subtitle is unspent keyword weight.'}, 'bundle_id': {'type': ['string', 'null'], 'description': 'Store bundle identifier, e.g. "com.burbn.instagram".'}, 'console_url': {'type': ['string', 'null'], 'description': "Where to open this app in the AppTail console — the owner's own dashboard when `is_mine`, the research view otherwise. Null where this environment serves no console. End an answer about an app with it."}, 'apple_app_id': {'type': ['integer', 'null'], 'description': "Apple's own numeric app ID, as it appears in App Store URLs. Not interchangeable with `app_id`."}, 'rating_count': {'type': ['integer', 'null'], 'description': 'Number of ratings in `country`.'}, 'rating_average': {'type': ['number', 'null'], 'description': 'Mean star rating (1-5) in `country`. Null if the app has no ratings there yet.'}, 'primary_country': {'type': ['string', 'null'], 'description': 'Lowercase ISO country code of the app\'s main storefront, e.g. "us".'}, 'primary_category': {'type': ['integer', 'null'], 'description': 'Store category ID. Pass this as `category` to get_top_charts.'}, 'listing_storefronts': {'type': 'array', 'items': {'type': 'string'}, 'description': 'One storefront per language the listing is localized in, `primary_country` first, e.g. ["ru", "us"]. An app published in two languages is searched for in two storefronts; keyword discovery and tracking are per storefront, so cover each of these rather than only `primary_country`.'}, 'is_tracked_competitor': {'type': ['boolean', 'null'], 'description': 'True when the account already tracks this app as a competitor of one of theirs. False on a high-ranking rival is a suggestion worth making: add_competitors starts watching it. Null when the call carried no account.'}, 'primary_category_name': {'type': ['string', 'null'], 'description': 'Human-readable name of `primary_category`, e.g. "Health Fitness".'}}}, 'description': "The publisher's most prominent apps, most prominent first. Capped, so may be shorter than `apps_active_count`."}, 'languages': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Lowercase language codes their apps are most often localised into, widest first, capped at 5.'}, 'team_size': {'type': ['integer', 'null'], 'description': 'Reported headcount for the company behind the publisher. **Modelled by a third party and absent for most publishers** — null means nobody has told us, never "no employees".'}, 'truncated': {'type': 'boolean', 'description': 'True when `top_apps` is shorter than `apps_matched`. Say the portfolio is a sample rather than presenting it as the whole catalogue.'}, 'apps_shown': {'type': 'integer', 'description': 'Apps returned in `top_apps`.'}, 'categories': {'type': 'array', 'items': {'type': 'object', 'properties': {'apps': {'type': 'integer', 'description': 'How many of their apps sit in it.'}, 'name': {'type': 'string', 'description': 'Store category.'}}}, 'description': 'What they build, biggest first, capped at 5. Empty when no category is on file.'}, 'legal_name': {'type': ['string', 'null'], 'description': 'Registered legal entity behind the publisher, when known.'}, 'revenue_30d': {'type': ['integer', 'null'], 'description': "**Modelled** 30-day worldwide gross revenue for the whole portfolio, in USD — what the store charged, before Apple's commission. Same summation and the same caveat as `downloads_30d`. Never present this beside a first-party figure without saying which is which."}, 'reviews_90d': {'type': ['integer', 'null'], 'description': 'Written reviews first seen in the last 90 days, portfolio-wide. The momentum figure: a large `reviews_total` with a near-zero figure here is a publisher coasting on an old hit.'}, 'apps_matched': {'type': 'integer', 'description': 'Apps this publisher has on file in total.'}, 'developer_id': {'type': 'integer', 'description': 'Apptail developer ID. This is the `developer_id` other tools expect.'}, 'downloads_30d': {'type': ['integer', 'null'], 'description': "**Modelled** 30-day worldwide downloads for the whole portfolio — the per-app estimates added up. Nobody sells a publisher-level figure, so read `estimate_apps_covered` before quoting this: a total over 6 of a studio's 40 apps is a sample, not their downloads. Null means nothing in the portfolio is covered, never that they have none. Apps too small for the vendor to size are left out too — see `estimate_apps_bucketed`."}, 'ratings_total': {'type': ['integer', 'null'], 'description': 'Vote counts summed over every app and every storefront. A size, not a score — never average it against a rating.'}, 'reviews_total': {'type': ['integer', 'null'], 'description': 'Written reviews AppTail holds across the whole portfolio.'}, 'top_storefronts': {'type': 'array', 'items': {'type': 'object', 'properties': {'apps': {'type': 'integer', 'description': 'Their apps rated in it.'}, 'country': {'type': 'string', 'description': 'Lowercase storefront code.'}, 'ratings': {'type': 'integer', 'description': 'Vote counts summed over those apps.'}}}, 'description': "Where the portfolio's ratings actually come from, biggest first. **Measured, unlike `country`** — use this to say which markets a publisher is strong in. Empty when none of their apps has a vote count on file."}, 'apps_total_count': {'type': ['integer', 'null'], 'description': 'Apps of theirs AppTail is crawling, as of the last profile refresh (up to a week old). Not "apps ever published" — a delisted app drops out of this. The exact current figure is `apps_matched` on the surfaces that return it.'}, 'apps_active_count': {'type': ['integer', 'null'], 'description': 'Of those, how many shipped an update in the last 180 days. **This is a maintenance figure, not a listing one**: the gap between it and `apps_total_count` is how much of the portfolio has been left alone.'}, 'first_released_at': {'type': ['string', 'null'], 'description': 'Date (YYYY-MM-DD) their oldest app was first released — how long they have been publishing.'}, 'recent_released_at': {'type': ['string', 'null'], 'description': 'Date (YYYY-MM-DD) anything in the portfolio last shipped an update. The single best answer to "are they still active".'}, 'store_developer_id': {'type': ['integer', 'null'], 'description': "The store's own publisher ID, as it appears in store URLs. Not interchangeable with `developer_id`."}, 'estimate_apps_total': {'type': ['integer', 'null'], 'description': 'How many apps the sum was attempted over. Equal to `estimate_apps_covered` when every app is covered.'}, 'updates_per_app_180d': {'type': ['number', 'null'], 'description': 'Mean releases per app over the last 180 days. Around 0 is a back catalogue; above ~6 is a team shipping every few weeks.'}, 'estimate_apps_covered': {'type': ['integer', 'null'], 'description': "How many of the publisher's apps the two figures above actually cover, out of `estimate_apps_total`. Uncovered apps are left out of the sum rather than counted as zero, so this is the denominator that makes the totals readable."}, 'estimate_apps_bucketed': {'type': ['integer', 'null'], 'description': 'How many covered apps the vendor would only bound rather than size — the ones it reports as "under 1,000" or "under 5,000" because they are below its modelling floor. **They contribute nothing to `downloads_30d` and `revenue_30d`**, so when this is above zero the two totals are floors: say "at least" rather than reporting them as the portfolio.'}}, 'description': 'The publisher and its portfolio — with the cap on `top_apps` declared. Present only with `include: ["developer"]`; null there when AppTail holds no profile for the publisher.'}, 'has_inapps': {'type': ['boolean', 'null'], 'description': 'Whether the app offers in-app purchases.'}, 'popularity': {'type': ['object', 'null'], 'required': ['top1_keywords', 'top10_keywords', 'top30_keywords', 'top100_keywords', 'top10_chart_count', 'top30_chart_count', 'top100_chart_count'], 'properties': {'top1_keywords': {'type': 'integer', 'description': 'Tracked keywords the app ranks #1 for.'}, 'top10_keywords': {'type': 'integer', 'description': 'Tracked keywords the app ranks in the top 10 for.'}, 'top30_keywords': {'type': 'integer', 'description': 'Tracked keywords the app ranks in the top 30 for.'}, 'top100_keywords': {'type': 'integer', 'description': 'Tracked keywords the app ranks in the top 100 for.'}, 'top10_chart_count': {'type': 'integer', 'description': 'Category charts the app sits in the top 10 of.'}, 'top30_chart_count': {'type': 'integer', 'description': 'Category charts the app sits in the top 30 of.'}, 'top100_chart_count': {'type': 'integer', 'description': 'Category charts the app sits in the top 100 of.'}}, 'description': 'Organic reach in `country`. Present only with `include: ["popularity"]`, and **null there when no storefront could be resolved** — a key that is present and null means "asked for, nothing to read", which an absent key does not.'}, 'seller_url': {'type': ['string', 'null'], 'description': "Publisher's marketing website."}, 'console_url': {'type': ['string', 'null'], 'description': "Where to open this app in the AppTail console — the owner's own dashboard when `is_mine`, the research view otherwise. Null where this environment serves no console. End an answer about an app with it."}, 'screenshots': {'type': ['object', 'null'], 'properties': {'urls': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Screenshot URLs in store order. Empty when none have been captured for this storefront.'}, 'country': {'type': ['string', 'null'], 'description': 'Storefront these were captured from.'}}, 'description': 'Present only with `include: ["screenshots"]`, and null there when no storefront could be resolved.'}, 'support_url': {'type': ['string', 'null'], 'description': 'Support page URL.'}, 'apple_app_id': {'type': ['integer', 'null'], 'description': "Apple's own numeric app ID, as it appears in App Store URLs. Not interchangeable with `app_id`."}, 'developer_id': {'type': ['integer', 'null'], 'description': 'Apptail developer ID. Pass this as `developer_id` to get_developer_info. Null if we hold no profile for the publisher.'}, 'rating_count': {'type': ['integer', 'null'], 'description': 'Number of ratings in `country`.'}, 'release_date': {'type': ['string', 'null'], 'description': 'Date the app first appeared in the store (YYYY-MM-DD).'}, 'rating_average': {'type': ['number', 'null'], 'description': 'Mean star rating (1-5) in `country`. Null if the app has no ratings there yet.'}, 'primary_country': {'type': ['string', 'null'], 'description': 'Lowercase ISO country code of the app\'s main storefront, e.g. "us".'}, 'primary_category': {'type': ['integer', 'null'], 'description': 'Store category ID. Pass this as `category` to get_top_charts.'}, 'privacy_policy_url': {'type': ['string', 'null'], 'description': 'Privacy policy URL.'}, 'store_developer_id': {'type': ['integer', 'null'], 'description': "The store's own publisher ID, as it appears in store URLs. Not interchangeable with `developer_id`."}, 'listing_storefronts': {'type': 'array', 'items': {'type': 'string'}, 'description': 'One storefront per language the listing is localized in, `primary_country` first, e.g. ["ru", "us"]. An app published in two languages is searched for in two storefronts; keyword discovery and tracking are per storefront, so cover each of these rather than only `primary_country`.'}, 'is_tracked_competitor': {'type': ['boolean', 'null'], 'description': 'True when the account already tracks this app as a competitor of one of theirs. False on a high-ranking rival is a suggestion worth making: add_competitors starts watching it. Null when the call carried no account.'}, 'primary_category_name': {'type': ['string', 'null'], 'description': 'Human-readable name of `primary_category`, e.g. "Health Fitness".'}, 'current_version_release_date': {'type': ['string', 'null'], 'description': 'Date the current version shipped (YYYY-MM-DD). Useful as an update-cadence signal.'}}}

{'type': 'object', 'required': ['app_id'], 'properties': {'app_id': {'type': 'integer', 'description': 'Apptail app id for one of YOUR apps — get it from get_account. Not the numeric id in an App Store URL (that is apple_app_id).'}}}

{'type': 'object', 'required': ['app_id', 'count', 'limit', 'competitors', 'suggested'], 'properties': {'count': {'type': 'integer', 'description': 'Number of competitors returned.'}, 'limit': {'type': 'integer', 'description': 'How many competitors this plan allows per app. -1 means unlimited.'}, 'app_id': {'type': 'integer', 'description': 'The app these rivals are tracked against.'}, 'remaining': {'type': ['integer', 'null'], 'description': 'Slots left before add_competitors is refused. Null when the plan is unlimited.'}, 'suggested': {'type': 'array', 'items': {'type': 'object', 'required': ['app_id', 'terms', 'sample_terms', 'source'], 'properties': {'name': {'type': ['string', 'null'], 'description': "The app's name."}, 'terms': {'type': 'integer', 'description': "How many of the app's corpus terms this rival sits in the top ten for, over the last two weeks. Zero on a `similar` row. This is the number the list is sorted by: a rival on five pages is a stronger suggestion than one on one."}, 'app_id': {'type': 'integer', 'description': 'Apptail app id. Pass it to add_competitors to track it, or to get_app for the listing.'}, 'source': {'enum': ['serp', 'similar'], 'type': 'string', 'description': "`serp` — seen in the top ten of the app's terms, which is the evidence `terms` counts. `similar` — the App Store lists it beside the app and no results page has shown it: a weaker reason, appended only when the pages named fewer rivals than asked for."}, 'bundle_id': {'type': ['string', 'null'], 'description': 'Bundle identifier.'}, 'best_place': {'type': ['integer', 'null'], 'description': 'Its highest place among those terms. Null on a `similar` row.'}, 'sample_terms': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Up to three of the terms it ranks best on — name them when recommending it, so the owner can see why.'}}}, 'description': 'Rivals worth tracking that are not on the list, strongest evidence first: apps in the top ten of the terms this app competes on (tracked, already ranked for, or read off its listing when it has neither), never the account\'s own apps, never one already tracked, never one hidden from the Landscape. Offer them with their `sample_terms`; add with add_competitors only when asked. Empty when the app has nothing to derive from — say that rather than "no competitors exist".'}, 'competitors': {'type': 'array', 'items': {'type': 'object', 'required': ['app_id'], 'properties': {'icon': {'type': ['string', 'null'], 'description': 'Absolute URL of the app icon.'}, 'name': {'type': ['string', 'null'], 'description': 'The app\'s title **as published in `country`** — the string a shopper in that storefront reads, which is also the string Apple indexes. It is not a translation of one canonical name: an app localised for Mexico has a different title there, and `get_app(country: "mx")` returning the US one is what makes an agent report a localised app as "not localized". Falls back to the app\'s canonical name when this storefront has not been crawled yet, and is null only while a freshly imported app is still being processed.'}, 'price': {'type': ['number', 'null'], 'description': "Download price in `country`, in that storefront's own currency and in major units — 9.99, never 999. 0 means free, which is what most apps are; `currency` names the money. Null when this storefront has no listing on file."}, 'store': {'enum': ['apple', 'google'], 'type': ['string', 'null'], 'description': 'Which store the app belongs to.'}, 'app_id': {'type': 'integer', 'description': 'Apptail app ID. This is the `app_id` every other tool expects.'}, 'country': {'type': ['string', 'null'], 'description': 'Storefront the metrics below were read from. Defaults to `primary_country`.'}, 'is_mine': {'type': ['boolean', 'null'], 'description': 'True when this is one of the asking account\'s own apps. Null when the call carried no account — get_top_charts answers without a token — which is "not known here", not "no".'}, 'version': {'type': ['string', 'null'], 'description': 'Latest published version string.'}, 'currency': {'type': ['string', 'null'], 'description': 'ISO code of the currency `price` is in, derived from `country`. A price without it is a number, not an amount — several storefronts print a "$" and mean different money.'}, 'subtitle': {'type': ['string', 'null'], 'description': 'The subtitle under the title in `country` — thirty characters Apple indexes as heavily as the title, and the field most competitors leave generic. Null when the storefront listing has none, which is itself worth saying: an empty subtitle is unspent keyword weight.'}, 'bundle_id': {'type': ['string', 'null'], 'description': 'Store bundle identifier, e.g. "com.burbn.instagram".'}, 'console_url': {'type': ['string', 'null'], 'description': "Where to open this app in the AppTail console — the owner's own dashboard when `is_mine`, the research view otherwise. Null where this environment serves no console. End an answer about an app with it."}, 'apple_app_id': {'type': ['integer', 'null'], 'description': "Apple's own numeric app ID, as it appears in App Store URLs. Not interchangeable with `app_id`."}, 'rating_count': {'type': ['integer', 'null'], 'description': 'Number of ratings in `country`.'}, 'rating_average': {'type': ['number', 'null'], 'description': 'Mean star rating (1-5) in `country`. Null if the app has no ratings there yet.'}, 'primary_country': {'type': ['string', 'null'], 'description': 'Lowercase ISO country code of the app\'s main storefront, e.g. "us".'}, 'primary_category': {'type': ['integer', 'null'], 'description': 'Store category ID. Pass this as `category` to get_top_charts.'}, 'listing_storefronts': {'type': 'array', 'items': {'type': 'string'}, 'description': 'One storefront per language the listing is localized in, `primary_country` first, e.g. ["ru", "us"]. An app published in two languages is searched for in two storefronts; keyword discovery and tracking are per storefront, so cover each of these rather than only `primary_country`.'}, 'is_tracked_competitor': {'type': ['boolean', 'null'], 'description': 'True when the account already tracks this app as a competitor of one of theirs. False on a high-ranking rival is a suggestion worth making: add_competitors starts watching it. Null when the call carried no account.'}, 'primary_category_name': {'type': ['string', 'null'], 'description': 'Human-readable name of `primary_category`, e.g. "Health Fitness".'}}}, 'description': 'Apps tracked as competitors of the given app. Empty if none are tracked yet.'}, 'suggested_basis': {'type': ['object', 'null'], 'required': ['country', 'terms', 'terms_tracked', 'terms_ranked', 'terms_from_listing', 'terms_measured', 'terms_pending', 'total', 'truncated'], 'properties': {'terms': {'type': 'integer', 'description': 'Corpus size: how many terms the pages were read for.'}, 'total': {'type': 'integer', 'description': 'How many untracked apps the pages named in all, before the cap.'}, 'country': {'type': 'string', 'description': 'The storefront whose results pages were read. Suggestions are per storefront.'}, 'truncated': {'type': 'boolean', 'description': 'True when `suggested` is shorter than `total`. get_landscape has the whole niche.'}, 'terms_ranked': {'type': 'integer', 'description': 'Terms the app already holds a top-10 place for without tracking them.'}, 'terms_pending': {'type': 'integer', 'description': 'Terms queued for a crawl and not yet read. **Above zero means the list is partial and will grow** — say so, and offer to look again in a minute rather than presenting it as complete.'}, 'terms_tracked': {'type': 'integer', 'description': 'Of those, terms the account tracks for this app.'}, 'terms_measured': {'type': 'integer', 'description': 'Terms with a results page in the last two weeks — the ones `terms` on each row is counted out of.'}, 'terms_from_listing': {'type': 'integer', 'description': 'Terms a model read off the listing because the two above were too few. Zero when they were enough.'}}, 'description': "What the suggestions were derived from. Null when the app is not one of the account's own — a suggestion needs your terms to read."}}}

{'type': 'object', 'properties': {'to': {'type': 'string', 'description': 'End date, `YYYY-MM-DD`, inclusive. Send it alone and the window is the three years before it.'}, 'from': {'type': 'string', 'description': 'Start date, `YYYY-MM-DD`, inclusive. Overrides `period` when both are sent. Send it alone and the window runs to today.'}, 'sort': {'enum': ['movement', 'rank', 'volume', 'competition'], 'type': 'string', 'description': '`movement` (the default) puts terms that left the results first, then real drops by size — the top of the list is what to ask about. `rank` is best position first, `volume` is most searched (Apple popularity), `competition` is most crowded. **Every sort selects, so a capped list is never a sample**: a movement-sorted read of 15 terms returns 15 movers whatever the corpus did. Count from `movers` and `coverage`, never from the rows.'}, 'limit': {'type': 'integer', 'description': 'Max terms returned, after sorting. Default 100, capped at 300. The answer always says how many the corpus holds.'}, 'scope': {'enum': ['app', 'portfolio'], 'type': 'string', 'description': '`app` (the default) reads one app\'s corpus and needs `app_id`. `portfolio` reads every app the account owns and reports each term under whichever of them ranks best for it — that is the scope `include: ["shared"]` needs, and hidden apps are excluded from it.'}, 'app_id': {'type': 'integer', 'description': 'Apptail app id for one of YOUR apps — get_account lists them. Required for `scope: "app"`. Not the numeric id in an App Store URL (that is apple_app_id).'}, 'period': {'type': 'string', 'description': 'The window to report on. A calendar month as `2026-07`, a calendar year as `2026`, `last_month`, `this_month`, `last_year`, or a trailing window: `today`, `7d`, `14d`, `30d`, `90d`, `180d`, `365d`, `730d`, `1095d`. Defaults to `30d`. A calendar period is compared against the calendar period before it — July against June, not against the 31 days ending 30 June. Three years is the ceiling.'}, 'tag_id': {'type': 'integer', 'description': "Only keywords carrying this tag. Tag ids come back on the keywords in this tool's own output. Omit for the whole corpus."}, 'country': {'type': 'string', 'description': "Storefront to read ranks in (e.g. US, GB). Defaults to the app's primary storefront. Ranks only exist per storefront — the same term ranks differently in each — so one call answers for one market."}, 'include': {'type': 'array', 'items': {'enum': ['history', 'visibility', 'shared'], 'type': 'string'}, 'description': 'Extra blocks. `history` adds a day-by-day series per term, capped at 25 terms — pair it with `keyword_ids` for specific terms. `visibility` adds the daily top-1/3/10/30/50/100 counts and their change, which is the number that survives a corpus changing size. `shared` adds the terms two of your own apps are both on, and needs `scope: "portfolio"`.'}, 'contains': {'type': 'string', 'description': 'Only terms whose text carries this substring, matched case-insensitively and applied before the sort and the cap. This is how to ask about a term by name — "how is `mpg` doing" — without looking up its id first, and the only way to see a term that sits mid-table by movement and so never reaches the top of a sorted list.'}, 'keyword_ids': {'type': 'array', 'items': {'type': 'integer'}, 'description': 'Only these terms, by Apptail keyword id — from this tool\'s own output or discover_keywords. Ids the account does not track are still answered when the scope is one app, because "how is my app doing for this term" is a real question; the answer says so. Omit for the whole corpus.'}, 'compare_with': {'type': 'array', 'items': {'type': 'integer'}, 'description': 'Apptail app ids to measure on these same terms — from get_competitors or search_apps. Rivals are measured on YOUR corpus, not theirs. At most 5 are used and the answer names which; send the ones that matter first.'}}}

{'type': 'object', 'required': ['scope', 'app_ids', 'country', 'window', 'sort', 'count', 'total', 'truncated', 'keywords', 'movers', 'coverage', 'shared', 'compared_app_ids', 'compare_truncated', 'caveats'], 'properties': {'sort': {'type': 'string', 'description': 'The order the list came back in.'}, 'count': {'type': 'integer', 'description': 'Terms returned.'}, 'scope': {'type': 'string', 'description': 'Which scope answered: `app` or `portfolio`.'}, 'total': {'type': 'integer', 'description': 'Terms the corpus holds in this storefront. Larger than `count` when the list was capped.'}, 'movers': {'type': 'object', 'properties': {'of': {'type': 'integer', 'description': 'Terms these four were counted over — the whole corpus after any filter, same as `total`. The four add up to it.'}, 'fell': {'type': 'integer', 'description': 'Terms that lost places or left the results in this window.'}, 'held': {'type': 'integer', 'description': 'Terms that were measured and ended where they started.'}, 'rose': {'type': 'integer', 'description': 'Terms that gained places or entered the results.'}, 'unmeasured': {'type': 'integer', 'description': 'Terms crawled on no day of the window. **Never folded into `held`** — a term nobody looked at has no rank to have held, and counting it as steady is a claim about our crawling dressed up as a claim about the app.'}}, 'description': 'The shape of the window in four numbers, **counted over every term in the corpus, not over the rows returned**. This is the only honest basis for a sentence about the corpus, and it is the one to lead with: 8 fell of 103 is a different week from 80 of 103, and a list of 15 rows cannot tell you which you are in.'}, 'shared': {'type': 'array', 'items': {'type': 'object', 'required': ['keyword_id', 'name', 'popularity_pending', 'apps', 'competing', 'same_category', 'spread', 'crawled_days'], 'properties': {'apps': {'type': 'array', 'items': {'type': 'object', 'properties': {'name': {'type': ['string', 'null'], 'description': 'Its name.'}, 'app_id': {'type': 'integer', 'description': "One of the account's own apps."}, 'position': {'type': 'integer', 'description': 'Its rank on the term, best first.'}, 'established': {'type': 'boolean', 'description': 'Whether it has held the term for at least half the days anybody was measured on it. An app that arrived this week has not taken anything from anybody yet.'}}}, 'description': "The account's apps on this term, best rank first. Always at least two — a term one app is on is not shared."}, 'name': {'type': 'string', 'description': 'The term itself.'}, 'spread': {'type': 'integer', 'description': 'Places between the best and worst of your apps on this term.'}, 'country': {'type': ['string', 'null'], 'description': 'Storefront the overlap is in. An overlap is per storefront, like every rank.'}, 'competing': {'type': 'boolean', 'description': "Whether these apps are actually taking traffic from each other: two of them inside the top ten, in the same category, both established. **False is the default reading** — this accuses somebody's own portfolio of a problem and is deliberately slow to. A false here with a spread of 40 is a portfolio covering more ground, not a conflict."}, 'keyword_id': {'type': 'integer', 'description': 'Apptail keyword id for the contested term.'}, 'popularity': {'type': ['integer', 'null'], 'description': 'Apple search popularity. Read it first: a bad overlap on a term nobody searches is not a finding, which is why the list is ordered by this within each group.'}, 'crawled_days': {'type': 'integer', 'description': 'Days in the window the term was crawled at all — what `established` was measured against. Never the days in the window: a skipped crawl would otherwise read as an app that keeps dropping out.'}, 'results_count': {'type': ['integer', 'null'], 'description': 'How many apps the store returns for the term.'}, 'same_category': {'type': 'boolean', 'description': 'Whether both apps sit in the same App Store category. A fuel tracker and a language app sharing "tracker" are two answers to two questions; an app whose category is unknown never counts as matching.'}, 'popularity_pending': {'type': 'boolean', 'description': 'Whether `popularity` is null because nobody has asked Apple about this term yet. True means queued, not zero and not "Apple has no number for it" - do not read a null popularity as low popularity while this is true.'}}}, 'description': 'Terms two of the account\'s own apps are both on, worst first, when `include: ["shared"]` was asked for at portfolio scope. Empty otherwise. Read `competing` before calling anything a conflict.'}, 'window': {'type': 'object', 'required': ['from', 'to', 'days', 'label'], 'properties': {'to': {'type': 'string', 'description': 'Last day covered, inclusive.'}, 'days': {'type': 'integer', 'description': 'Length of the window in days.'}, 'from': {'type': 'string', 'description': 'First day covered, inclusive.'}, 'label': {'type': 'string', 'description': 'What names this window — the period key, or `custom`.'}}, 'description': 'The window actually read, which is not always the one asked for: an inverted range is swapped, a range past three years is shortened, and first-party figures are pulled back to the last day App Store Connect reported. Quote these dates, not the requested ones.'}, 'app_ids': {'type': 'array', 'items': {'type': 'integer'}, 'description': 'The apps these ranks were read for.'}, 'caveats': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Sentences the reader has to hear before the list means what it looks like it means — a capped list and what it was selected for, terms nobody crawled, ranks that are weeks old, a history returned for only some rows, an include that did not apply. They carry the corpus-wide numbers in them so they survive being quoted alone. Pass these on; do not summarise them away.'}, 'country': {'type': 'string', 'description': 'Storefront the ranks were measured in.'}, 'coverage': {'type': 'object', 'properties': {'stale': {'type': 'integer', 'description': 'Measured terms whose last crawl is more than `stale_after_days` before the end of the window. Their `current_position` is that older reading — true, and not news.'}, 'terms': {'type': 'integer', 'description': 'Terms in the corpus after any filter.'}, 'ranked': {'type': 'integer', 'description': 'Terms the app was in the results for on at least one day.'}, 'measured': {'type': 'integer', 'description': 'Terms crawled on at least one day of the window.'}, 'unmeasured': {'type': 'integer', 'description': 'Terms crawled on no day at all. Their rank fields are unknowns, not zeroes.'}, 'last_measured_on': {'type': ['string', 'null'], 'description': 'The most recent day any term in this corpus was crawled, `YYYY-MM-DD`. Null when none were.'}, 'stale_after_days': {'type': 'integer', 'description': "The gap, in days, after which a term's last reading is counted as stale."}}, 'description': 'How much of this corpus was actually looked at in this window — the answer to "is this a drop or a gap in your crawling", which is otherwise unanswerable from ranks alone and has been guessed at wrongly. AppTail does not crawl every term every day, so sparse coverage on a few terms is normal; a corpus-wide `unmeasured` is not.'}, 'keywords': {'type': 'array', 'items': {'type': 'object', 'required': ['keyword_id', 'name', 'app_id', 'current_position', 'start_position', 'best_position', 'days_ranked', 'days_measured', 'competitors'], 'properties': {'tag': {'type': ['object', 'null'], 'properties': {'name': {'type': ['string', 'null'], 'description': 'Tag name.'}, 'color': {'type': ['string', 'null'], 'description': 'Tag colour as a hex code.'}}, 'description': "User-defined tag grouping this keyword, or null when untagged. Absent on portfolio-scoped calls: a tag belongs to one app's corpus, and two of your apps may tag the same term differently."}, 'name': {'type': 'string', 'description': 'The search term itself, lowercased.'}, 'store': {'enum': ['apple', 'google'], 'type': ['string', 'null'], 'description': 'Which store this keyword is tracked against.'}, 'app_id': {'type': 'integer', 'description': 'The app these ranks belong to. On a portfolio-scoped call a term is reported under whichever of your apps ranks best for it, so this varies row to row.'}, 'country': {'type': ['string', 'null'], 'description': 'Lowercase ISO code of the storefront this keyword is tracked in, e.g. "us". A term is tracked per country.'}, 'history': {'type': ['array', 'null'], 'items': {'type': 'object', 'required': ['date', 'measured'], 'properties': {'date': {'type': 'string', 'description': 'Day of the measurement, `YYYY-MM-DD`.'}, 'dynamics': {'type': ['object', 'null'], 'properties': {'delta': {'type': 'integer', 'description': 'How many places the rank moved since the previous measurement.'}, 'status': {'enum': ['new', 'up', 'down', 'out'], 'type': 'string', 'description': '"new" = entered the ranking, "out" = dropped out, "up"/"down" = moved.'}}, 'description': 'What changed against the previous **measured** day, skipping over days nobody crawled. Null when the rank held, when the day was not measured, and on the first measured day of the window — which is a starting point, not an arrival.'}, 'measured': {'type': 'boolean', 'description': "Whether the term was crawled on this day. False means AppTail has no reading for it — the gap is ours, not the app's. The crawler does not visit every term every day, so a sparse run of these is normal and says nothing about ranks."}, 'position': {'type': ['integer', 'null'], 'description': 'Rank on this day, 1 = top. **-1 means the term was searched and this app was not in the results** — a real absence. **Null means nobody crawled the term that day**, which is not a rank at all: do not count it as a drop, do not average it in, and do not read a run of them as an app leaving the results. `measured` beside it says which of the two this is.'}}}, 'description': 'One entry per day in the window, oldest first, when `include: ["history"]` was asked for and this row was inside the cap. **Each day is one of three things and the entry says which**: a rank, `position: -1` with `measured: true` for a day the term was searched and the app was absent, or `position: null` with `measured: false` for a day nobody crawled. Only the middle one is a departure. Null for the whole field means the history was not asked for or not returned for this row — never that the app did not rank.'}, 'movement': {'type': ['object', 'null'], 'properties': {'delta': {'type': 'integer', 'description': 'Places moved. Only meaningful when both ends are real ranks — for "new" and "out" it is measured against -1 and is not a number of places.'}, 'status': {'enum': ['new', 'up', 'down', 'out'], 'type': 'string', 'description': '"up" = a better (smaller) rank than at the start, "down" = worse, "new" = did not rank at the start and does now, "out" = the reverse.'}}, 'description': 'How the rank changed across the window. Null when it ended where it started — **and also when `days_measured` is 0**, where nothing was measured and there is no movement to report rather than a movement of nothing. Check `days_measured` before reading a null here as "steady".'}, 'keyword_id': {'type': 'integer', 'description': 'Apptail keyword ID. This is the `keyword_id` other tools expect.'}, 'popularity': {'type': ['integer', 'null'], 'description': 'Apple search popularity score (roughly 5-100). Higher means more searched. Null if not measured yet.'}, 'competitors': {'type': 'array', 'items': {'type': 'object', 'properties': {'name': {'type': ['string', 'null'], 'description': 'Its name.'}, 'app_id': {'type': 'integer', 'description': 'Apptail id of the rival.'}, 'position': {'type': 'integer', 'description': 'Its rank on the last crawled day, -1 for not ranking.'}}}, 'description': 'Where the apps named in `compare_with` stood on this same term, measured on the same day as `current_position`. Empty when nothing was compared.'}, 'console_url': {'type': ['string', 'null'], 'description': 'The keyword screen for the app this row belongs to.'}, 'days_ranked': {'type': 'integer', 'description': 'Days in the window the app was in the results at all. Read against `days_measured`: a term held on 3 of 30 days is not a term you hold.'}, 'best_position': {'type': 'integer', 'description': 'The best rank held at any point in the window. -1 when the app never ranked. Says whether a term was ever winnable, which neither end of the window can.'}, 'days_measured': {'type': 'integer', 'description': 'Days in the window the term was crawled at all — the honest denominator for `days_ranked`. Not the days in the window: the crawler does not visit every term every day, and measuring against days nobody looked would report a term that never moved as one that keeps dropping out. **0 means this term was never measured in the window**, so every rank field on the row is an unknown rather than a zero, and the term is counted in `movers.unmeasured` rather than in `held`.'}, 'results_count': {'type': ['integer', 'null'], 'description': 'How many apps the store returns for this term. A rough competition signal: higher means more crowded.'}, 'start_position': {'type': 'integer', 'description': 'Rank on the first day in the window the term was crawled, same scale. Compare with `current_position` for the direction of travel rather than a single snapshot.'}, 'current_position': {'type': 'integer', 'description': 'Rank on the last day in the window the term was crawled, 1 = top. **-1 means the app was not in the results on that day** — a real departure, not a gap — unless `days_measured` is 0, in which case nothing was measured and the -1 is an unknown. Not the last day of the window: most windows end on a day nobody crawled, and reading that literally reports every app as unranked. `last_measured_on` is the day this rank was read on; quote it whenever it is not recent.'}, 'last_measured_on': {'type': ['string', 'null'], 'description': "The last day in the window this term was crawled, `YYYY-MM-DD` — the day `current_position` was read on. Null when it was not crawled at all. **This is what tells a stale rank from a current one**: a term last measured three weeks before the window closed still reports the rank it held then, which is true and is not news. Say the date rather than presenting an old rank as today's."}}}, 'description': 'The terms, in the order `sort` asked for. **A selection, not a sample**: this is the top of a sorted list, so when `truncated` is true these rows are whatever the sort favoured — with the default sort, the worst movers and nothing else. Read them for which terms to ask about next; read `movers` and `coverage` for anything about the corpus. Empty when none are tracked in this storefront — track some with add_keywords.'}, 'truncated': {'type': 'boolean', 'description': 'True when `count` is below `total`. Say the list is partial rather than reporting it as the whole corpus.'}, 'visibility': {'type': ['object', 'null'], 'properties': {'top1': {'type': 'integer', 'description': 'Terms ranked 1.'}, 'top3': {'type': 'integer', 'description': 'Terms in the top 3 (includes top1).'}, 'top10': {'type': 'integer', 'description': 'Terms in the top 10.'}, 'top30': {'type': 'integer', 'description': 'Terms in the top 30.'}, 'top50': {'type': 'integer', 'description': 'Terms in the top 50.'}, 'change': {'type': 'object', 'properties': {'top1': {'type': ['integer', 'null']}, 'top3': {'type': ['integer', 'null']}, 'top10': {'type': ['integer', 'null']}, 'top30': {'type': ['integer', 'null']}, 'top50': {'type': ['integer', 'null']}, 'ranked': {'type': ['integer', 'null']}, 'top100': {'type': ['integer', 'null']}}, 'description': 'Change against the window before this one, per band. **Null means no earlier day was rolled up** — no history, which is not a change of nothing.'}, 'ranked': {'type': 'integer', 'description': 'Terms ranked anywhere at all.'}, 'top100': {'type': 'integer', 'description': 'Terms in the top 100.'}}, 'description': 'Terms in each band at the end of the window, cumulative, when `include: ["visibility"]` was asked for. **A state, not a sum** — the last day that has a row, because summing thirty days of "terms in the top ten" counts the same term thirty times. Null when it was not asked for, or when nothing has been rolled up for this app yet.'}, 'compared_app_ids': {'type': 'array', 'items': {'type': 'integer'}, 'description': 'The competitor ids actually measured. Shorter than what was sent when the cap or an unknown id dropped one.'}, 'compare_truncated': {'type': 'boolean', 'description': 'True when competitor ids were dropped for exceeding the cap of 5.'}}}

{'type': 'object', 'properties': {'date': {'type': 'string', 'description': 'The day to read, `YYYY-MM-DD`. Omit for the most recent crawl, which is the only mode that ever crawls live — naming a day is a question about the past and is answered from what was recorded. A day nobody crawled comes back empty with `crawled: false` rather than as an error; pick one from `crawled_days`, which the answer always returns.'}, 'limit': {'type': 'integer', 'description': 'How deep to read. Default 25, capped at 50. Below about 25 nobody is competing with you for the term.'}, 'country': {'type': 'string', 'description': 'Storefront for `keyword`, e.g. "us", "jp". Required with `keyword` and ignored with `keyword_id`, because a keyword already names its storefront. There is no worldwide search results page — every App Store search happens in one country.'}, 'keyword': {'type': 'string', 'description': 'The search term itself, for words a user typed rather than an id — "sleep tracker", "заметки". Needs `country`. A term nobody has ever looked up is created and the storefront is read live, so this answers for any search in the store and not only for terms Apptail already holds. Prefer `keyword_id` when you have one: it is the exact row, where words go through the store\'s own normalisation first.'}, 'keyword_id': {'type': 'integer', 'description': 'Apptail keyword id — from get_keywords or discover_keywords, or off a `rank.move` signal. The storefront is fixed by the keyword itself; a term is tracked per country. Give this OR `keyword` + `country`, not both.'}}}

{'type': 'object', 'required': ['keyword_id', 'keyword', 'crawled', 'refreshed', 'crawled_days', 'count', 'apps'], 'properties': {'apps': {'type': 'array', 'items': {'type': 'object', 'required': ['position', 'app_id', 'is_mine', 'is_tracked_competitor'], 'properties': {'name': {'type': ['string', 'null'], 'description': "The app's name in this storefront. Null while a freshly seen app is still being enriched — not a nameless app."}, 'app_id': {'type': 'integer', 'description': 'Apptail app id. Feed it straight into get_app_info or add_competitor.'}, 'rating': {'type': ['number', 'null'], 'description': 'Average rating in this storefront, 1-5. Null when nobody has rated it here.'}, 'is_mine': {'type': 'boolean', 'description': "True when this is one of the asking account's own apps."}, 'position': {'type': 'integer', 'description': 'Rank on this day, 1 = top of the results.'}, 'subtitle': {'type': ['string', 'null'], 'description': 'The subtitle under the name — thirty characters that Apple indexes and that most competitors leave generic.'}, 'developer': {'type': ['string', 'null'], 'description': 'Who publishes it.'}, 'rating_count': {'type': ['integer', 'null'], 'description': 'How many ratings that average is over. A 4.9 from eleven people and a 4.6 from ninety thousand are not comparable.'}, 'is_tracked_competitor': {'type': 'boolean', 'description': 'True when the account already tracks this app as a competitor. False on a high-ranking rival is a suggestion worth making: add_competitor starts watching it.'}}}, 'description': "The results in rank order, best first. `is_mine` marks the account's own apps and `is_tracked_competitor` marks rivals it already watches — a high-ranking app that is neither is worth suggesting they add."}, 'date': {'type': ['string', 'null'], 'description': 'The day actually read, which is the day asked for or the most recent crawl. Null when nothing has been crawled for this term.'}, 'count': {'type': 'integer', 'description': 'Apps returned.'}, 'country': {'type': ['string', 'null'], 'description': 'Storefront these results come from. Fixed by the keyword.'}, 'crawled': {'type': 'boolean', 'description': 'Whether that day had a crawl at all. False with an empty list means nobody measured, **not** that nobody ranked.'}, 'keyword': {'type': 'string', 'description': 'The search term itself.'}, 'refreshed': {'type': 'boolean', 'description': 'True when this call read the App Store rather than the database — a term looked up for the first time, or one whose last crawl was over a day old. False means these are stored results; `date` says which day they are from. Do not describe results as live unless this is true.'}, 'keyword_id': {'type': 'integer', 'description': 'The term that was read.'}, 'popularity': {'type': ['integer', 'null'], 'description': 'Apple search popularity for the term, roughly 5-100. Higher means more searched. Read it before calling a position valuable.'}, 'console_url': {'type': ['string', 'null'], 'description': 'Where this search is shown in the console, with the icons and screenshots this payload leaves out.'}, 'my_position': {'type': ['integer', 'null'], 'description': "The best rank held here by one of the account's own apps, or null when none of them are in these results. Null is not -1: it means no app of theirs appears in the depth that was read, which is not the same as being measured and absent."}, 'crawled_days': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Days in the last 30 that were crawled, newest first. Name one in `date` to see how the results looked then — comparing two days is what shows who took a place.'}, 'results_count': {'type': ['integer', 'null'], 'description': 'How many apps the store returns for this term in total. The results below are the top of that.'}}}

{'type': 'object', 'required': ['app_id'], 'properties': {'to': {'type': 'string', 'description': 'End date, `YYYY-MM-DD`, inclusive. Send it alone and the window is the three years before it.'}, 'from': {'type': 'string', 'description': 'Start date, `YYYY-MM-DD`, inclusive. Overrides `period` when both are sent. Send it alone and the window runs to today.'}, 'app_id': {'type': 'integer', 'description': 'Apptail app id for one of YOUR apps — get it from get_account. Not the numeric id in an App Store URL (that is apple_app_id).'}, 'period': {'type': 'string', 'description': 'The window to report on. A calendar month as `2026-07`, a calendar year as `2026`, `last_month`, `this_month`, `last_year`, or a trailing window: `today`, `7d`, `14d`, `30d`, `90d`, `180d`, `365d`, `730d`, `1095d`. Defaults to `30d`. A calendar period is compared against the calendar period before it — July against June, not against the 31 days ending 30 June. Three years is the ceiling.'}, 'country': {'type': 'string', 'description': "Storefront to read the niche in (e.g. US, GB). A niche exists per storefront and is never blended across them. Defaults to the first of the account's focus_countries this app is actually tracked in, then the app's primary storefront."}}}

{'type': 'object', 'required': ['app_id', 'country', 'window', 'terms', 'count', 'total', 'truncated', 'hidden_count', 'members', 'term_gap', 'caveats'], 'properties': {'count': {'type': 'integer', 'description': 'Members returned.'}, 'terms': {'type': 'integer', 'description': "How many terms defined this niche: the account's tracked terms for this app in this storefront, plus the terms the app already holds a top-10 position for. Every `terms` and `top10_terms` figure below is out of this."}, 'total': {'type': 'integer', 'description': 'Members the niche actually holds. Larger than `count` means the list was cut.'}, 'app_id': {'type': 'integer', 'description': 'The app whose niche this is.'}, 'window': {'type': 'object', 'properties': {'days': {'type': 'integer'}, 'label': {'type': 'string'}, 'compareLabel': {'type': 'string'}}, 'description': 'The window used, and what the change figures are measured against.'}, 'caveats': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Sentences the reader has to hear before the numbers mean what they look like they mean — a cut list, hidden rows, an unmeasurable gap, modelled sizes. Pass these on; do not summarise them away.'}, 'country': {'type': 'string', 'description': 'The storefront actually read, which may not be the one asked for.'}, 'members': {'type': 'array', 'items': {'type': 'object', 'required': ['app_id', 'is_mine', 'is_competitor', 'terms', 'top10_terms', 'rating_count', 'ratings_storefronts', 'ratings_gained_in', 'new_reviews', 'is_estimate', 'off_market'], 'properties': {'left': {'type': ['boolean', 'null'], 'description': 'True when this app ranked for at least one term in the previous window and none now. Null when no term was measured in both windows. `was_terms` says how much it held.'}, 'name': {'type': ['string', 'null'], 'description': "The app's name in this storefront. Null while a freshly seen app is still being enriched."}, 'share': {'type': ['number', 'null'], 'description': "Share of this corpus's search visibility, 0-100, and the figure the list is ordered by. Each (term, place) slot is weighted by how much evidence the term carries — a term Apple answers with one app is worth a twentieth of one it answers with twenty or more — and by how deep the place is, so #1 counts for roughly five times #10. Measured from our own daily ranks; no vendor model touches it. Null where nobody ranks at all."}, 'terms': {'type': 'integer', 'description': "How many of the landscape's terms this app ranked for at all, anywhere in the top 50, during the window."}, 'app_id': {'type': 'integer', 'description': 'Apptail app id. Feed it straight into get_app_info, get_app_reviews or add_competitors.'}, 'rating': {'type': ['number', 'null'], 'description': 'Average rating in this storefront, 1-5. Null when nobody has rated it here.'}, 'source': {'type': ['string', 'null'], 'description': 'Which source produced the size figures: `appstoreconnect`, `sensortower`, `appmagic`. Null when neither covers this app.'}, 'entered': {'type': ['boolean', 'null'], 'description': "True when this app ranked for none of these terms in the previous window and ranks for at least one now. **NULL means there was nothing to compare against** — no term was measured in both windows, which is the normal state of a market built inside this window. Null is not false and is certainly not true: do not report a new market's whole leaderboard as arrivals. Recomputed per window, so it cannot say which day it happened."}, 'is_mine': {'type': 'boolean', 'description': "True when this is one of the asking account's own apps."}, 'was_terms': {'type': ['integer', 'null'], 'description': 'How many terms this app held in the previous window. Null when it was absent then.'}, 'off_market': {'type': 'boolean', 'description': "The app is in these search results but not in this market: it shares no word with the corpus, sits in another category, and carries fifty times the median member's audience. All three are required, so this names padding (Instagram at #4 for `cyprus exam` in a thin storefront) rather than every large rival. Sorted last, never removed — report it as context, not as a competitor."}, 'is_estimate': {'type': 'boolean', 'description': "True when downloads_30d and revenue_30d are a third-party model rather than Apple's own figures. Decided per row, never per column: your connected app is measured and the row beside it is not. Say so when you report the numbers."}, 'new_reviews': {'type': 'integer', 'description': 'Reviews left during the window, in every storefront.'}, 'released_at': {'type': ['string', 'null'], 'description': 'First release, `YYYY-MM-DD`, as Apple gives it. What makes a rank readable: 4.9 on 30 votes and a rank that moved 40 places mean one thing for an app six weeks old and another for one six years old. The console marks anything inside 90 days as new. Null when the listing has never been crawled.'}, 'revenue_30d': {'type': ['integer', 'null'], 'description': 'Worldwide revenue over the same 30 days, in USD. Same provenance rule as downloads_30d, and the same two causes for null — see `revenue_30d_max`.'}, 'top10_terms': {'type': 'integer', 'description': 'How many of those terms the app actually owns — a top-10 position. This is the figure that moves and the one the list is sorted by; `terms` is reach, this is visibility.'}, 'last_updated': {'type': ['string', 'null'], 'description': "When the app's current version shipped, `YYYY-MM-DD`. The other half of `released_at`, and the one that separates a live rival from a listing: an app holding third place on a version it last shipped two years ago is not defending it. Null when we have never crawled a version date."}, 'rating_count': {'type': 'integer', 'description': 'How many ratings that average is over — the only size figure that exists for every app in the niche.'}, 'terms_change': {'type': ['integer', 'null'], 'description': 'Change in `terms` against the previous window of the same length. Null when the app was absent then, which is what `entered` reports.'}, 'top10_change': {'type': ['integer', 'null'], 'description': 'Change in `top10_terms` against the previous window, counted over the terms measured in BOTH windows so a corpus that grew cannot read as growth. The only growth number on this tool measured first-hand rather than modelled. Null when no term was measured in both.'}, 'downloads_30d': {'type': ['integer', 'null'], 'description': "Worldwide downloads over the last 30 days. Apple's measurement when this is a connected app of yours, a vendor's model otherwise — read `is_estimate`. Ignores the window: no vendor sells an estimate by window. **Null has two causes and `downloads_30d_max` separates them**: no source covers the app, or the vendor would only bound it. Never read null as zero."}, 'is_competitor': {'type': 'boolean', 'description': 'True when the account already tracks this app as a competitor of the app whose landscape this is. False on a stranger, which is most rows — the store put it here, nobody chose it.'}, 'ratings_total': {'type': ['integer', 'null'], 'description': 'Ratings the app holds across every storefront AppTail has a listing for, not only this one — `rating_count` above is this storefront alone. Null when no listing has been crawled; never 0 for unknown.'}, 'ratings_gained': {'type': ['integer', 'null'], 'description': "Ratings that arrived during the window — the half of a rating that moves, and what the store's own ranking reads. A rival gaining thousands a week is growing whatever its 4.6 says. Null when no storefront was crawled twice inside the window: one snapshot cannot measure a change."}, 'revenue_30d_max': {'type': ['integer', 'null'], 'description': 'The revenue ceiling for an app the vendor would only bound — "under $5,000". Set only when `revenue_30d` is null.'}, 'downloads_30d_max': {'type': ['integer', 'null'], 'description': 'The ceiling the vendor gave instead of a figure, for an app below its modelling floor — 1000 or 5000, depending on the vendor. Set only when `downloads_30d` is null, and then the honest sentence is "under 5,000 downloads", never a number. **Both null is a different state**: no vendor models this app at all, which is not the same as small.'}, 'ratings_gained_in': {'type': 'integer', 'description': "Storefronts `ratings_gained` was actually measured on. Lower than `ratings_storefronts` means the gain covers part of the app's markets — say so rather than reporting it as the whole."}, 'ratings_storefronts': {'type': 'integer', 'description': 'How many storefronts `ratings_total` pools.'}}}, 'description': "The niche, most of the account's terms owned first. `entered` and `left` mark this window's movers."}, 'app_name': {'type': ['string', 'null'], 'description': 'Its name.'}, 'term_gap': {'type': 'object', 'properties': {'missing': {'type': ['integer', 'null'], 'description': '`niche_terms` minus the ones already tracked. Null when `niche_terms` is null.'}, 'tracked': {'type': 'integer', 'description': 'Terms the account tracks for this app in this storefront.'}, 'truncated': {'type': 'boolean', 'description': 'True when the vocabulary read hit its cap, making `niche_terms` a floor rather than a total. Report it as "at least".'}, 'niche_terms': {'type': ['integer', 'null'], 'description': "Terms the apps in this niche hold a top-10 position for here, this window. NULL means it could not be measured — that is unknown, never zero. This is the niche's vocabulary, not the store's: it is a defensible denominator precisely because it is small."}, 'top_missing': {'type': 'array', 'items': {'type': 'object', 'required': ['keyword_id', 'term', 'rivals', 'best_position'], 'properties': {'term': {'type': 'string', 'description': 'The search term, as the storefront spells it.'}, 'rivals': {'type': 'integer', 'description': "How many apps in this niche hold a top-10 position for the term. This is what orders the list: six rivals is a hole in the account's corpus, one rival is that rival's experiment."}, 'keyword_id': {'type': 'integer', 'description': 'Apptail keyword id. Pass this to add_keywords — never the text, which re-resolves and can land on a different row.'}, 'popularity': {'type': ['integer', 'null'], 'description': "Apple's search popularity, roughly 5-100. Null means not measured yet, which is NOT the same as unpopular — do not report a null as low volume."}, 'best_position': {'type': 'integer', 'description': 'The best position any of them reached for it during the window.'}}}, 'description': 'The biggest holes, most rivals first. Pass `keyword_id` to add_keywords to start tracking one.'}}, 'description': "How much of the niche's vocabulary the account is not watching."}, 'truncated': {'type': 'boolean', 'description': 'True when `count` is less than `total`. Say the list is partial rather than presenting it as the whole niche.'}, 'console_url': {'type': ['string', 'null'], 'description': 'This landscape in the console, in this storefront.'}, 'hidden_count': {'type': 'integer', 'description': 'Apps the account owner has hidden from this landscape in the console. They are excluded from `members`, from the movers and from `term_gap` alike.'}}}

{'type': 'object', 'properties': {'to': {'type': 'string', 'description': 'End date, `YYYY-MM-DD`, inclusive. Send it alone and the window is the three years before it.'}, 'from': {'type': 'string', 'description': 'Start date, `YYYY-MM-DD`, inclusive. Overrides `period` when both are sent. Send it alone and the window runs to today.'}, 'query': {'type': 'string', 'description': 'A phrase to resolve into a market right now, e.g. "AI calorie tracking". Requires `countries`. Can persist shared keywords and search observations. No market is saved to your account — call save_market with the same phrase to keep it.'}, 'store': {'type': 'string', 'description': 'Read only this one storefront of a saved market. Omit for every storefront compared, which is where `overlap` and the contest range come from.'}, 'app_id': {'type': 'integer', 'description': 'Scopes `include: ["app_terms"]` to one app — an Apptail app id from `members`, `search_apps` or `get_landscape`. This is the audit trail for membership: it returns every (term, storefront) place that app holds in this market, how many days it held each, and which clause of the rule put it in `apps` or in `fringe`. Reach for it when the user disagrees with a market\'s membership, or asks why a particular app is or is not in the niche.'}, 'period': {'type': 'string', 'description': 'The window to report on. A calendar month as `2026-07`, a calendar year as `2026`, `last_month`, `this_month`, `last_year`, or a trailing window: `today`, `7d`, `14d`, `30d`, `90d`, `180d`, `365d`, `730d`, `1095d`. Defaults to `30d`. A calendar period is compared against the calendar period before it — July against June, not against the 31 days ending 30 June. Three years is the ceiling.'}, 'include': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Extra sections, each costing a query: `members` (the leaderboard), `corpus` (every term with why it is in), `movement` (who arrived and who left), `app_terms` (which terms ONE app holds here and whether that makes it a competitor — needs `app_id`). Ask for what the question needs.'}, 'countries': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Storefronts to ask the question in, ISO 3166-1 alpha-2 (e.g. ["US","GB","DE"]). Required with `query`. Each storefront gets its own corpus seeded from the same phrase; that is deliberate, and a phrase nobody searches in a storefront comes back with a thin corpus, which is itself the finding.'}, 'market_id': {'type': 'integer', 'description': 'Apptail market id for a market this account has saved — from list_markets. A saved market is a pure read: no crawling, sub-second. Send this OR `query`, not both.'}, 'budget_seconds': {'type': 'integer', 'description': 'How long a live `query` may spend crawling, shared across ALL storefronts rather than each. Default 5, max 30. It is rarely the binding limit — at most 12 terms are crawled per call whatever the clock says.'}, 'new_within_days': {'type': 'integer', 'description': 'Keep only apps FIRST RELEASED inside this many days — "what has launched into this niche lately". Applied to every app ranking for the corpus before the list is cut, so these are the new apps in the market and not the new apps among its leaders; a young app is rarely a leader yet, so filtering the leaderboard itself would answer nothing. Affects `members` only. `share` stays a share of the WHOLE market, which is the point of it. Not the same question as `movement`: that is who started ranking here, which is mostly apps that are not new at all.'}}}

{'type': 'object', 'required': ['status', 'storefront_count', 'terms', 'apps', 'fringe', 'apps_capped', 'size_covered', 'stale_terms', 'storefronts', 'window', 'truncated', 'pending_terms', 'pending_storefronts', 'caveats'], 'properties': {'apps': {'type': 'integer', 'description': "UNION: apps COMPETING in at least one storefront, counted ONCE however many they rank in. Competing means a top-10 place on at least one of this market's terms AND a top-50 place on at least two of them — one term is a coincidence and a place nobody scrolls to is not competition. Never the sum of the per-storefront counts: one app in three storefronts is one app. A FLOOR rather than a count when `apps_capped` is true. Everything else the store returned is in `fringe`."}, 'left': {'type': ['array', 'null'], 'items': {'type': 'object', 'required': ['app_id', 'is_mine', 'is_competitor', 'terms', 'top10_terms', 'rating_count', 'ratings_storefronts', 'ratings_gained_in', 'new_reviews', 'is_estimate', 'off_market', 'storefronts'], 'properties': {'left': {'type': ['boolean', 'null'], 'description': 'True when this app ranked for at least one term in the previous window and none now. Null when no term was measured in both windows. `was_terms` says how much it held.'}, 'name': {'type': ['string', 'null'], 'description': "The app's name in this storefront. Null while a freshly seen app is still being enriched."}, 'share': {'type': ['number', 'null'], 'description': "Share of this corpus's search visibility, 0-100, and the figure the list is ordered by. Each (term, place) slot is weighted by how much evidence the term carries — a term Apple answers with one app is worth a twentieth of one it answers with twenty or more — and by how deep the place is, so #1 counts for roughly five times #10. Measured from our own daily ranks; no vendor model touches it. Null where nobody ranks at all."}, 'terms': {'type': 'integer', 'description': "How many of the landscape's terms this app ranked for at all, anywhere in the top 50, during the window."}, 'app_id': {'type': 'integer', 'description': 'Apptail app id. Feed it straight into get_app_info, get_app_reviews or add_competitors.'}, 'rating': {'type': ['number', 'null'], 'description': 'Average rating in this storefront, 1-5. Null when nobody has rated it here.'}, 'source': {'type': ['string', 'null'], 'description': 'Which source produced the size figures: `appstoreconnect`, `sensortower`, `appmagic`. Null when neither covers this app.'}, 'entered': {'type': ['boolean', 'null'], 'description': "True when this app ranked for none of these terms in the previous window and ranks for at least one now. **NULL means there was nothing to compare against** — no term was measured in both windows, which is the normal state of a market built inside this window. Null is not false and is certainly not true: do not report a new market's whole leaderboard as arrivals. Recomputed per window, so it cannot say which day it happened."}, 'is_mine': {'type': 'boolean', 'description': "True when this is one of the asking account's own apps."}, 'was_terms': {'type': ['integer', 'null'], 'description': 'How many terms this app held in the previous window. Null when it was absent then.'}, 'off_market': {'type': 'boolean', 'description': "The app is in these search results but not in this market: it shares no word with the corpus, sits in another category, and carries fifty times the median member's audience. All three are required, so this names padding (Instagram at #4 for `cyprus exam` in a thin storefront) rather than every large rival. Sorted last, never removed — report it as context, not as a competitor."}, 'is_estimate': {'type': 'boolean', 'description': "True when downloads_30d and revenue_30d are a third-party model rather than Apple's own figures. Decided per row, never per column: your connected app is measured and the row beside it is not. Say so when you report the numbers."}, 'new_reviews': {'type': 'integer', 'description': 'Reviews left during the window, in every storefront.'}, 'released_at': {'type': ['string', 'null'], 'description': 'First release, `YYYY-MM-DD`, as Apple gives it. What makes a rank readable: 4.9 on 30 votes and a rank that moved 40 places mean one thing for an app six weeks old and another for one six years old. The console marks anything inside 90 days as new. Null when the listing has never been crawled.'}, 'revenue_30d': {'type': ['integer', 'null'], 'description': 'Worldwide revenue over the same 30 days, in USD. Same provenance rule as downloads_30d, and the same two causes for null — see `revenue_30d_max`.'}, 'storefronts': {'type': 'array', 'items': {'type': 'string'}, 'description': "Which of this market's storefronts the app ranks in. An app in five of six and absent from the sixth is a storefront somebody can ship into — that gap is the reading a single-storefront market cannot produce."}, 'top10_terms': {'type': 'integer', 'description': 'How many of those terms the app actually owns — a top-10 position. This is the figure that moves and the one the list is sorted by; `terms` is reach, this is visibility.'}, 'last_updated': {'type': ['string', 'null'], 'description': "When the app's current version shipped, `YYYY-MM-DD`. The other half of `released_at`, and the one that separates a live rival from a listing: an app holding third place on a version it last shipped two years ago is not defending it. Null when we have never crawled a version date."}, 'rating_count': {'type': 'integer', 'description': 'How many ratings that average is over — the only size figure that exists for every app in the niche.'}, 'terms_change': {'type': ['integer', 'null'], 'description': 'Change in `terms` against the previous window of the same length. Null when the app was absent then, which is what `entered` reports.'}, 'top10_change': {'type': ['integer', 'null'], 'description': 'Change in `top10_terms` against the previous window, counted over the terms measured in BOTH windows so a corpus that grew cannot read as growth. The only growth number on this tool measured first-hand rather than modelled. Null when no term was measured in both.'}, 'downloads_30d': {'type': ['integer', 'null'], 'description': "Worldwide downloads over the last 30 days. Apple's measurement when this is a connected app of yours, a vendor's model otherwise — read `is_estimate`. Ignores the window: no vendor sells an estimate by window. **Null has two causes and `downloads_30d_max` separates them**: no source covers the app, or the vendor would only bound it. Never read null as zero."}, 'is_competitor': {'type': 'boolean', 'description': 'True when the account already tracks this app as a competitor of the app whose landscape this is. False on a stranger, which is most rows — the store put it here, nobody chose it.'}, 'ratings_total': {'type': ['integer', 'null'], 'description': 'Ratings the app holds across every storefront AppTail has a listing for, not only this one — `rating_count` above is this storefront alone. Null when no listing has been crawled; never 0 for unknown.'}, 'ratings_gained': {'type': ['integer', 'null'], 'description': "Ratings that arrived during the window — the half of a rating that moves, and what the store's own ranking reads. A rival gaining thousands a week is growing whatever its 4.6 says. Null when no storefront was crawled twice inside the window: one snapshot cannot measure a change."}, 'revenue_30d_max': {'type': ['integer', 'null'], 'description': 'The revenue ceiling for an app the vendor would only bound — "under $5,000". Set only when `revenue_30d` is null.'}, 'downloads_30d_max': {'type': ['integer', 'null'], 'description': 'The ceiling the vendor gave instead of a figure, for an app below its modelling floor — 1000 or 5000, depending on the vendor. Set only when `downloads_30d` is null, and then the honest sentence is "under 5,000 downloads", never a number. **Both null is a different state**: no vendor models this app at all, which is not the same as small.'}, 'ratings_gained_in': {'type': 'integer', 'description': "Storefronts `ratings_gained` was actually measured on. Lower than `ratings_storefronts` means the gain covers part of the app's markets — say so rather than reporting it as the whole."}, 'ratings_storefronts': {'type': 'integer', 'description': 'How many storefronts `ratings_total` pools.'}}}, 'description': 'Apps that fell out of every storefront they held. include: ["movement"].'}, 'name': {'type': ['string', 'null'], 'description': 'What the market is called. Null for an unsaved reading.'}, 'slug': {'type': ['string', 'null'], 'description': 'Its address in the console.'}, 'terms': {'type': 'integer', 'description': 'SUM of the per-storefront corpora. The corpora are disjoint by construction — a term belongs to one storefront — so nothing is counted twice, and this is exactly what the market costs to crawl.'}, 'corpus': {'type': ['array', 'null'], 'items': {'type': 'object', 'required': ['keyword_id', 'term', 'country', 'origin'], 'properties': {'term': {'type': 'string', 'description': 'The term as the store stores it: lower case, punctuation stripped.'}, 'score': {'type': ['number', 'null'], 'description': 'Why this term made the corpus, 0-100, normalised against the best term IN THIS STOREFRONT. A rank within one corpus, not a figure comparable across two.'}, 'origin': {'type': 'string', 'description': 'seed | competitor | related | manual. `seed` was typed; `competitor` came from the terms the seeds\' leaders own (the backbone); `related` is what Apple\'s own search box suggests for a seed, which is usually a COMPLETION of it ("calorie tracker free") rather than a synonym ("meal logging") - so read the `competitor` terms for the niche\'s vocabulary and the `related` ones for how people finish typing the seed.'}, 'country': {'type': 'string', 'description': 'The storefront this term belongs to. A term is per storefront and never shared between them.'}, 'results': {'type': ['integer', 'null'], 'description': 'How many apps the store matches for this term. Being refilled: rows crawled before 30 Aug 2026 hold the length of the page Apple returned (~200 at most) rather than the real total, so treat a value near 200 as a floor.'}, 'crawled_at': {'type': ['string', 'null'], 'description': 'When the store was last searched for this term. NULL means never — the term is in the corpus and its ranks are not in yet.'}, 'keyword_id': {'type': 'integer', 'description': 'Apptail keyword id. Pass it to get_keyword_serp for the full result page, or to add_keywords to start tracking it against one of your apps.'}, 'popularity': {'type': ['integer', 'null'], 'description': "Apple's search popularity index for this term. NULL means never measured, which is unknown rather than low — do not read it as zero demand."}}}, 'description': 'Every term, with its storefront and why it is in the corpus. Present only with include: ["corpus"].'}, 'fringe': {'type': 'integer', 'description': "Apps that rank somewhere in this market's search results and are NOT competing in it: one term only, or no top-10 place anywhere. Typically several times `apps` — measured on a nine-storefront market, 578 competing against 2,001 fringe. They are real placements and worth naming as context (a store that seats an app beside yours), never as rivals. Counted once and never double-counted with `apps`: an app competing in one storefront and fringe in another is competing."}, 'spread': {'type': ['string', 'null'], 'description': 'open | contested | locked | mixed. `mixed` is the finding rather than a fudge: a niche locked in the US and open in Germany is the answer to "where should I launch this first". Storefronts in the same band report that band.'}, 'status': {'type': 'string', 'description': "draft | building | ready | failed. A market is `building` while ANY of its storefronts is — never report it ready because most of them landed. `ready` beats `failed`, so a market can read `ready` and still hold a storefront whose build died: check each storefront's `failed_at` before quoting its figures."}, 'window': {'type': 'object', 'properties': {'days': {'type': 'integer'}, 'label': {'type': 'string'}, 'compareLabel': {'type': 'string'}}, 'description': 'The window read, and what `newcomers`, `departures` and the change figures are measured against.'}, 'caveats': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Sentences the reader has to hear before the numbers mean what they look like they mean. Pass them on; do not summarise them away.'}, 'entered': {'type': ['array', 'null'], 'items': {'type': 'object', 'required': ['app_id', 'is_mine', 'is_competitor', 'terms', 'top10_terms', 'rating_count', 'ratings_storefronts', 'ratings_gained_in', 'new_reviews', 'is_estimate', 'off_market', 'storefronts'], 'properties': {'left': {'type': ['boolean', 'null'], 'description': 'True when this app ranked for at least one term in the previous window and none now. Null when no term was measured in both windows. `was_terms` says how much it held.'}, 'name': {'type': ['string', 'null'], 'description': "The app's name in this storefront. Null while a freshly seen app is still being enriched."}, 'share': {'type': ['number', 'null'], 'description': "Share of this corpus's search visibility, 0-100, and the figure the list is ordered by. Each (term, place) slot is weighted by how much evidence the term carries — a term Apple answers with one app is worth a twentieth of one it answers with twenty or more — and by how deep the place is, so #1 counts for roughly five times #10. Measured from our own daily ranks; no vendor model touches it. Null where nobody ranks at all."}, 'terms': {'type': 'integer', 'description': "How many of the landscape's terms this app ranked for at all, anywhere in the top 50, during the window."}, 'app_id': {'type': 'integer', 'description': 'Apptail app id. Feed it straight into get_app_info, get_app_reviews or add_competitors.'}, 'rating': {'type': ['number', 'null'], 'description': 'Average rating in this storefront, 1-5. Null when nobody has rated it here.'}, 'source': {'type': ['string', 'null'], 'description': 'Which source produced the size figures: `appstoreconnect`, `sensortower`, `appmagic`. Null when neither covers this app.'}, 'entered': {'type': ['boolean', 'null'], 'description': "True when this app ranked for none of these terms in the previous window and ranks for at least one now. **NULL means there was nothing to compare against** — no term was measured in both windows, which is the normal state of a market built inside this window. Null is not false and is certainly not true: do not report a new market's whole leaderboard as arrivals. Recomputed per window, so it cannot say which day it happened."}, 'is_mine': {'type': 'boolean', 'description': "True when this is one of the asking account's own apps."}, 'was_terms': {'type': ['integer', 'null'], 'description': 'How many terms this app held in the previous window. Null when it was absent then.'}, 'off_market': {'type': 'boolean', 'description': "The app is in these search results but not in this market: it shares no word with the corpus, sits in another category, and carries fifty times the median member's audience. All three are required, so this names padding (Instagram at #4 for `cyprus exam` in a thin storefront) rather than every large rival. Sorted last, never removed — report it as context, not as a competitor."}, 'is_estimate': {'type': 'boolean', 'description': "True when downloads_30d and revenue_30d are a third-party model rather than Apple's own figures. Decided per row, never per column: your connected app is measured and the row beside it is not. Say so when you report the numbers."}, 'new_reviews': {'type': 'integer', 'description': 'Reviews left during the window, in every storefront.'}, 'released_at': {'type': ['string', 'null'], 'description': 'First release, `YYYY-MM-DD`, as Apple gives it. What makes a rank readable: 4.9 on 30 votes and a rank that moved 40 places mean one thing for an app six weeks old and another for one six years old. The console marks anything inside 90 days as new. Null when the listing has never been crawled.'}, 'revenue_30d': {'type': ['integer', 'null'], 'description': 'Worldwide revenue over the same 30 days, in USD. Same provenance rule as downloads_30d, and the same two causes for null — see `revenue_30d_max`.'}, 'storefronts': {'type': 'array', 'items': {'type': 'string'}, 'description': "Which of this market's storefronts the app ranks in. An app in five of six and absent from the sixth is a storefront somebody can ship into — that gap is the reading a single-storefront market cannot produce."}, 'top10_terms': {'type': 'integer', 'description': 'How many of those terms the app actually owns — a top-10 position. This is the figure that moves and the one the list is sorted by; `terms` is reach, this is visibility.'}, 'last_updated': {'type': ['string', 'null'], 'description': "When the app's current version shipped, `YYYY-MM-DD`. The other half of `released_at`, and the one that separates a live rival from a listing: an app holding third place on a version it last shipped two years ago is not defending it. Null when we have never crawled a version date."}, 'rating_count': {'type': 'integer', 'description': 'How many ratings that average is over — the only size figure that exists for every app in the niche.'}, 'terms_change': {'type': ['integer', 'null'], 'description': 'Change in `terms` against the previous window of the same length. Null when the app was absent then, which is what `entered` reports.'}, 'top10_change': {'type': ['integer', 'null'], 'description': 'Change in `top10_terms` against the previous window, counted over the terms measured in BOTH windows so a corpus that grew cannot read as growth. The only growth number on this tool measured first-hand rather than modelled. Null when no term was measured in both.'}, 'downloads_30d': {'type': ['integer', 'null'], 'description': "Worldwide downloads over the last 30 days. Apple's measurement when this is a connected app of yours, a vendor's model otherwise — read `is_estimate`. Ignores the window: no vendor sells an estimate by window. **Null has two causes and `downloads_30d_max` separates them**: no source covers the app, or the vendor would only bound it. Never read null as zero."}, 'is_competitor': {'type': 'boolean', 'description': 'True when the account already tracks this app as a competitor of the app whose landscape this is. False on a stranger, which is most rows — the store put it here, nobody chose it.'}, 'ratings_total': {'type': ['integer', 'null'], 'description': 'Ratings the app holds across every storefront AppTail has a listing for, not only this one — `rating_count` above is this storefront alone. Null when no listing has been crawled; never 0 for unknown.'}, 'ratings_gained': {'type': ['integer', 'null'], 'description': "Ratings that arrived during the window — the half of a rating that moves, and what the store's own ranking reads. A rival gaining thousands a week is growing whatever its 4.6 says. Null when no storefront was crawled twice inside the window: one snapshot cannot measure a change."}, 'revenue_30d_max': {'type': ['integer', 'null'], 'description': 'The revenue ceiling for an app the vendor would only bound — "under $5,000". Set only when `revenue_30d` is null.'}, 'downloads_30d_max': {'type': ['integer', 'null'], 'description': 'The ceiling the vendor gave instead of a figure, for an app below its modelling floor — 1000 or 5000, depending on the vendor. Set only when `downloads_30d` is null, and then the honest sentence is "under 5,000 downloads", never a number. **Both null is a different state**: no vendor models this app at all, which is not the same as small.'}, 'ratings_gained_in': {'type': 'integer', 'description': "Storefronts `ratings_gained` was actually measured on. Lower than `ratings_storefronts` means the gain covers part of the app's markets — say so rather than reporting it as the whole."}, 'ratings_storefronts': {'type': 'integer', 'description': 'How many storefronts `ratings_total` pools.'}}}, 'description': 'Apps that arrived somewhere in this market this window. include: ["movement"].'}, 'members': {'type': ['array', 'null'], 'items': {'type': 'object', 'required': ['app_id', 'is_mine', 'is_competitor', 'terms', 'top10_terms', 'rating_count', 'ratings_storefronts', 'ratings_gained_in', 'new_reviews', 'is_estimate', 'off_market', 'storefronts'], 'properties': {'left': {'type': ['boolean', 'null'], 'description': 'True when this app ranked for at least one term in the previous window and none now. Null when no term was measured in both windows. `was_terms` says how much it held.'}, 'name': {'type': ['string', 'null'], 'description': "The app's name in this storefront. Null while a freshly seen app is still being enriched."}, 'share': {'type': ['number', 'null'], 'description': "Share of this corpus's search visibility, 0-100, and the figure the list is ordered by. Each (term, place) slot is weighted by how much evidence the term carries — a term Apple answers with one app is worth a twentieth of one it answers with twenty or more — and by how deep the place is, so #1 counts for roughly five times #10. Measured from our own daily ranks; no vendor model touches it. Null where nobody ranks at all."}, 'terms': {'type': 'integer', 'description': "How many of the landscape's terms this app ranked for at all, anywhere in the top 50, during the window."}, 'app_id': {'type': 'integer', 'description': 'Apptail app id. Feed it straight into get_app_info, get_app_reviews or add_competitors.'}, 'rating': {'type': ['number', 'null'], 'description': 'Average rating in this storefront, 1-5. Null when nobody has rated it here.'}, 'source': {'type': ['string', 'null'], 'description': 'Which source produced the size figures: `appstoreconnect`, `sensortower`, `appmagic`. Null when neither covers this app.'}, 'entered': {'type': ['boolean', 'null'], 'description': "True when this app ranked for none of these terms in the previous window and ranks for at least one now. **NULL means there was nothing to compare against** — no term was measured in both windows, which is the normal state of a market built inside this window. Null is not false and is certainly not true: do not report a new market's whole leaderboard as arrivals. Recomputed per window, so it cannot say which day it happened."}, 'is_mine': {'type': 'boolean', 'description': "True when this is one of the asking account's own apps."}, 'was_terms': {'type': ['integer', 'null'], 'description': 'How many terms this app held in the previous window. Null when it was absent then.'}, 'off_market': {'type': 'boolean', 'description': "The app is in these search results but not in this market: it shares no word with the corpus, sits in another category, and carries fifty times the median member's audience. All three are required, so this names padding (Instagram at #4 for `cyprus exam` in a thin storefront) rather than every large rival. Sorted last, never removed — report it as context, not as a competitor."}, 'is_estimate': {'type': 'boolean', 'description': "True when downloads_30d and revenue_30d are a third-party model rather than Apple's own figures. Decided per row, never per column: your connected app is measured and the row beside it is not. Say so when you report the numbers."}, 'new_reviews': {'type': 'integer', 'description': 'Reviews left during the window, in every storefront.'}, 'released_at': {'type': ['string', 'null'], 'description': 'First release, `YYYY-MM-DD`, as Apple gives it. What makes a rank readable: 4.9 on 30 votes and a rank that moved 40 places mean one thing for an app six weeks old and another for one six years old. The console marks anything inside 90 days as new. Null when the listing has never been crawled.'}, 'revenue_30d': {'type': ['integer', 'null'], 'description': 'Worldwide revenue over the same 30 days, in USD. Same provenance rule as downloads_30d, and the same two causes for null — see `revenue_30d_max`.'}, 'storefronts': {'type': 'array', 'items': {'type': 'string'}, 'description': "Which of this market's storefronts the app ranks in. An app in five of six and absent from the sixth is a storefront somebody can ship into — that gap is the reading a single-storefront market cannot produce."}, 'top10_terms': {'type': 'integer', 'description': 'How many of those terms the app actually owns — a top-10 position. This is the figure that moves and the one the list is sorted by; `terms` is reach, this is visibility.'}, 'last_updated': {'type': ['string', 'null'], 'description': "When the app's current version shipped, `YYYY-MM-DD`. The other half of `released_at`, and the one that separates a live rival from a listing: an app holding third place on a version it last shipped two years ago is not defending it. Null when we have never crawled a version date."}, 'rating_count': {'type': 'integer', 'description': 'How many ratings that average is over — the only size figure that exists for every app in the niche.'}, 'terms_change': {'type': ['integer', 'null'], 'description': 'Change in `terms` against the previous window of the same length. Null when the app was absent then, which is what `entered` reports.'}, 'top10_change': {'type': ['integer', 'null'], 'description': 'Change in `top10_terms` against the previous window, counted over the terms measured in BOTH windows so a corpus that grew cannot read as growth. The only growth number on this tool measured first-hand rather than modelled. Null when no term was measured in both.'}, 'downloads_30d': {'type': ['integer', 'null'], 'description': "Worldwide downloads over the last 30 days. Apple's measurement when this is a connected app of yours, a vendor's model otherwise — read `is_estimate`. Ignores the window: no vendor sells an estimate by window. **Null has two causes and `downloads_30d_max` separates them**: no source covers the app, or the vendor would only bound it. Never read null as zero."}, 'is_competitor': {'type': 'boolean', 'description': 'True when the account already tracks this app as a competitor of the app whose landscape this is. False on a stranger, which is most rows — the store put it here, nobody chose it.'}, 'ratings_total': {'type': ['integer', 'null'], 'description': 'Ratings the app holds across every storefront AppTail has a listing for, not only this one — `rating_count` above is this storefront alone. Null when no listing has been crawled; never 0 for unknown.'}, 'ratings_gained': {'type': ['integer', 'null'], 'description': "Ratings that arrived during the window — the half of a rating that moves, and what the store's own ranking reads. A rival gaining thousands a week is growing whatever its 4.6 says. Null when no storefront was crawled twice inside the window: one snapshot cannot measure a change."}, 'revenue_30d_max': {'type': ['integer', 'null'], 'description': 'The revenue ceiling for an app the vendor would only bound — "under $5,000". Set only when `revenue_30d` is null.'}, 'downloads_30d_max': {'type': ['integer', 'null'], 'description': 'The ceiling the vendor gave instead of a figure, for an app below its modelling floor — 1000 or 5000, depending on the vendor. Set only when `downloads_30d` is null, and then the honest sentence is "under 5,000 downloads", never a number. **Both null is a different state**: no vendor models this app at all, which is not the same as small.'}, 'ratings_gained_in': {'type': 'integer', 'description': "Storefronts `ratings_gained` was actually measured on. Lower than `ratings_storefronts` means the gain covers part of the app's markets — say so rather than reporting it as the whole."}, 'ratings_storefronts': {'type': 'integer', 'description': 'How many storefronts `ratings_total` pools.'}}}, 'description': 'The leaderboard, ordered by rating count — the one size figure we measure for every app. Present only with include: ["members"].'}, 'overlap': {'type': ['number', 'null'], 'description': 'Of the apps holding a top-10 place in ANY storefront, the share holding one in EVERY storefront, 0-100. High means one leaderboard travels and a newcomer meets it wherever they launch; low means each storefront is its own contest, which is where an unowned storefront hides. NULL for a single-storefront market — it is not a question one place can answer.'}, 'built_at': {'type': ['string', 'null'], 'description': "The OLDEST of the storefronts' build times: a market is only as fresh as its worst."}, 'app_terms': {'type': ['array', 'null'], 'items': {'type': 'object', 'required': ['keyword_id', 'term', 'country', 'place', 'is_top10', 'days', 'crawled_days', 'origin'], 'properties': {'days': {'type': 'integer', 'description': 'Days inside the window the app actually held a place for this term. **This is what separates a one-day fluke at #48 from a month at #3**, and the two are the same row without it — read it before calling a single place evidence of anything.'}, 'term': {'type': 'string', 'description': 'The term as the store stores it: lower case, punctuation stripped.'}, 'place': {'type': 'integer', 'description': 'Best position reached for this term during the window, 1 being the top. Only places inside the top 50 are here at all — deeper than that an app is listed rather than competing.'}, 'origin': {'type': 'string', 'description': 'seed | competitor | related | manual — why the TERM is in the corpus, not why the app ranks for it. Often the answer on a fringe row: an app holding only `related` terms is ranking for completions of a seed rather than for the niche itself.'}, 'country': {'type': 'string', 'description': 'The storefront this term belongs to. A term is per storefront and never shared between them, so the same word in two storefronts is two rows.'}, 'is_top10': {'type': 'boolean', 'description': 'Whether that place is inside the first result page anybody sees. This is the clause the membership verdict usually turns on: a top-50 place nobody scrolls to is not competition.'}, 'keyword_id': {'type': 'integer', 'description': 'Apptail keyword id. Pass it to get_keyword_serp for the whole result page this place sits on.'}, 'popularity': {'type': ['integer', 'null'], 'description': "Apple's search popularity index for the term. NULL is never measured, which is unknown rather than low."}, 'crawled_days': {'type': 'integer', 'description': 'Days anybody was crawling this term in the window — the denominator for `days`, and NOT the length of the window. `days: 1` out of `crawled_days: 1` is a term seen once, which is a different finding from 1 out of 30. Always at least `days`: a row exists here only because the app held a place, which means the term was crawled.'}}}, 'description': 'Every (term, storefront) place that app holds here, best place first — the evidence `app_verdict` was taken over. Present only with include: ["app_terms"].'}, 'market_id': {'type': ['integer', 'null'], 'description': 'Apptail market id, or NULL when this reading was resolved from a phrase and not saved. Pass it to save_market to keep it, or to get_market to read it again for free.'}, 'newcomers': {'type': ['integer', 'null'], 'description': "Distinct apps that arrived in at least one storefront this window. Arriving in `de` while already ranking in `us` counts as arriving in this market. **NULL means no storefront had a previous window to compare against** — nothing of this corpus was crawled then, which is the normal state of a market built inside the window. Never read null as 0, and never report a new market's whole membership as newcomers."}, 'truncated': {'type': 'boolean', 'description': 'True when any list above was cut. Say so rather than presenting a partial list as the whole thing.'}, 'departures': {'type': ['integer', 'null'], 'description': 'Distinct apps that fell out of every storefront they held. Null on the same terms as `newcomers`.'}, 'app_verdict': {'type': ['object', 'null'], 'required': ['app_id', 'is_competing', 'verdict', 'terms', 'top10_terms', 'ranked_in', 'competing_in', 'storefronts'], 'properties': {'terms': {'type': 'integer', 'description': 'Terms held across every storefront, top 50. The corpora are disjoint so this sums — but the rule was NOT run against it; see `storefronts[]`.'}, 'app_id': {'type': 'integer', 'description': 'The app this verdict is about — the `app_id` that was asked for.'}, 'verdict': {'type': 'string', 'description': 'The whole finding in one sentence, e.g. "2 terms, 0 top-10 places, in 1 of 9 storefronts — below the bar in every one, shown as fringe." Written where the rule lives, so it cannot drift from the counts. Quote it rather than rebuilding it from the numbers.'}, 'ranked_in': {'type': 'integer', 'description': 'Storefronts of this market the app ranks in at all.'}, 'storefronts': {'type': 'array', 'items': {'type': 'object', 'properties': {'why': {'type': 'string'}, 'terms': {'type': 'integer'}, 'reason': {'type': 'string'}, 'country': {'type': 'string'}, 'top10_terms': {'type': 'integer'}, 'corpus_terms': {'type': 'integer'}, 'is_competing': {'type': 'boolean'}, 'breadth_terms': {'type': ['integer', 'null']}}}, 'description': 'Where the rule actually ran: one row per storefront the market is asked in, INCLUDING the ones the app ranks in nowhere — "absent from six of nine" is the finding on a fringe app, not a row to skip. `reason` is one of absent | too_few_terms | not_visible | visible | breadth and `why` states the CLAUSE rather than the counts — it deliberately does not repeat `terms` and `top10_terms`, which are on the row beside it. `breadth_terms` is how many terms breadth alone would take in that storefront (a fifth of its corpus, floor 3), null where the corpus is empty and the clause is off.'}, 'top10_terms': {'type': 'integer', 'description': 'How many of those are inside a top ten, summed the same way.'}, 'competing_in': {'type': 'integer', 'description': '...and how many of those clear the bar. `ranked_in` well above this is the usual shape of a fringe app: it appears widely and owns nothing.'}, 'is_competing': {'type': 'boolean', 'description': 'True when the app clears the bar in at least one storefront, which is exactly what `apps` on the market counts. False means it is in `fringe`: the store really did return it, and it is context rather than a rival.'}}, 'description': 'Whether the app named by `app_id` is competing in this market, and which clause of the rule decided. Present only with include: ["app_terms"].'}, 'apps_capped': {'type': 'boolean', 'description': 'True when the census stopped at its depth before it ran out of apps. `apps`, `newcomers`, `departures`, `downloads_30d` and `revenue_30d` are then floors, because all of them are summed over the counted set. Say "at least" rather than reporting the number as a total.'}, 'console_url': {'type': ['string', 'null'], 'description': 'This market in the console.'}, 'contest_low': {'type': ['number', 'null'], 'description': "The least contested storefront's share of top-10 slots held by its top three, 0-100."}, 'revenue_30d': {'type': ['integer', 'null'], 'description': 'ESTIMATE, same basis as downloads_30d.'}, 'stale_terms': {'type': 'integer', 'description': 'Corpus terms across the market past their 72-hour refresh.'}, 'storefronts': {'type': 'array', 'items': {'type': 'object', 'required': ['country', 'status', 'terms', 'apps', 'fringe', 'apps_capped', 'stale_terms', 'seed_terms'], 'properties': {'apps': {'type': 'integer', 'description': "Apps COMPETING here: a top-10 place on at least one of this corpus's terms AND a top-50 place on at least two, in the window. A FLOOR rather than a count when `apps_capped` is true. What ranks but does not clear that bar is `fringe`."}, 'band': {'type': ['string', 'null'], 'description': 'open | contested | locked — the word for `contest`. Under 45% is open, over 70% is locked. Null when contest is.'}, 'depth': {'type': ['integer', 'null'], 'description': 'MEDIAN apps matching a term across this corpus. BEING REFILLED: rows crawled before 30 Aug 2026 hold the length of the page Apple returned (~200 at most) rather than the real total, so a value near 200 is a floor and a whole corpus sitting near 200 is measuring pagination rather than depth. Treat it as a lower bound until the corpus has turned over, and prefer `contest` — which is measured from our own daily ranks — when the question is how crowded the niche is.'}, 'terms': {'type': 'integer', 'description': 'Corpus size here. What this storefront costs to crawl.'}, 'demand': {'type': ['integer', 'null'], 'description': "MEDIAN popularity across this corpus's terms. Never a sum: popularity is an index, and adding indices produces a number that exists nowhere."}, 'fringe': {'type': 'integer', 'description': "Apps ranking in this storefront's results without competing in it — one term, or never inside a top ten. Context, not rivals."}, 'status': {'type': 'string', 'description': 'draft | building | ready | failed. A `building` storefront has a corpus and no reading yet; report it as still landing rather than as empty. `failed` means the build died with nothing to read — its zeros are missing figures, NOT a finding about the niche, and the fix is a rebuild in the console.'}, 'contest': {'type': ['number', 'null'], 'description': 'Share of this corpus\'s top-10 slots held by its top three apps, 0-100. Measured from daily ranks, not modelled. NULL means undefined, not zero: with fewer than four apps holding anything, "the top three" is the whole field.'}, 'country': {'type': 'string', 'description': 'Two-letter storefront code, lower case.'}, 'built_at': {'type': ['string', 'null'], 'description': "When this storefront's corpus was last assembled. Null while it never has been."}, 'failed_at': {'type': ['string', 'null'], 'description': 'When the LAST build attempt failed, null when it succeeded. Independent of `status` and that is the point: a rebuild that dies over a storefront that already has a corpus stays `ready` with a real reading that is quietly OLDER than `built_at` says. When this is set, say so before quoting the figures.'}, 'newcomers': {'type': ['integer', 'null'], 'description': 'Apps with no top-50 place here in the previous window of the same length. NULL when no term of this corpus was measured in both windows — a storefront first crawled inside this window has no baseline, and "nobody crawled it" is not "nobody ranked".'}, 'age_months': {'type': ['integer', 'null'], 'description': 'Median months since first release among the head. A niche of four-year-olds and one of six-month-olds are different bets.'}, 'demand_top': {'type': ['integer', 'null'], 'description': 'The most popular single term in this corpus.'}, 'departures': {'type': ['integer', 'null'], 'description': 'The inverse: apps that held one then and do not now. Null on the same terms as `newcomers`.'}, 'last_error': {'type': ['string', 'null'], 'description': 'One sentence saying what failed. Null unless `failed_at` is set. Safe to repeat to the user verbatim.'}, 'seed_terms': {'type': 'array', 'items': {'type': 'string'}, 'description': "What this storefront's corpus was expanded FROM, in its own language. A leaderboard that looks wrong is nearly always a storefront asked the wrong question, and this is the question — check it before reporting the niche as empty or the members as odd. Change it with save_market's `seeds`, which rebuilds this storefront whole."}, 'apps_capped': {'type': 'boolean', 'description': "True when this storefront's census stopped at its depth before it ran out of apps. `apps` and everything summed over the member set are then floors."}, 'revenue_30d': {'type': ['integer', 'null'], 'description': 'ESTIMATE, same basis as downloads_30d.'}, 'seed_source': {'type': ['string', 'null'], 'description': "The storefront these terms were READ from, when nobody gave any. Null means they were typed. Otherwise they were lifted off the localised listings of that storefront's leaders and kept only because searching them here brought those same leaders back — good terms, and this product's guess rather than the user's words. Worth naming when reporting what a market was built on."}, 'stale_terms': {'type': 'integer', 'description': 'Corpus terms past their 72-hour refresh. A large share means this reading is older than it looks.'}, 'rating_floor': {'type': ['number', 'null'], 'description': 'Median rating of the head of this leaderboard — what a newcomer has to clear.'}, 'concentration': {'type': ['number', 'null'], 'description': "HHI over each app's share of the top-10 slots, 0-1. Contest says how much the head holds; this says whether the head is one app or three."}, 'downloads_30d': {'type': ['integer', 'null'], 'description': 'ESTIMATE, and a FLOOR. A third-party model, worldwide and 30-day, summed over this storefront\'s apps — with the apps the vendor would only bound ("under 5,000") left out entirely, since a ceiling cannot be added. Never present this as measured, and never differentiate two of them into a growth rate.'}}}, 'description': 'One entry per storefront, and the only level at which contest, demand and depth exist. Compare these rather than averaging them.'}, 'contest_high': {'type': ['number', 'null'], 'description': "The most contested storefront's. A RANGE, deliberately: there is no market-level contest to average."}, 'corpus_total': {'type': ['integer', 'null'], 'description': 'Terms the market holds. Larger than the list means it was cut.'}, 'size_covered': {'type': 'integer', 'description': 'How many of the `apps` above carry an estimate at all, INCLUDING the ones the vendor would only bound as "under 1,000" / "under 5,000". Those contribute nothing to the sums, so a market with many small apps reports a size that is a floor. A total over 40 of 291 apps is a different statement from one over 280 — say which when quoting the size.'}, 'downloads_30d': {'type': ['integer', 'null'], 'description': 'ESTIMATE. A third-party model, worldwide and 30-day, summed over the UNION with each app counted once. Adding the per-storefront totals would count the same worldwide figure once per storefront and be wrong by roughly the storefront count.'}, 'members_total': {'type': ['integer', 'null'], 'description': 'Members the market actually holds. Larger than the list means it was cut.'}, 'pending_terms': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Terms in the corpus that could not be crawled inside the budget. Their ranks are missing from this reading, so it is a floor. Saving the market and asking again returns a deeper answer.'}, 'app_terms_total': {'type': ['integer', 'null'], 'description': 'Places the app actually holds. Larger than the list means it was cut.'}, 'storefront_count': {'type': 'integer', 'description': 'How many places this question is asked in.'}, 'pending_storefronts': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Storefronts that ran out of budget before they were read at all. Name them; a partial answer that reads as complete is the failure this field exists to prevent.'}}}

{'type': 'object', 'properties': {'to': {'type': 'string', 'description': 'End date, `YYYY-MM-DD`, inclusive. Send it alone and the window is the three years before it.'}, 'from': {'type': 'string', 'description': 'Start date, `YYYY-MM-DD`, inclusive. Overrides `period` when both are sent. Send it alone and the window runs to today.'}, 'grain': {'enum': ['day', 'week', 'month', 'quarter', 'year'], 'type': 'string', 'description': 'Bucket size for the series. Omit and it is chosen to fit the window — a day for a month, a week for a year. A grain too fine or too coarse for the window is ignored rather than refused.'}, 'scope': {'enum': ['portfolio', 'app'], 'type': 'string', 'description': '`portfolio` (the default) sums every app the account owns; `app` reports one, and then `app_id` is required. Hidden apps are in the portfolio sum only if the account has not hidden them — they are excluded, matching what the console shows.'}, 'split': {'enum': ['none', 'country', 'source'], 'type': 'string', 'description': "Break the totals down. `country` gives one row per storefront Apple named; `source` gives Apple's own attribution — App Store search, browse, app and web referrers. `source` reports the attribution associated with measured downloads. Rows need not add up to the total; the caveats say so."}, 'app_id': {'type': 'integer', 'description': "Apptail app id, required when `scope` is `app`. Must be one of the user's own apps — get_account lists them. Measured analytics require an authorised App Store Connect connection for the account."}, 'period': {'type': 'string', 'description': 'The window to report on. A calendar month as `2026-07`, a calendar year as `2026`, `last_month`, `this_month`, `last_year`, or a trailing window: `today`, `7d`, `14d`, `30d`, `90d`, `180d`, `365d`, `730d`, `1095d`. Defaults to `30d`. A calendar period is compared against the calendar period before it — July against June, not against the 31 days ending 30 June. Three years is the ceiling.'}, 'compare': {'enum': ['none', 'previous', 'year_ago'], 'type': 'string', 'description': 'What to read the window against. `previous` (the default) is the period immediately before — for a calendar month that is the calendar month before, not the same number of days. `year_ago` is the same dates a year earlier, for comparison with the corresponding period in the previous year.'}, 'include_apps': {'type': 'boolean', 'description': 'On `portfolio` scope, also return one row per app so a portfolio move can be attributed to the app that caused it. Default false.'}}}

{'type': 'object', 'required': ['scope', 'app_ids', 'window', 'requested_window', 'grain', 'coverage', 'totals', 'series', 'split', 'split_rows', 'split_total', 'truncated', 'apps', 'caveats'], 'properties': {'apps': {'type': 'array', 'items': {'type': 'object', 'required': ['app_id', 'connected'], 'properties': {'name': {'type': ['string', 'null'], 'description': 'App name.'}, 'app_id': {'type': 'integer', 'description': 'Apptail app id.'}, 'proceeds': {'type': ['number', 'null'], 'description': 'Proceeds over the window, in USD.'}, 'connected': {'type': 'boolean', 'description': 'Whether App Store Connect reports for this app. False means its figures are null and it contributed nothing to the totals — it was left out, not counted as zero.'}, 'downloads': {'type': ['number', 'null'], 'description': 'Downloads over the window.'}, 'conversion': {'type': ['number', 'null'], 'description': 'Downloads over impressions, as a percentage.'}, 'impressions': {'type': ['number', 'null'], 'description': 'Impressions over the window.'}, 'store_views': {'type': ['number', 'null'], 'description': 'Product page views over the window — how many times the listing itself was opened, which is a smaller and different number from impressions. The gap between the two is discovery working and the listing not being opened; the gap between this and downloads is the listing being opened and not converting.'}, 'data_through': {'type': ['string', 'null'], 'description': 'Last day App Store Connect reported for this app. Null when it never has.'}}}, 'description': 'One row per app, when `include_apps` was set on a portfolio call. Empty otherwise.'}, 'grain': {'type': 'string', 'description': 'Bucket size the series came back at.'}, 'scope': {'type': 'string', 'description': 'Which scope answered: `portfolio` or `app`.'}, 'split': {'type': 'string', 'description': 'Which breakdown was returned: `none`, `country` or `source`.'}, 'series': {'type': 'array', 'items': {'type': 'object', 'required': ['date', 'impressions', 'store_views', 'downloads', 'sales', 'proceeds'], 'properties': {'date': {'type': 'string', 'description': 'First day of the bucket, `YYYY-MM-DD`. At day grain that is the day itself; at week grain the Monday; at month grain the 1st.'}, 'sales': {'type': 'number', 'description': 'Gross sales in this bucket, in USD.'}, 'proceeds': {'type': 'number', 'description': 'What Apple pays out, in USD — the number an owner means by revenue.'}, 'downloads': {'type': 'number', 'description': 'Total downloads in this bucket.'}, 'conversion': {'type': ['number', 'null'], 'description': 'Downloads over impressions for this bucket, as a percentage, rebuilt from the bucket\'s own totals. Null when there were no impressions — which is "nobody saw it", not "nobody who saw it installed". Never average these across buckets; the mean of rates is a different number.'}, 'impressions': {'type': 'number', 'description': 'Times the app appeared, in this bucket.'}, 'store_views': {'type': 'number', 'description': 'Product page views in this bucket.'}}}, 'description': 'The same metrics bucketed across the window, oldest first. Empty when nothing is connected.'}, 'totals': {'type': 'array', 'items': {'type': 'object', 'required': ['key', 'is_estimate', 'precision'], 'properties': {'key': {'type': 'string', 'description': 'Which metric: `impressions`, `store_views`, `downloads`, `iap` (in-app purchase transactions), `sales` (gross), `proceeds` (what Apple actually pays out) or `conversion` (downloads over impressions, as a percentage).'}, 'note': {'type': ['string', 'null'], 'description': 'Something the reader has to know before quoting the figure — most often that the window was only measured part-way, or that connecting App Store Connect would replace the estimate with a measurement.'}, 'as_of': {'type': ['string', 'null'], 'description': 'For a measurement, the last day App Store Connect reported. For an estimate, the day the vendor was scraped.'}, 'value': {'type': ['number', 'null'], 'description': 'The figure. **Null means unknown, never zero** — no connection, or no data for these days. Also null when `precision` is `bucketed`, where the source only gave an upper bound.'}, 'source': {'enum': ['appstoreconnect', 'sensortower', 'appmagic', 'scraped', 'mock'], 'type': ['string', 'null'], 'description': "Where the figure came from. `appstoreconnect` is Apple's own measurement of an app the account has connected; `sensortower` and `appmagic` are third-party models. Null when nothing covers it."}, 'window': {'type': ['string', 'null'], 'description': 'What the figure covers: `2026-07-01..2026-07-31` for a measurement, or the literal `rolling_30d` for a vendor estimate, which is a thirty-day total snapshotted on scrape day and must never be pro-rated into a requested period.'}, 'previous': {'type': ['number', 'null'], 'description': 'The same metric over the comparison window. Null when nothing was compared.'}, 'delta_pct': {'type': ['number', 'null'], 'description': 'Percentage change against `previous`. A base of zero reads +100% when the figure arrived and −100% when it went away, matching the console — so it is a convention at that end rather than a measured proportion, and the figures themselves are in `value` and `previous`. Null when there is nothing to compare, or when the two figures are not the same kind of claim (a modelled estimate against a measurement).'}, 'precision': {'enum': ['exact', 'bucketed', 'none'], 'type': 'string', 'description': '`exact` = the number is the number. `bucketed` = the source only said "under N"; read `upper_bound` and do not invent a midpoint. `none` = not known at all.'}, 'is_estimate': {'type': 'boolean', 'description': "True for a vendor model, false for a measurement. **Never compare a true against a false without saying so** — measured July against a rival's rolling-30-day model is a confident wrong answer that reads exactly like a right one."}, 'lower_bound': {'type': ['integer', 'null'], 'description': 'Floor of a bucketed figure, when the source claimed one.'}, 'upper_bound': {'type': ['integer', 'null'], 'description': 'Ceiling of a bucketed figure — "under 5,000" arrives as 5000.'}}}, 'description': 'Window totals, one entry per metric, each carrying where it came from and what it may be compared with.'}, 'window': {'type': 'object', 'required': ['from', 'to', 'days', 'label'], 'properties': {'to': {'type': 'string', 'description': 'Last day covered, inclusive.'}, 'days': {'type': 'integer', 'description': 'Length of the window in days.'}, 'from': {'type': 'string', 'description': 'First day covered, inclusive.'}, 'label': {'type': 'string', 'description': 'What names this window — the period key, or `custom`.'}}, 'description': 'The window actually read, which is not always the one asked for: an inverted range is swapped, a range past three years is shortened, and first-party figures are pulled back to the last day App Store Connect reported. Quote these dates, not the requested ones.'}, 'app_ids': {'type': 'array', 'items': {'type': 'integer'}, 'description': 'The apps behind these figures.'}, 'caveats': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Sentences the reader has to hear before the numbers mean what they look like they mean — apps left out, a window shortened, a breakdown that does not sum. Pass these on; do not summarise them away.'}, 'coverage': {'type': 'object', 'required': ['apps', 'connected', 'excluded'], 'properties': {'apps': {'type': 'integer', 'description': 'Own apps in scope.'}, 'excluded': {'type': 'array', 'items': {'type': 'integer'}, 'description': 'App ids left out of the totals for having no connection. They are omitted, never counted as zero.'}, 'connected': {'type': 'integer', 'description': 'How many of them App Store Connect reports for.'}}, 'description': 'What the totals do and do not cover. Quote this whenever `connected` is below `apps`.'}, 'truncated': {'type': 'boolean', 'description': 'True when `split_rows` is shorter than `split_total`. Say so rather than presenting the returned rows as the whole breakdown.'}, 'split_rows': {'type': 'array', 'items': {'type': 'object', 'required': ['key', 'label'], 'properties': {'key': {'type': 'string', 'description': 'Storefront code (`us`, `de`) for a country split, or the numeric traffic-source id for a source split.'}, 'label': {'type': 'string', 'description': 'What to call it in an answer — the country\'s name, or "App Store search" / "App Store browse" / "App referrer" and so on.'}, 'proceeds': {'type': ['number', 'null'], 'description': 'Proceeds in this row, in USD.'}, 'delta_pct': {'type': ['number', 'null'], 'description': 'Change in downloads against the comparison window. Null when nothing was compared, or when this row had no downloads to compare against.'}, 'downloads': {'type': ['number', 'null'], 'description': 'Downloads in this row.'}, 'share_pct': {'type': ['number', 'null'], 'description': "This row's share of the split's own downloads, not of the grand total. Apple names only the storefronts it chooses to per metric, so the rows can fall short of the total — taking a share against the total would leave a gap nobody can explain."}, 'conversion': {'type': ['number', 'null'], 'description': 'Downloads over impressions for this row, as a percentage.'}, 'impressions': {'type': ['number', 'null'], 'description': 'Impressions in this row.'}, 'store_views': {'type': ['number', 'null'], 'description': 'Product page views in this row — the listing opened, not merely shown.'}}}, 'description': 'The breakdown, biggest by downloads first. Empty when `split` is `none`.'}, 'split_total': {'type': 'integer', 'description': 'How many rows the breakdown has in total, which can exceed the number returned.'}, 'data_through': {'type': ['string', 'null'], 'description': 'Last day App Store Connect has reported across these apps. Apple lands analytics one to two days late, so this is usually a day or two behind today; a gap of a week or more is a broken connection rather than a lag.'}, 'requested_window': {'type': 'object', 'required': ['from', 'to', 'days'], 'properties': {'to': {'type': 'string', 'description': 'Last day asked for.'}, 'days': {'type': 'integer', 'description': 'Length asked for, in days.'}, 'from': {'type': 'string', 'description': 'First day asked for.'}}, 'description': 'What the call asked for, when that differs from what was read. Compare with `window` before quoting a total as covering the period the user named.'}, 'comparison_window': {'type': ['object', 'null'], 'required': ['from', 'to', 'days'], 'properties': {'to': {'type': 'string', 'description': 'Last day of the comparison window.'}, 'days': {'type': 'integer', 'description': 'Its length in days.'}, 'from': {'type': 'string', 'description': 'First day of the comparison window.'}}, 'description': 'The window `previous` on each metric was measured over. Null when `compare` was `none`.'}}}

{'type': 'object', 'required': ['app_id'], 'properties': {'to': {'type': 'string', 'description': 'End date, `YYYY-MM-DD`, inclusive. Send it alone and the window is the three years before it.'}, 'from': {'type': 'string', 'description': 'Start date, `YYYY-MM-DD`, inclusive. Overrides `period` when both are sent. Send it alone and the window runs to today.'}, 'limit': {'type': 'integer', 'description': 'Max reviews, newest first. Default 25, capped at 200. The answer always says how many matched.'}, 'app_id': {'type': 'integer', 'description': "Apptail app id. get_account for the user's own apps, search_apps for any other. Reviews are readable for any app in the store, including competitors."}, 'period': {'type': 'string', 'description': 'The window to report on. A calendar month as `2026-07`, a calendar year as `2026`, `last_month`, `this_month`, `last_year`, or a trailing window: `today`, `7d`, `14d`, `30d`, `90d`, `180d`, `365d`, `730d`, `1095d`. Defaults to `30d`. A calendar period is compared against the calendar period before it — July against June, not against the 31 days ending 30 June. Three years is the ceiling. **This tool also takes `all`**, which is the app\'s whole review history and the only period that reaches a backlog older than three years. Reviews are kept for the life of the app and the console\'s own reviews screen has no date bound at all, so the ceiling above is about first-party analytics and not about these rows. Send `all` for "what have we never answered" and for anything asking about a review from years ago; the trend then buckets by quarter or year.'}, 'rating': {'type': 'array', 'items': {'type': 'integer'}, 'description': 'Only these star ratings, e.g. `[1, 2]` for the critical ones. Omit for all five. The `summary` counts are deliberately NOT filtered by this, so a call asking only for one-stars still learns how many reviews the period actually held.'}, 'country': {'type': 'string', 'description': "Only reviews from this storefront (e.g. de). Omit for every storefront, which is usually right — one storefront's reviews are a thin sample. Send it when `ratings.by_country` on get_app has pointed at a market, which is the follow-up that finds out why it is low."}, 'contains': {'type': 'string', 'description': 'Only reviews whose title or body contains this text, case-insensitively. Title as well as body, because a complaint is as often the headline as the paragraph. This is how you check a hypothesis — "crash", "subscription", "ads" — rather than reading everything.'}, 'unanswered': {'type': 'boolean', 'description': 'Only reviews the developer has never replied to. False or omitted for all of them. Combined with `rating: [1, 2]` this is the work queue the console leads with — and **a backlog has no window**, so send `period: "all"` when you mean all of it. `summary.unanswered` is the whole-history count either way, and a list that is smaller than it is a windowed list, not a shorter backlog.'}}}

{'type': 'object', 'required': ['window', 'app_id', 'count', 'total', 'truncated', 'filtered', 'summary', 'trend', 'reviews', 'replies'], 'properties': {'count': {'type': 'integer', 'description': 'Reviews returned.'}, 'total': {'type': 'integer', 'description': 'Reviews matching the filters in this window. Larger than `count` when the list was capped.'}, 'trend': {'type': 'object', 'properties': {'grain': {'type': 'string', 'description': 'Bucket size the window resolved to: day, week, month, quarter or year.'}, 'buckets': {'type': 'array', 'items': {'type': 'object', 'required': ['date', 'arrived'], 'properties': {'date': {'type': 'string', 'description': 'First day of the bucket (YYYY-MM-DD).'}, 'arrived': {'type': 'integer', 'description': 'Reviews left in this bucket. A real zero: the window is known to have happened and nothing came in.'}, 'store_rating': {'type': ['number', 'null'], 'description': "The app's pooled store rating at the end of this bucket, across every storefront with votes. Null before the first daily snapshot, and for buckets older than the 365-day ratings history. This moves far more slowly than `average_rating`: it is a running total over the app's life."}, 'average_rating': {'type': ['number', 'null'], 'description': 'Mean star of the reviews that arrived here, 1-5. Null when none did — a bucket nobody reviewed has no average, and 0 on a five-point scale is the worst score there is.'}}}, 'description': 'Oldest first, one per bucket including the empty ones.'}}, 'description': 'The shape of the period. Compare `average_rating` with `store_rating` bucket by bucket: the first is the mood of what arrived, the second is the running total the store ranks on, and the gap between them is the finding.'}, 'app_id': {'type': 'integer', 'description': 'The app the reviews belong to.'}, 'window': {'type': 'object', 'required': ['from', 'to', 'days', 'label'], 'properties': {'to': {'type': 'string', 'description': 'Last day covered, inclusive.'}, 'days': {'type': 'integer', 'description': 'Length of the window in days.'}, 'from': {'type': 'string', 'description': 'First day covered, inclusive.'}, 'label': {'type': 'string', 'description': 'What names this window — the period key, or `custom`.'}}, 'description': 'The window actually read, which is not always the one asked for: an inverted range is swapped, a range past three years is shortened, and first-party figures are pulled back to the last day App Store Connect reported. Quote these dates, not the requested ones.'}, 'country': {'type': ['string', 'null'], 'description': 'Storefront the list was narrowed to, or null for every storefront.'}, 'replies': {'type': 'object', 'properties': {'reason': {'type': ['string', 'null'], 'description': 'Why replying is unavailable, in words for the account owner. It always ends at a screen in the console — connecting a key is not something this connection can do, so offer the sentence rather than a workaround.'}, 'enabled': {'type': ['boolean', 'null'], 'description': 'Whether this account can answer this app\'s reviews with `reply_to_reviews`. **Null is "this call had no account", never "no"** — the same convention as `is_mine`.'}, 'max_length': {'type': 'integer', 'description': "Apple's ceiling on a reply, in characters. Count before sending; a longer one is refused outright."}}, 'description': "Whether replying is available to this account at all. Read it together with `can_reply` on each review: this is about the account's key, that is about the individual review having an App Store Connect id. Both must be true."}, 'reviews': {'type': 'array', 'items': {'type': 'object', 'required': ['review_id', 'can_reply', 'reply_unavailable'], 'properties': {'body': {'type': ['string', 'null'], 'description': 'Full review text, in the language it was written in.'}, 'title': {'type': ['string', 'null'], 'description': 'Review headline.'}, 'author': {'type': ['string', 'null'], 'description': 'Display name the reviewer posted under.'}, 'rating': {'type': ['integer', 'null'], 'description': 'Star rating the reviewer gave, 1-5.'}, 'country': {'type': ['string', 'null'], 'description': 'Lowercase ISO code of the storefront the review was left in, e.g. "de".'}, 'can_reply': {'type': 'boolean', 'description': "Whether `reply_to_reviews` can answer this one. True when the review carries the App Store Connect id Apple's reply endpoint takes — which reviews read from the public store do not have, and which arrives once the account has connected an App Store Connect API key and its first sync has run. **True here is necessary and not sufficient:** the account must also hold a key that reaches this app, which is reported once per call in `replies` rather than repeated on every row."}, 'review_id': {'type': 'integer', 'description': 'Apptail review ID.'}, 'created_at': {'type': ['string', 'null'], 'description': 'Date the review was posted (YYYY-MM-DD).'}, 'reply_state': {'enum': ['published', 'pending'], 'type': ['string', 'null'], 'description': 'Where the developer\'s reply is on its way to the store. `published` is live. `pending` means Apple has taken it and has not published it yet — say **pending**, never "replied", because somebody told the reply is live will go and look for it on the store and not find it. **Null means unknown, not published**: replies AppTail read from the public App Store carry no state, and so does every review with no reply at all. Read `developer_response` to tell those two apart.'}, 'reply_unavailable': {'type': 'boolean', 'description': 'Whether `can_reply: false` is **permanent**. False is the ordinary case: the App Store Connect sync has not reached this review yet, and it will become answerable once it does — tell the user to open the review in AppTail and press **Read them now**, or simply to try again later. True means AppTail read every review App Store Connect returns for that storefront and this one was not among them, so Apple holds no id to accept a reply against and never will: it cannot be answered here or in App Store Connect, usually because the reviewer or Apple has since removed it. **Do not tell the user to sync for one of these** and do not offer to retry it — say it cannot be answered and move on to the ones that can. Always false where `can_reply` is true.'}, 'developer_response': {'type': ['string', 'null'], 'description': "The developer's public reply, or null if they have not replied."}, 'developer_responded_at': {'type': ['string', 'null'], 'description': 'Date the developer replied (YYYY-MM-DD).'}}}, 'description': 'The matching reviews, newest first, in the language they were written in. Read them; do not ask for a summary you can produce better yourself.'}, 'summary': {'type': 'object', 'properties': {'arrived': {'type': 'integer', 'description': 'Reviews left in the window, unfiltered.'}, 'all_time': {'type': 'integer', 'description': 'Reviews on file for this app, ever. The honest denominator for the list.'}, 'critical': {'type': 'integer', 'description': 'Of those, how many were 1–2★.'}, 'positive': {'type': 'integer', 'description': 'How many were 4–5★.'}, 'unanswered': {'type': 'integer', 'description': "Reviews with no developer reply, over the app's whole history. **A backlog has no window** — an unanswered one-star from March is still work outstanding."}, 'store_rating': {'type': ['number', 'null'], 'description': "The app's rating across every storefront with votes, weighted by each one's count. A stock read at today, not a figure for the window — and never the primary storefront's alone."}, 'average_rating': {'type': ['number', 'null'], 'description': 'Mean star of what arrived in the window. Null when nothing did — never 0.'}, 'arrived_previous': {'type': 'integer', 'description': 'The same count for the period before it — July against June, not the 31 days ending 30 June.'}, 'critical_previous': {'type': 'integer', 'description': 'And in the period before.'}, 'critical_unanswered': {'type': 'integer', 'description': 'Of those, how many are 1–2★. This is the queue worth leading with.'}, 'store_ratings_count': {'type': 'integer', 'description': 'Total votes behind it. Note the scale: Apple counts ratings in the hundreds of thousands and publishes reviews in the dozens.'}, 'average_rating_previous': {'type': ['number', 'null'], 'description': 'The same for the period before.'}, 'store_rating_storefronts': {'type': 'integer', 'description': 'How many storefronts that pools.'}}, 'description': 'The period in figures. `arrived*`, `critical*` and `average_rating*` are flows *in the window*; `all_time`, `unanswered` and `store_rating*` are the app\'s standing position and ignore it. Mixing the two is how "we got 12 reviews and have 400" becomes one number.'}, 'app_name': {'type': ['string', 'null'], 'description': 'Its name.'}, 'filtered': {'type': 'boolean', 'description': 'True when any of `country`, `rating`, `contains` or `unanswered` narrowed the list. Worth saying out loud: "no reviews" under a filter is not "no reviews".'}, 'truncated': {'type': 'boolean', 'description': 'True when `count` is below `total`. Say the list is a sample rather than presenting it as everything that was written.'}, 'console_url': {'type': ['string', 'null'], 'description': "The app's Reviews screen in the console."}}}

{'type': 'object', 'properties': {'to': {'type': 'string', 'description': 'End date, `YYYY-MM-DD`, inclusive. Send it alone and the window is the three years before it.'}, 'from': {'type': 'string', 'description': 'Start date, `YYYY-MM-DD`, inclusive. Overrides `period` when both are sent. Send it alone and the window runs to today.'}, 'limit': {'type': 'integer', 'description': 'Max findings, newest first. Default 50, capped at 200. The answer always says how many the window actually holds.'}, 'types': {'type': 'array', 'items': {'enum': ['rank.move', 'chart.enter', 'review.spike', 'competitor.release', 'price.change', 'traffic.shift', 'conversion.shift', 'downloads.drop', 'review.new', 'rating.change'], 'type': 'string'}, 'description': 'Only these kinds of finding. Omit for all of them. An unknown name is refused rather than ignored, so a filtered answer is never returned as though it were unfiltered.'}, 'app_id': {'type': 'integer', 'description': "Narrow to one of the user's own apps — get_account lists them. Findings about the competitors tracked under it are included, because a rival taking your places is something that happened to you. Omit for the whole portfolio."}, 'period': {'type': 'string', 'description': 'The window to report on. A calendar month as `2026-07`, a calendar year as `2026`, `last_month`, `this_month`, `last_year`, or a trailing window: `today`, `7d`, `14d`, `30d`, `90d`, `180d`, `365d`, `730d`, `1095d`. Defaults to `30d`. A calendar period is compared against the calendar period before it — July against June, not against the 31 days ending 30 June. Three years is the ceiling.'}, 'include_sent': {'type': 'boolean', 'description': 'Mark the findings that already went out in an alert digest the user has read. Default false. Set it whenever you are about to summarise a period for someone: without it you cannot tell news from something they read at breakfast, and repeating the second as the first is how an assistant stops being believed.'}, 'min_severity': {'enum': ['neutral', 'opportunity', 'warning', 'critical'], 'type': 'string', 'description': 'Floor on how loudly a finding speaks. Default `neutral`, which is everything. `warning` drops a rival shipping a point release, which is worth knowing and not worth acting on. It is NOT the same as "what needs my attention" — read `asks_action` on each finding for that: a competitor taking a run of 1–2★ reviews is a warning about somebody else\'s week and asks nothing of this user.'}}}

{'type': 'object', 'required': ['window', 'app_ids', 'count', 'total', 'truncated', 'by_type', 'by_severity', 'signals'], 'properties': {'count': {'type': 'integer', 'description': 'Findings returned.'}, 'total': {'type': 'integer', 'description': 'Findings the window holds in total. Larger than `count` when the list was capped.'}, 'digest': {'type': ['object', 'null'], 'properties': {'unsent': {'type': 'integer', 'description': 'How many the user has not been mailed. Lead with these.'}, 'already_sent': {'type': 'integer', 'description': 'How many of the returned findings it carried.'}, 'last_sent_at': {'type': ['string', 'null'], 'description': 'When the most recent alert digest covering this period went out.'}}, 'description': 'What the product has already told this person, when `include_sent` was set. Null otherwise, which means "not asked" rather than "never mailed".'}, 'window': {'type': 'object', 'required': ['from', 'to', 'days', 'label'], 'properties': {'to': {'type': 'string', 'description': 'Last day covered, inclusive.'}, 'days': {'type': 'integer', 'description': 'Length of the window in days.'}, 'from': {'type': 'string', 'description': 'First day covered, inclusive.'}, 'label': {'type': 'string', 'description': 'What names this window — the period key, or `custom`.'}}, 'description': 'The window actually read, which is not always the one asked for: an inverted range is swapped, a range past three years is shortened, and first-party figures are pulled back to the last day App Store Connect reported. Quote these dates, not the requested ones.'}, 'app_ids': {'type': 'array', 'items': {'type': 'integer'}, 'description': "The apps of the user's these findings hang under."}, 'by_type': {'type': 'object', 'properties': {'rank.move': {'type': 'integer', 'description': 'Rank moves on tracked terms.'}, 'review.new': {'type': 'integer', 'description': 'New reviews on own apps.'}, 'chart.enter': {'type': 'integer', 'description': 'Chart entries.'}, 'price.change': {'type': 'integer', 'description': 'Price changes.'}, 'review.spike': {'type': 'integer', 'description': 'Unusual runs of 1–2★ reviews.'}, 'rating.change': {'type': 'integer', 'description': 'Rating moves on own apps.'}, 'traffic.shift': {'type': 'integer', 'description': 'Week-over-week impression or page-view shifts on own apps.'}, 'downloads.drop': {'type': 'integer', 'description': 'Two-day download collapses on own apps.'}, 'conversion.shift': {'type': 'integer', 'description': 'Week-over-week install-rate shifts on own apps.'}, 'competitor.release': {'type': 'integer', 'description': 'Competitor releases.'}}, 'description': 'How many of each kind the window holds — the shape of the period, counted over everything rather than over the capped list. A key is absent when there were none.'}, 'signals': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'date', 'detected_at', 'type', 'severity', 'headline', 'evidence', 'app_id', 'app_name', 'owner_app_id', 'is_own_app', 'asks_action', 'storefronts', 'measure', 'to', 'improved'], 'properties': {'id': {'type': 'string', 'description': 'A stable id for this finding. The same string a digest email records, which is what makes `already_sent` an exact answer rather than a guess.'}, 'to': {'type': 'number', 'description': "What it is now, in the storefront named by `country`. Across a finding that spans storefronts the figures differ — Apple's price tiers are per currency — so `headline` states the range and these two stay one storefront's checkable numbers."}, 'date': {'type': 'string', 'description': 'The day the change happened, `YYYY-MM-DD` — not the day it was noticed. Detectors run after the crawl wave, so the two differ by hours.'}, 'from': {'type': ['number', 'null'], 'description': 'What it was, in the storefront named by `country`. Null only for a first observation, which says so in `evidence`.'}, 'type': {'enum': ['rank.move', 'chart.enter', 'review.spike', 'competitor.release', 'price.change', 'traffic.shift', 'conversion.shift', 'downloads.drop', 'review.new', 'rating.change'], 'type': 'string', 'description': "What kind of change this is. The first five are store-side and cover rivals; `traffic.shift`, `conversion.shift`, `downloads.drop`, `review.new` and `rating.change` are first-party (App Store Connect, the user's own reviews and ratings) and exist only for the user's own apps. A type this list does not name is not something the product watches for."}, 'app_id': {'type': 'integer', 'description': "The app this is ABOUT. Equal to `owner_app_id` when it is one of the user's own; otherwise it is a competitor they track."}, 'country': {'type': ['string', 'null'], 'description': "Storefront, or null for an event that is not per-storefront — a release is one event for the whole store, not 122 of them. When `storefronts` is above 1 this is the loudest of them, and `from`, `to` and `evidence` are that storefront's own figures; `countries` names the rest."}, 'keyword': {'type': ['string', 'null'], 'description': 'That term, when the keyword row still exists. A signal outlives the keyword it was written about, so null here means the term is no longer tracked, not that the finding is invalid.'}, 'measure': {'type': 'string', 'description': 'What `from` and `to` are in: `rank`, `chart_position`, `price`, `critical_reviews`, `days_between_releases`, `weekly_total` (of the metric `subject` names), `install_rate_pct`, `daily_downloads` (`from` is the trailing median), `stars` or `rating`. Never guess the unit from the type.'}, 'sent_at': {'type': ['string', 'null'], 'description': 'When the digest carrying it went out. Null when it never did, or when `include_sent` was not asked for.'}, 'subject': {'type': ['string', 'null'], 'description': 'What the row is about when it is not a keyword: a version string for a release, a chart id for a chart entry. Empty for the rest.'}, 'app_name': {'type': 'string', 'description': 'Name of that app.'}, 'evidence': {'type': 'string', 'description': 'The figures behind the headline in one sentence — what it moved from, over how long, against what baseline. This is the sentence a reader checks the product against.'}, 'headline': {'type': 'string', 'description': 'What happened, in one clause, with its numbers in it — the same sentence the console shows. Quote it rather than rewriting it; it is the finding, and it is checkable against `from` and `to`.'}, 'improved': {'type': 'boolean', 'description': 'Whether the move was in the good direction. Rank and chart position invert — #4 beats #19 — so a falling number is an improvement there and a rising one is not. Read this rather than comparing `from` and `to` yourself.'}, 'severity': {'enum': ['neutral', 'opportunity', 'warning', 'critical'], 'type': 'string', 'description': 'How loudly it speaks. Assigned from the size of the move, never from the type: a two-place slide and a slide out of the top ten are the same type and not the same news. `neutral` is worth knowing and not worth interrupting for.'}, 'countries': {'type': ['array', 'null'], 'items': {'type': 'string'}, 'description': 'Every storefront the finding covers, when it covers more than one — the whole list, never a sample. Null when there is only `country` to name.'}, 'is_own_app': {'type': 'boolean', 'description': "True when the subject is one of the user's own apps. False means a competitor moved, which is context rather than something they did."}, 'keyword_id': {'type': ['integer', 'null'], 'description': 'The term this is about, for a `rank.move`. Pass it to get_keywords or get_keyword_serp to find out who took the places. Null for every other type.'}, 'asks_action': {'type': 'boolean', 'description': "Whether this is a **task** or a **thing to know**. True means something of the user's moved — their app, or their tracked term — and there is a next step. False means it is intelligence: a competitor's 1–2★ wave, price cut or chart entry is worth knowing and has no move attached to it, because nothing of theirs changed. Lead an answer with the true ones and report the rest as context; the console draws exactly this line, so a briefing that ignores it disagrees with the screen the user is looking at."}, 'console_url': {'type': ['string', 'null'], 'description': "Where in the console this finding is shown. Always a page inside the user's own app, even for a finding about a competitor. End the answer with it."}, 'detected_at': {'type': 'string', 'description': 'When the detector wrote it, as an ISO timestamp.'}, 'storefronts': {'type': 'integer', 'description': "How many storefronts this ONE finding covers. A price re-tier is a single decision applied to up to 122 of them, so it is one finding here and not 122 — the console's feed shows it as one line for the same reason. 1 is the ordinary case; 0 means the event is not per-storefront at all."}, 'already_sent': {'type': ['boolean', 'null'], 'description': 'Whether this finding already went out in an alert digest the user has read. **Null means nobody asked** — set `include_sent` to find out. When it is true, lead with what is new instead of repeating what they read over breakfast.'}, 'owner_app_id': {'type': 'integer', 'description': "The app of the user's this hangs under. A rival's signal hangs under the app it was added as a competitor of, which is how a finding about somebody else is still a finding inside one of your niches."}}}, 'description': "The findings, newest first. Each carries the sentence that states it and the two numbers behind it. Empty is a real answer: it means nothing crossed a detector's threshold, which is the only way a threshold means anything."}, 'truncated': {'type': 'boolean', 'description': 'True when `count` is below `total`. Say the list is partial rather than presenting it as everything that happened.'}, 'by_severity': {'type': 'object', 'properties': {'neutral': {'type': 'integer', 'description': 'Worth knowing.'}, 'warning': {'type': 'integer', 'description': 'Something is going the wrong way.'}, 'critical': {'type': 'integer', 'description': 'Something relied on is gone.'}, 'opportunity': {'type': 'integer', 'description': 'Something got better.'}}, 'description': 'The severities among the findings returned. Counted over the returned rows, not the window, so it describes the list in hand.'}}}

{'type': 'object', 'properties': {'limit': {'type': 'integer', 'description': 'How deep to read the chart. Default 25, capped at 100.'}, 'store': {'enum': ['apple'], 'type': 'string', 'description': 'Only the App Store is covered. Google Play is in the data model but nothing is crawled for it, so omit this.'}, 'country': {'type': 'string', 'description': 'Storefront to read the chart for (e.g. US, GB, JP). Defaults to US. An unrecognised code falls back to US rather than failing — the reply echoes the storefront actually used, so check it.'}, 'category': {'type': 'string', 'description': 'Apple category id as a number, e.g. 6014 Games, 6015 Finance, 6017 Education, 6023 Food & Drink, 6013 Health & Fitness, 6012 Lifestyle. Omit for the overall chart across all categories. An id we do not recognise is ignored and you get the overall chart.'}, 'chart_type': {'enum': ['free', 'paid', 'grossing'], 'type': 'string', 'description': 'Which chart. Default free. Use grossing for revenue questions — top free ranks by downloads and says nothing about money. An unrecognised value falls back to free and the reply says which chart it read.'}}}

{'type': 'object', 'required': ['country', 'chart_type', 'count', 'apps'], 'properties': {'apps': {'type': 'array', 'items': {'type': 'object', 'required': ['position', 'app_id'], 'properties': {'icon': {'type': ['string', 'null'], 'description': 'Absolute URL of the app icon.'}, 'name': {'type': ['string', 'null'], 'description': 'The app\'s title **as published in `country`** — the string a shopper in that storefront reads, which is also the string Apple indexes. It is not a translation of one canonical name: an app localised for Mexico has a different title there, and `get_app(country: "mx")` returning the US one is what makes an agent report a localised app as "not localized". Falls back to the app\'s canonical name when this storefront has not been crawled yet, and is null only while a freshly imported app is still being processed.'}, 'price': {'type': ['number', 'null'], 'description': "Download price in `country`, in that storefront's own currency and in major units — 9.99, never 999. 0 means free, which is what most apps are; `currency` names the money. Null when this storefront has no listing on file."}, 'store': {'enum': ['apple', 'google'], 'type': ['string', 'null'], 'description': 'Which store the app belongs to.'}, 'app_id': {'type': 'integer', 'description': 'Apptail app ID. This is the `app_id` every other tool expects.'}, 'country': {'type': ['string', 'null'], 'description': 'Storefront the metrics below were read from. Defaults to `primary_country`.'}, 'is_mine': {'type': ['boolean', 'null'], 'description': 'True when this is one of the asking account\'s own apps. Null when the call carried no account — get_top_charts answers without a token — which is "not known here", not "no".'}, 'version': {'type': ['string', 'null'], 'description': 'Latest published version string.'}, 'currency': {'type': ['string', 'null'], 'description': 'ISO code of the currency `price` is in, derived from `country`. A price without it is a number, not an amount — several storefronts print a "$" and mean different money.'}, 'position': {'type': 'integer', 'description': 'Rank in the chart, 1 = top.'}, 'subtitle': {'type': ['string', 'null'], 'description': 'The subtitle under the title in `country` — thirty characters Apple indexes as heavily as the title, and the field most competitors leave generic. Null when the storefront listing has none, which is itself worth saying: an empty subtitle is unspent keyword weight.'}, 'bundle_id': {'type': ['string', 'null'], 'description': 'Store bundle identifier, e.g. "com.burbn.instagram".'}, 'console_url': {'type': ['string', 'null'], 'description': "Where to open this app in the AppTail console — the owner's own dashboard when `is_mine`, the research view otherwise. Null where this environment serves no console. End an answer about an app with it."}, 'apple_app_id': {'type': ['integer', 'null'], 'description': "Apple's own numeric app ID, as it appears in App Store URLs. Not interchangeable with `app_id`."}, 'rating_count': {'type': ['integer', 'null'], 'description': 'Number of ratings in `country`.'}, 'rating_average': {'type': ['number', 'null'], 'description': 'Mean star rating (1-5) in `country`. Null if the app has no ratings there yet.'}, 'primary_country': {'type': ['string', 'null'], 'description': 'Lowercase ISO country code of the app\'s main storefront, e.g. "us".'}, 'primary_category': {'type': ['integer', 'null'], 'description': 'Store category ID. Pass this as `category` to get_top_charts.'}, 'listing_storefronts': {'type': 'array', 'items': {'type': 'string'}, 'description': 'One storefront per language the listing is localized in, `primary_country` first, e.g. ["ru", "us"]. An app published in two languages is searched for in two storefronts; keyword discovery and tracking are per storefront, so cover each of these rather than only `primary_country`.'}, 'is_tracked_competitor': {'type': ['boolean', 'null'], 'description': 'True when the account already tracks this app as a competitor of one of theirs. False on a high-ranking rival is a suggestion worth making: add_competitors starts watching it. Null when the call carried no account.'}, 'primary_category_name': {'type': ['string', 'null'], 'description': 'Human-readable name of `primary_category`, e.g. "Health Fitness".'}}}, 'description': 'Chart entries, rank 1 first. Empty when no chart data exists for this country/category combination.'}, 'count': {'type': 'integer', 'description': 'Number of entries returned.'}, 'country': {'type': 'string', 'description': 'Storefront the chart was read from.'}, 'chart_type': {'enum': ['free', 'paid', 'grossing'], 'type': 'string', 'description': 'Which chart was read.'}}}

{'type': 'object', 'properties': {'to': {'type': 'string', 'description': 'End date, `YYYY-MM-DD`, inclusive. Send it alone and the window is the three years before it.'}, 'from': {'type': 'string', 'description': 'Start date, `YYYY-MM-DD`, inclusive. Overrides `period` when both are sent. Send it alone and the window runs to today.'}, 'period': {'type': 'string', 'description': 'The window to report on. A calendar month as `2026-07`, a calendar year as `2026`, `last_month`, `this_month`, `last_year`, or a trailing window: `today`, `7d`, `14d`, `30d`, `90d`, `180d`, `365d`, `730d`, `1095d`. Defaults to `30d`. A calendar period is compared against the calendar period before it — July against June, not against the 31 days ending 30 June. Three years is the ceiling.'}}}

{'type': 'object', 'required': ['count', 'limit', 'window', 'markets'], 'properties': {'count': {'type': 'integer', 'description': 'Markets this account keeps.'}, 'limit': {'type': 'integer', 'description': 'How many its plan allows. Equal to `count` means the next save is refused; say so before the user tries.'}, 'window': {'type': 'object', 'properties': {'days': {'type': 'integer'}, 'label': {'type': 'string'}, 'compareLabel': {'type': 'string'}}, 'description': 'The window every change figure below is measured over.'}, 'markets': {'type': 'array', 'items': {'type': 'object', 'required': ['status', 'storefront_count', 'terms', 'apps', 'fringe', 'apps_capped', 'size_covered', 'stale_terms', 'storefronts'], 'properties': {'apps': {'type': 'integer', 'description': "UNION: apps COMPETING in at least one storefront, counted ONCE however many they rank in. Competing means a top-10 place on at least one of this market's terms AND a top-50 place on at least two of them — one term is a coincidence and a place nobody scrolls to is not competition. Never the sum of the per-storefront counts: one app in three storefronts is one app. A FLOOR rather than a count when `apps_capped` is true. Everything else the store returned is in `fringe`."}, 'name': {'type': ['string', 'null'], 'description': 'What the market is called. Null for an unsaved reading.'}, 'slug': {'type': ['string', 'null'], 'description': 'Its address in the console.'}, 'terms': {'type': 'integer', 'description': 'SUM of the per-storefront corpora. The corpora are disjoint by construction — a term belongs to one storefront — so nothing is counted twice, and this is exactly what the market costs to crawl.'}, 'fringe': {'type': 'integer', 'description': "Apps that rank somewhere in this market's search results and are NOT competing in it: one term only, or no top-10 place anywhere. Typically several times `apps` — measured on a nine-storefront market, 578 competing against 2,001 fringe. They are real placements and worth naming as context (a store that seats an app beside yours), never as rivals. Counted once and never double-counted with `apps`: an app competing in one storefront and fringe in another is competing."}, 'spread': {'type': ['string', 'null'], 'description': 'open | contested | locked | mixed. `mixed` is the finding rather than a fudge: a niche locked in the US and open in Germany is the answer to "where should I launch this first". Storefronts in the same band report that band.'}, 'status': {'type': 'string', 'description': "draft | building | ready | failed. A market is `building` while ANY of its storefronts is — never report it ready because most of them landed. `ready` beats `failed`, so a market can read `ready` and still hold a storefront whose build died: check each storefront's `failed_at` before quoting its figures."}, 'overlap': {'type': ['number', 'null'], 'description': 'Of the apps holding a top-10 place in ANY storefront, the share holding one in EVERY storefront, 0-100. High means one leaderboard travels and a newcomer meets it wherever they launch; low means each storefront is its own contest, which is where an unowned storefront hides. NULL for a single-storefront market — it is not a question one place can answer.'}, 'built_at': {'type': ['string', 'null'], 'description': "The OLDEST of the storefronts' build times: a market is only as fresh as its worst."}, 'market_id': {'type': ['integer', 'null'], 'description': 'Apptail market id, or NULL when this reading was resolved from a phrase and not saved. Pass it to save_market to keep it, or to get_market to read it again for free.'}, 'newcomers': {'type': ['integer', 'null'], 'description': "Distinct apps that arrived in at least one storefront this window. Arriving in `de` while already ranking in `us` counts as arriving in this market. **NULL means no storefront had a previous window to compare against** — nothing of this corpus was crawled then, which is the normal state of a market built inside the window. Never read null as 0, and never report a new market's whole membership as newcomers."}, 'departures': {'type': ['integer', 'null'], 'description': 'Distinct apps that fell out of every storefront they held. Null on the same terms as `newcomers`.'}, 'apps_capped': {'type': 'boolean', 'description': 'True when the census stopped at its depth before it ran out of apps. `apps`, `newcomers`, `departures`, `downloads_30d` and `revenue_30d` are then floors, because all of them are summed over the counted set. Say "at least" rather than reporting the number as a total.'}, 'console_url': {'type': ['string', 'null'], 'description': 'This market in the console.'}, 'contest_low': {'type': ['number', 'null'], 'description': "The least contested storefront's share of top-10 slots held by its top three, 0-100."}, 'revenue_30d': {'type': ['integer', 'null'], 'description': 'ESTIMATE, same basis as downloads_30d.'}, 'stale_terms': {'type': 'integer', 'description': 'Corpus terms across the market past their 72-hour refresh.'}, 'storefronts': {'type': 'array', 'items': {'type': 'object', 'required': ['country', 'status', 'terms', 'apps', 'fringe', 'apps_capped', 'stale_terms', 'seed_terms'], 'properties': {'apps': {'type': 'integer', 'description': "Apps COMPETING here: a top-10 place on at least one of this corpus's terms AND a top-50 place on at least two, in the window. A FLOOR rather than a count when `apps_capped` is true. What ranks but does not clear that bar is `fringe`."}, 'band': {'type': ['string', 'null'], 'description': 'open | contested | locked — the word for `contest`. Under 45% is open, over 70% is locked. Null when contest is.'}, 'depth': {'type': ['integer', 'null'], 'description': 'MEDIAN apps matching a term across this corpus. BEING REFILLED: rows crawled before 30 Aug 2026 hold the length of the page Apple returned (~200 at most) rather than the real total, so a value near 200 is a floor and a whole corpus sitting near 200 is measuring pagination rather than depth. Treat it as a lower bound until the corpus has turned over, and prefer `contest` — which is measured from our own daily ranks — when the question is how crowded the niche is.'}, 'terms': {'type': 'integer', 'description': 'Corpus size here. What this storefront costs to crawl.'}, 'demand': {'type': ['integer', 'null'], 'description': "MEDIAN popularity across this corpus's terms. Never a sum: popularity is an index, and adding indices produces a number that exists nowhere."}, 'fringe': {'type': 'integer', 'description': "Apps ranking in this storefront's results without competing in it — one term, or never inside a top ten. Context, not rivals."}, 'status': {'type': 'string', 'description': 'draft | building | ready | failed. A `building` storefront has a corpus and no reading yet; report it as still landing rather than as empty. `failed` means the build died with nothing to read — its zeros are missing figures, NOT a finding about the niche, and the fix is a rebuild in the console.'}, 'contest': {'type': ['number', 'null'], 'description': 'Share of this corpus\'s top-10 slots held by its top three apps, 0-100. Measured from daily ranks, not modelled. NULL means undefined, not zero: with fewer than four apps holding anything, "the top three" is the whole field.'}, 'country': {'type': 'string', 'description': 'Two-letter storefront code, lower case.'}, 'built_at': {'type': ['string', 'null'], 'description': "When this storefront's corpus was last assembled. Null while it never has been."}, 'failed_at': {'type': ['string', 'null'], 'description': 'When the LAST build attempt failed, null when it succeeded. Independent of `status` and that is the point: a rebuild that dies over a storefront that already has a corpus stays `ready` with a real reading that is quietly OLDER than `built_at` says. When this is set, say so before quoting the figures.'}, 'newcomers': {'type': ['integer', 'null'], 'description': 'Apps with no top-50 place here in the previous window of the same length. NULL when no term of this corpus was measured in both windows — a storefront first crawled inside this window has no baseline, and "nobody crawled it" is not "nobody ranked".'}, 'age_months': {'type': ['integer', 'null'], 'description': 'Median months since first release among the head. A niche of four-year-olds and one of six-month-olds are different bets.'}, 'demand_top': {'type': ['integer', 'null'], 'description': 'The most popular single term in this corpus.'}, 'departures': {'type': ['integer', 'null'], 'description': 'The inverse: apps that held one then and do not now. Null on the same terms as `newcomers`.'}, 'last_error': {'type': ['string', 'null'], 'description': 'One sentence saying what failed. Null unless `failed_at` is set. Safe to repeat to the user verbatim.'}, 'seed_terms': {'type': 'array', 'items': {'type': 'string'}, 'description': "What this storefront's corpus was expanded FROM, in its own language. A leaderboard that looks wrong is nearly always a storefront asked the wrong question, and this is the question — check it before reporting the niche as empty or the members as odd. Change it with save_market's `seeds`, which rebuilds this storefront whole."}, 'apps_capped': {'type': 'boolean', 'description': "True when this storefront's census stopped at its depth before it ran out of apps. `apps` and everything summed over the member set are then floors."}, 'revenue_30d': {'type': ['integer', 'null'], 'description': 'ESTIMATE, same basis as downloads_30d.'}, 'seed_source': {'type': ['string', 'null'], 'description': "The storefront these terms were READ from, when nobody gave any. Null means they were typed. Otherwise they were lifted off the localised listings of that storefront's leaders and kept only because searching them here brought those same leaders back — good terms, and this product's guess rather than the user's words. Worth naming when reporting what a market was built on."}, 'stale_terms': {'type': 'integer', 'description': 'Corpus terms past their 72-hour refresh. A large share means this reading is older than it looks.'}, 'rating_floor': {'type': ['number', 'null'], 'description': 'Median rating of the head of this leaderboard — what a newcomer has to clear.'}, 'concentration': {'type': ['number', 'null'], 'description': "HHI over each app's share of the top-10 slots, 0-1. Contest says how much the head holds; this says whether the head is one app or three."}, 'downloads_30d': {'type': ['integer', 'null'], 'description': 'ESTIMATE, and a FLOOR. A third-party model, worldwide and 30-day, summed over this storefront\'s apps — with the apps the vendor would only bound ("under 5,000") left out entirely, since a ceiling cannot be added. Never present this as measured, and never differentiate two of them into a growth rate.'}}}, 'description': 'One entry per storefront, and the only level at which contest, demand and depth exist. Compare these rather than averaging them.'}, 'contest_high': {'type': ['number', 'null'], 'description': "The most contested storefront's. A RANGE, deliberately: there is no market-level contest to average."}, 'size_covered': {'type': 'integer', 'description': 'How many of the `apps` above carry an estimate at all, INCLUDING the ones the vendor would only bound as "under 1,000" / "under 5,000". Those contribute nothing to the sums, so a market with many small apps reports a size that is a floor. A total over 40 of 291 apps is a different statement from one over 280 — say which when quoting the size.'}, 'downloads_30d': {'type': ['integer', 'null'], 'description': 'ESTIMATE. A third-party model, worldwide and 30-day, summed over the UNION with each app counted once. Adding the per-storefront totals would count the same worldwide figure once per storefront and be wrong by roughly the storefront count.'}, 'storefront_count': {'type': 'integer', 'description': 'How many places this question is asked in.'}}}, 'description': 'One entry per market, newest first. Pass a `market_id` to get_market with include: ["members"] for the leaderboard behind any of them.'}}}

{'type': 'object', 'required': ['app_id', 'competitors'], 'properties': {'app_id': {'type': 'integer', 'description': "Apptail app id for one of YOUR apps — from get_account. Only this app's competitor set is touched."}, 'competitors': {'type': 'array', 'items': {'type': 'string'}, 'description': 'The rivals to stop tracking, up to 20. Each item is an Apptail app_id (as returned by get_competitors), a store URL, or a name. Ids are the reliable form here — a name is resolved against the whole store, not against what you track.'}}}

{'type': 'object', 'required': ['app_id', 'removed_count', 'requested_count', 'remaining', 'outcomes'], 'properties': {'app_id': {'type': 'integer', 'description': 'The app these rivals were tracked against.'}, 'outcomes': {'type': 'array', 'items': {'type': 'object', 'required': ['ref', 'status'], 'properties': {'ref': {'type': 'string', 'description': 'What was asked for, exactly as it was sent — an id, a name or a store URL. Match outcomes to your request by this, not by order.'}, 'name': {'type': ['string', 'null'], 'description': "The app's name, so the answer can name it rather than quoting an id back."}, 'app_id': {'type': ['integer', 'null'], 'description': 'Apptail app id, once the reference resolved to one. Null when nothing matched.'}, 'status': {'enum': ['added', 'already', 'removed', 'not_tracked', 'not_found', 'refused', 'would_add'], 'type': 'string', 'description': 'What happened to this one. `added` / `removed` are done. `already` means it was there before this call and nothing changed — not a failure. `not_tracked` means it was not there to remove. `not_found` means nothing in the store matched. `refused` means a rule said no and `message` says which. `would_add` only appears under `dry_run`, and nothing was written.'}, 'message': {'type': ['string', 'null'], 'description': 'Why, when this one did not do what was asked. Written for a person — quote it rather than rewriting it.'}, 'console_url': {'type': ['string', 'null'], 'description': 'Where the owner can see this app in the AppTail console.'}}}, 'description': 'One row per item. `not_tracked` means it was not a competitor of this app to begin with — the end state is what was asked for, but do not report it as a removal.'}, 'remaining': {'type': 'integer', 'description': 'How many competitors this app still tracks.'}, 'removed_count': {'type': 'integer', 'description': 'How many pairings were actually removed.'}, 'requested_count': {'type': 'integer', 'description': 'How many items were sent.'}}}

{'type': 'object', 'required': ['app_id', 'keyword_ids'], 'properties': {'app_id': {'type': 'integer', 'description': 'Apptail app id for one of YOUR apps — get it from get_account. Not the numeric id in an App Store URL (that is apple_app_id).'}, 'keyword_ids': {'type': 'array', 'items': {'type': 'integer'}, 'description': 'Apptail keyword ids to stop tracking, as returned by get_keywords. Ids, not terms — two apps can track the same word and only these rows are removed. Frees the slots against your plan limit. Position history is kept, so re-adding a term later does not start from nothing.'}}}

{'type': 'object', 'required': ['app_id', 'removed_count', 'requested_count', 'remaining'], 'properties': {'app_id': {'type': 'integer', 'description': 'The app these terms were tracked for.'}, 'remaining': {'type': 'integer', 'description': 'How many keywords this app still tracks, across every storefront.'}, 'removed_count': {'type': 'integer', 'description': 'How many keywords were actually untracked. Lower than `requested_count` when some IDs were not tracked for this app.'}, 'requested_count': {'type': 'integer', 'description': 'How many keyword IDs were passed in.'}}}

{'type': 'object', 'required': ['market_id'], 'properties': {'store': {'type': 'string', 'description': 'Drop only this storefront, ISO 3166-1 alpha-2. Omit to delete the whole market. Dropping the last storefront deletes the market too, because a market asked nowhere is not a market.'}, 'market_id': {'type': 'integer', 'description': 'Apptail market id — from list_markets.'}}}

{'type': 'object', 'required': ['market_id', 'name', 'deleted', 'removed_storefronts', 'remaining_storefronts', 'markets_remaining'], 'properties': {'name': {'type': 'string'}, 'deleted': {'type': 'boolean', 'description': 'True when the whole market is gone. False when only a storefront was dropped and the market remains.'}, 'market_id': {'type': 'integer'}, 'markets_remaining': {'type': 'integer', 'description': 'Markets left on the account after this call.'}, 'removed_storefronts': {'type': 'array', 'items': {'type': 'string'}, 'description': 'What this call removed.'}, 'remaining_storefronts': {'type': 'array', 'items': {'type': 'string'}, 'description': 'What the market is still asked in.'}}}

{'type': 'object', 'required': ['replies'], 'properties': {'dry_run': {'type': 'boolean', 'description': "Check every item and report what would happen, without publishing anything. **Worth using by default here** — it confirms the reviews resolve, the account's key reaches their apps and the text fits, before anything reaches the store."}, 'replies': {'type': 'array', 'items': {'type': 'object', 'required': ['review_id'], 'properties': {'body': {'type': 'string', 'description': 'The reply, exactly as it will appear on the App Store, at most 5970 characters. Write it in the language the review was written in. Required unless `remove` is true. Sending the text that is already on the review does nothing and comes back as `unchanged`, which is not a failure.'}, 'remove': {'type': 'boolean', 'description': 'Take the existing reply down instead of writing one. `body` is then ignored. Only ever on explicit instruction — a published reply that disappears is visible to everybody who read it.'}, 'review_id': {'type': 'integer', 'description': 'The Apptail review id, from `get_reviews`. Not the star rating and not the app id.'}}}, 'description': 'The replies, up to 10 per call. Send them in one call rather than one at a time: each is answered separately, so a batch where one app is not covered still posts the rest and says which it did not.'}}}

{'type': 'object', 'required': ['dry_run', 'requested_count', 'posted_count', 'removed_count', 'failed_count', 'max_items', 'outcomes'], 'properties': {'dry_run': {'type': 'boolean', 'description': 'True when nothing was sent to Apple. Every outcome is then what *would* have happened.'}, 'outcomes': {'type': 'array', 'items': {'type': 'object', 'required': ['status'], 'properties': {'state': {'enum': ['pending', 'published'], 'type': ['string', 'null'], 'description': 'Where the reply is on its way to the store — the same two words `reply_state` uses on a review from `get_reviews`. Apple takes a reply and publishes it some time later, so a fresh `posted` is nearly always `pending`. **Say "sent, pending publication", never "replied"** — somebody told the reply is live will go and look for it on the store, not find it, and think the product lied. Null when there is no reply, or when its state is unknown.'}, 'author': {'type': ['string', 'null'], 'description': 'Display name the reviewer posted under.'}, 'rating': {'type': ['integer', 'null'], 'description': "The review's star rating, so the answer can name it rather than quoting an id."}, 'status': {'enum': ['posted', 'removed', 'unchanged', 'not_replied', 'no_key', 'not_replyable', 'invalid', 'refused', 'would_post', 'would_remove'], 'type': 'string', 'description': "What happened to this one. `posted` means Apple took the reply — **read `state` before calling it published**. `removed` means the reply is gone. `unchanged` means the text asked for was already the text on the review and nothing was sent; that is the state that was asked for, not a failure. `not_replied` means there was no reply to remove. `no_key` means this account holds no App Store Connect API key reaching that app, and `not_replyable` means the review itself carries no App Store Connect id — neither is worth retrying. `no_key` is fixed by the owner in the console; `not_replyable` is fixed by a sync **unless** the review's `reply_unavailable` is true, in which case App Store Connect does not hold that review at all and nothing will fix it. `message` says which of the two it is; pass it on rather than promising a sync that will not help. `invalid` is the text (empty, or past Apple's limit). `refused` is Apple saying no, and `message` is what it said. `would_post` and `would_remove` appear only under `dry_run`, and nothing reached the store."}, 'country': {'type': ['string', 'null'], 'description': 'Lowercase ISO code of the storefront the review was left in.'}, 'message': {'type': ['string', 'null'], 'description': 'Why, when this one did not do what was asked — or what to tell the user when it did. Written for a person; quote it rather than rewriting it.'}, 'review_id': {'type': ['integer', 'null'], 'description': 'The Apptail review id this outcome is about, exactly as it was sent. Match outcomes to your request by this, not by order.'}, 'console_url': {'type': ['string', 'null'], 'description': "The app's Reviews screen in the console, where the owner can see the reply."}}}, 'description': 'One row per item, in the order they were sent. Read `status` per row, then `state` on the ones that posted.'}, 'max_items': {'type': 'integer', 'description': 'The per-call cap. A request above it is refused as a whole rather than silently trimmed.'}, 'failed_count': {'type': 'integer', 'description': 'How many did not do what was asked. Never report a batch as done while this is above zero — say which ones and why.'}, 'posted_count': {'type': 'integer', 'description': "How many replies Apple took. Read each one's `state` before calling any of them published."}, 'removed_count': {'type': 'integer', 'description': 'How many replies were taken down.'}, 'requested_count': {'type': 'integer', 'description': 'How many items were sent.'}}}

{'type': 'object', 'required': ['query', 'countries'], 'properties': {'name': {'type': 'string', 'description': 'What to call it. Defaults to `query`. Passing the name of a market this account already has ADDS the new storefronts to it rather than creating a second one.'}, 'query': {'type': 'string', 'description': 'The phrase to build the market from, e.g. "AI calorie tracking". Used as the seed in every storefront unless `seeds` overrides it.'}, 'seeds': {'type': 'object', 'description': 'Per-storefront seed terms, keyed by country code: {"de": ["kalorienzähler"]}. OPTIONAL, and optional per storefront. A storefront you leave out is not seeded from `query`: its terms are read off the localised listings of the leaders of the storefront that WAS phrased, and each one is searched there before it is kept — so it ends up with the local phrasing rather than an English phrase nobody types. Pass a storefront explicitly when you know the local phrase (to use the supplied local terms) or when you want to ask a different question there. Up to five terms each.'}, 'countries': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Storefronts to ask it in, ISO 3166-1 alpha-2 (e.g. ["US","DE"]). Each keeps its own corpus; nothing is blended across them.'}}}

{'type': 'object', 'required': ['market_id', 'name', 'slug', 'status', 'created', 'storefronts', 'added_storefronts', 'caveats'], 'properties': {'name': {'type': 'string'}, 'slug': {'type': 'string', 'description': 'Its address in the console.'}, 'status': {'type': 'string', 'description': '`building` immediately after a save. A market is building while ANY storefront is; each one lands separately. A build that dies leaves the storefront `failed` (or `ready` with `failed_at` set when a previous corpus survives) — it never stays `building` for ever.'}, 'caveats': {'type': 'array', 'items': {'type': 'string'}, 'description': 'What the caller needs to hear — that the build is not finished, or that a storefront was seeded from an English phrase.'}, 'created': {'type': 'boolean', 'description': 'True for a new market, false when storefronts were added to one that already existed.'}, 'market_id': {'type': 'integer', 'description': 'Pass it to get_market to read the market once it has built.'}, 'console_url': {'type': ['string', 'null'], 'description': 'The market in the console.'}, 'storefronts': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Every storefront this market is now asked in, including ones it already had.'}, 'added_storefronts': {'type': 'array', 'items': {'type': 'string'}, 'description': 'The ones this call added or rebuilt.'}}}

{'type': 'object', 'required': ['query'], 'properties': {'limit': {'type': 'integer', 'description': 'Max results. Default 10, capped at 25.'}, 'query': {'type': 'string', 'description': 'App name in any language, a bundle id (com.example.app), or a full App Store URL. Searches Apptail first and falls back to the App Store, importing anything it finds — so this returns a usable app_id even for an app we have never seen. This is how you turn a name a user typed into an app_id.'}, 'country': {'type': 'string', 'description': 'Storefront to search (e.g. "us", "ru"). Omit and it is guessed from the script the query is written in — Cyrillic implies ru, and so on. Pass it explicitly when the user names a market, because the guess is about language and not about where they sell.'}}}

{'type': 'object', 'required': ['count', 'source', 'apps'], 'properties': {'apps': {'type': 'array', 'items': {'type': 'object', 'required': ['app_id'], 'properties': {'icon': {'type': ['string', 'null'], 'description': 'Absolute URL of the app icon.'}, 'name': {'type': ['string', 'null'], 'description': 'The app\'s title **as published in `country`** — the string a shopper in that storefront reads, which is also the string Apple indexes. It is not a translation of one canonical name: an app localised for Mexico has a different title there, and `get_app(country: "mx")` returning the US one is what makes an agent report a localised app as "not localized". Falls back to the app\'s canonical name when this storefront has not been crawled yet, and is null only while a freshly imported app is still being processed.'}, 'price': {'type': ['number', 'null'], 'description': "Download price in `country`, in that storefront's own currency and in major units — 9.99, never 999. 0 means free, which is what most apps are; `currency` names the money. Null when this storefront has no listing on file."}, 'store': {'enum': ['apple', 'google'], 'type': ['string', 'null'], 'description': 'Which store the app belongs to.'}, 'app_id': {'type': 'integer', 'description': 'Apptail app ID. This is the `app_id` every other tool expects.'}, 'country': {'type': ['string', 'null'], 'description': 'Storefront the metrics below were read from. Defaults to `primary_country`.'}, 'is_mine': {'type': ['boolean', 'null'], 'description': 'True when this is one of the asking account\'s own apps. Null when the call carried no account — get_top_charts answers without a token — which is "not known here", not "no".'}, 'version': {'type': ['string', 'null'], 'description': 'Latest published version string.'}, 'currency': {'type': ['string', 'null'], 'description': 'ISO code of the currency `price` is in, derived from `country`. A price without it is a number, not an amount — several storefronts print a "$" and mean different money.'}, 'subtitle': {'type': ['string', 'null'], 'description': 'The subtitle under the title in `country` — thirty characters Apple indexes as heavily as the title, and the field most competitors leave generic. Null when the storefront listing has none, which is itself worth saying: an empty subtitle is unspent keyword weight.'}, 'bundle_id': {'type': ['string', 'null'], 'description': 'Store bundle identifier, e.g. "com.burbn.instagram".'}, 'console_url': {'type': ['string', 'null'], 'description': "Where to open this app in the AppTail console — the owner's own dashboard when `is_mine`, the research view otherwise. Null where this environment serves no console. End an answer about an app with it."}, 'apple_app_id': {'type': ['integer', 'null'], 'description': "Apple's own numeric app ID, as it appears in App Store URLs. Not interchangeable with `app_id`."}, 'rating_count': {'type': ['integer', 'null'], 'description': 'Number of ratings in `country`.'}, 'rating_average': {'type': ['number', 'null'], 'description': 'Mean star rating (1-5) in `country`. Null if the app has no ratings there yet.'}, 'primary_country': {'type': ['string', 'null'], 'description': 'Lowercase ISO country code of the app\'s main storefront, e.g. "us".'}, 'primary_category': {'type': ['integer', 'null'], 'description': 'Store category ID. Pass this as `category` to get_top_charts.'}, 'listing_storefronts': {'type': 'array', 'items': {'type': 'string'}, 'description': 'One storefront per language the listing is localized in, `primary_country` first, e.g. ["ru", "us"]. An app published in two languages is searched for in two storefronts; keyword discovery and tracking are per storefront, so cover each of these rather than only `primary_country`.'}, 'is_tracked_competitor': {'type': ['boolean', 'null'], 'description': 'True when the account already tracks this app as a competitor of one of theirs. False on a high-ranking rival is a suggestion worth making: add_competitors starts watching it. Null when the call carried no account.'}, 'primary_category_name': {'type': ['string', 'null'], 'description': 'Human-readable name of `primary_category`, e.g. "Health Fitness".'}}}, 'description': 'Matching apps, best match first. Empty when nothing was found.'}, 'hint': {'type': ['string', 'null'], 'description': 'Present when nothing was found: suggests how to retry.'}, 'note': {'type': ['string', 'null'], 'description': 'Present when the results need a caveat, e.g. data still being fetched in the background.'}, 'count': {'type': 'integer', 'description': 'Number of apps returned.'}, 'source': {'enum': ['url', 'database', 'app_store', 'none'], 'type': 'string', 'description': 'Where the results came from. "app_store" means they were just imported and are still being enriched.'}, 'country': {'type': ['string', 'null'], 'description': 'Storefront that was searched. Null when answered from the local database, which is not country-specific.'}}}

{'type': 'object', 'required': ['app_id', 'keyword_ids'], 'properties': {'tag': {'type': 'string', 'description': 'The tag name to put them under. Created if it does not exist. Omit — or send null — to clear the tag off these keywords instead.'}, 'color': {'type': 'string', 'description': 'Hex colour for a tag being created, e.g. "#2563eb". Ignored when the tag already exists. Omit and one is picked from the palette that the app is not already using.'}, 'app_id': {'type': 'integer', 'description': 'Apptail app id for one of YOUR apps — from get_account. Tags belong to an app.'}, 'keyword_ids': {'type': 'array', 'items': {'type': 'integer'}, 'description': 'Apptail keyword ids to tag, as returned by get_keywords. Ids, not terms. Up to 500 in one call. A keyword the app does not track is reported back rather than silently ignored.'}}}

{'type': 'object', 'required': ['app_id', 'action', 'tag_created', 'changed_count', 'requested_count', 'unknown_ids', 'tags'], 'properties': {'tag': {'type': ['object', 'null'], 'required': ['tag_id', 'name'], 'properties': {'name': {'type': 'string', 'description': 'What the tag is called.'}, 'color': {'type': ['string', 'null'], 'description': 'The colour it is drawn in, as a hex string. Decoration; do not read meaning into it.'}, 'tag_id': {'type': 'integer', 'description': 'Apptail tag id. Pass it to tag_keywords to assign this tag.'}, 'keywords': {'type': ['integer', 'null'], 'description': "How many of the app's tracked keywords carry this tag. Null when it was not counted for this call — never read a null as zero."}}, 'description': 'The tag the keywords now carry. Null when the action was `cleared`.'}, 'tags': {'type': 'array', 'items': {'type': 'object', 'required': ['tag_id', 'name'], 'properties': {'name': {'type': 'string', 'description': 'What the tag is called.'}, 'color': {'type': ['string', 'null'], 'description': 'The colour it is drawn in, as a hex string. Decoration; do not read meaning into it.'}, 'tag_id': {'type': 'integer', 'description': 'Apptail tag id. Pass it to tag_keywords to assign this tag.'}, 'keywords': {'type': ['integer', 'null'], 'description': "How many of the app's tracked keywords carry this tag. Null when it was not counted for this call — never read a null as zero."}}}, 'description': 'Every tag this app now has, so a follow-up call does not have to guess at names.'}, 'action': {'enum': ['assigned', 'cleared'], 'type': 'string', 'description': '`assigned` when a tag was set, `cleared` when the tag was taken off.'}, 'app_id': {'type': 'integer', 'description': 'The app whose corpus was changed.'}, 'tag_created': {'type': 'boolean', 'description': 'True when this call created the tag rather than reusing one. Worth mentioning: a typo makes a second tag rather than an error.'}, 'unknown_ids': {'type': 'array', 'items': {'type': 'integer'}, 'description': 'Ids this app does not track, so nothing was changed for them. Empty on a clean run. Never present these as tagged.'}, 'changed_count': {'type': 'integer', 'description': 'How many keywords were actually changed.'}, 'requested_count': {'type': 'integer', 'description': 'How many keyword ids were sent.'}}}