API Reference

The REST endpoints, their parameters and their response schemas.

Base URL: https://appatlas.dev/api/v1

Android SDK version

The newest dev.appatlas:atlas-links release on Maven Central. The response body is a single JSON string. The Android artifacts release together, so this is the version of atlas-core, atlas-crash and atlas-crash-ndk too.

Apple SDK version

The newest AppAtlasSDK release on the CocoaPods trunk. The response body is a single JSON string. Swift Package Manager resolves the same tag, so this is the SPM version as well.

.NET SDK version

The newest AppAtlas.Sdk release on NuGet. The response body is a single JSON string.

Track ID lookup

Turns an App Store bundle_id into its numeric track_id. The response body is a single JSON string. Unknown identifiers answer 404.

bundle_id — The reverse-DNS bundle identifier, e.g. com.netflix.Netflix.

Bundle ID lookup

Turns an App Store track_id into its bundle_id. The response body is a single JSON string. Unknown identifiers answer 404.

track_id — The numeric ID from the store URL, e.g. 363590051.

Product ID lookup

Turns a Microsoft Store package_family_name into its product_id. The response body is a single JSON string. Unknown identifiers answer 404.

package_family_name — The package family name, e.g. 4DF9E0F8.Netflix_mcm4njqhnhss8.

Package Family Name lookup

Turns a Microsoft Store product_id into its package_family_name. The response body is a single JSON string. Unknown identifiers answer 404. Win32 products (XP… ids) have no package family name and also answer 404.

product_id — The 12-character store ID, e.g. 9WZDNCRFJ3TJ.

Access token

Exchanges an API key (issued on the account page) for a one-hour Bearer access token. Send it as an Authorization: Bearer header on every call. There is no refresh token: when it expires, exchange the key again. Revoking the key ends the exchange and kills its live tokens.

Current permissions

What a call would actually be allowed to do right now: the key's policy met with what the stores allow. Each connected store is re-checked when its last verification has gone stale, so a key revoked at the store drops out of grants here rather than failing your next call. global lists the account-level actions; grants carries one line per store and action set, apps merged, actions the meet of what was granted and what the store permits. readOnly is true only when the caller holds no grants and no account-level actions at all; anonymous first-party reads answer readOnly true with empty lists.

App info

The full listing for one app: name, description, developer, pricing, rating, screenshots, videos and categories. Daily history comes from the analytics endpoint.

lang — ISO 639-1 language code. Decides the language of the store listing text, prices and reviews.
country — ISO 3166-1 alpha-2 country code. Decides the storefront, and therefore price, currency and availability.
<identifier> — The identifier for the store in the path: package_name, track_id / bundle_id, or product_id / package_family_name. Omitting it returns 422.

App builds

The builds the store took for an app you manage, newest first, each with what its delivery mail would warn about. App Store only; other stores return an empty list. Gated like official analytics: a session, an API key with data:read, or an embed grant reaches it, and anyone else gets an empty list rather than a 404, so it never reveals that builds exist.

page — Zero-based page index. Default 0.
size — Builds per page. 1-100, default 5.
sort — Order by uploaded (default), version or state.
direction — desc (default) or asc.
state — Keep only these processing states, comma-separated (VALID, PROCESSING, INVALID, FAILED). All states when omitted.
q — Match the build number or marketing version.
<identifier> — The identifier for the store in the path: package_name, track_id / bundle_id, or product_id / package_family_name. Omitting it returns 422.

App analytics

Daily snapshots and, for a managing caller, the store's own analytics. No listing scrape runs behind it. How much history comes back is one parameter, <code>span</code>.

span — How much history to return. Default 30d. <code>n</code> is a natural number, <code>u</code> is one of d, w, m, y, and <code>A</code> and <code>B</code> are a dated form. <code>yyyy</code> that year <code>yyyy</code>-<code>MM</code> that month <code>yyyy</code>-W<code>ww</code> that ISO week <code>yyyy</code>-<code>MM</code>-<code>dd</code> that day <code>u</code> the current one <code>n</code><code>u</code> the current one and the <code>n</code>-1 before it <code>n</code>c the latest <code>n</code> records 0c no history <code>A</code>~<code>B</code> from <code>A</code> to <code>B</code>, both ends included <code>A</code>~ from <code>A</code> onward ~<code>B</code> up to <code>B</code> ~ everything <code>n</code>c~<code>A</code> the <code>n</code> records ending at <code>A</code> <code>A</code>~<code>n</code>c the <code>n</code> records from <code>A</code> <code>n</code><code>u</code>~<code>A</code> the <code>n</code> units ending at <code>A</code> <code>A</code>~<code>n</code><code>u</code> the <code>n</code> units from <code>A</code>
official — Set to 1 to also return the store's own analytics as the official field, for a caller authorised to manage the app. The managing identifier is the one you sent: package_name on Google Play, bundle_id on the App Store. Ignored for anyone else.
lang — ISO 639-1 language code. Only used to resolve an App Store bundle_id to its track id; the history itself has no language.
country — ISO 3166-1 alpha-2 country code. Observation is per storefront, so this decides which country's history is read.
<identifier> — The identifier for the store in the path: package_name, track_id / bundle_id, or product_id / package_family_name. Omitting it returns 422.

Category lookup

Resolves one category id to its localized display name, store link and embed address. It is the same row the categories endpoint lists. This endpoint reads no app identifier.

id — The category id to resolve. An unknown id returns 404.
content_type — Which listing: app or game. Defaults to app.
pricing_type — Which chart the returned link and embed point at: free or paid. Defaults to free.
lang — ISO 639-1 language code. Decides the language of the store listing text, prices and reviews.
country — ISO 3166-1 alpha-2 country code. Decides the storefront, and therefore price, currency and availability.

Top charts

The store's top chart (free, paid or grossing), for the whole store or for one category. Returns the same lightweight card as search. This endpoint reads no app identifier.

id — A category id from the categories endpoint. Omit it for the whole store's chart. An unknown id returns 404.
content_type — Which listing: app or game. Defaults to app.
pricing_type — Which chart: free, paid or grossing. The Microsoft Store has no grossing chart and answers 422 for it.
lang — ISO 639-1 language code. Decides the language of the store listing text, prices and reviews.
country — ISO 3166-1 alpha-2 country code. Decides the storefront, and therefore price, currency and availability.
count — Maximum number of items to return: 1-200, default 20. Stores may return fewer.
token — Continuation token from the previous page; omit for the first. When present, every other parameter is ignored in favour of the token's own snapshot; a malformed token returns 400. The response's token is null at the end of the list.

Reviews

A page of user reviews, including the developer's reply when one exists. Paginate by feeding the returned token back in.

order_by — Sort order: recent or helpful, default recent. helpful surfaces the most-voted reviews first; on Google Play it is Google's relevance sort.
token — Continuation token from the previous page; omit for the first. When present, every other parameter is ignored in favour of the token's own snapshot; a malformed token returns 400. The response's token is null at the end of the list.
official — Set to 1 to read reviews from the store's own API instead of the scrape, for a caller authorised to manage the app. Their ids are the ones a reply accepts. Ignored, and the scrape is returned, for anyone else. See canReply in the response.
lang — ISO 639-1 language code. Decides the language of the store listing text, prices and reviews.
country — ISO 3166-1 alpha-2 country code. Decides the storefront, and therefore price, currency and availability.
count — Maximum number of items to return: 1-200, default 20. Stores may return fewer.
<identifier> — The identifier for the store in the path: package_name, track_id / bundle_id, or product_id / package_family_name. Omitting it returns 422.

Reply to a review

Posts the developer reply to one review. Posting again replaces the existing reply, which is how a reply is edited. Only for an app the caller manages through a connected store key; the review id must come from the official list (official=1 on reviews).

Delete a reply

Deletes the developer reply to one review. App Store only. Google Play's API can replace a reply but never remove one, so play-store returns 400 unsupported_store. Deleting a review that has no reply is a no-op success.

Translate a review

Translates one review into the requested language and detects the language it was written in. Works for any review the reviews endpoint served: scraped or official, your own app or not. Each review in that response carries a signed reviewKey; send it back with the review's exact title and content, and the signature proves the text is what was served. Translations are cached per review and language; an edited review is translated afresh.

Draft a reply

Drafts a developer reply to one review and returns it as text. Nothing is sent to any store: posting stays with the reply endpoint and the person behind it. The draft is written in the review's own language; the response also carries the same reply rendered in your lang for checking, null when the two match. Send back the reviewKey from the reviews response with the review's exact title and content, like translation. The same review and options answer from storage for free; set regenerate to get a new take (the previous ones are kept).

Search

Search the store by keyword. Returns a lightweight card per app rather than the full listing.

query — The search keyword. Required in practice: omitting it answers 422.
lang — ISO 639-1 language code. Decides the language of the store listing text, prices and reviews.
country — ISO 3166-1 alpha-2 country code. Decides the storefront, and therefore price, currency and availability.
count — Maximum number of items to return: 1-200, default 20. Stores may return fewer.
token — Continuation token from the previous page; omit for the first. When present, every other parameter is ignored in favour of the token's own snapshot; a malformed token returns 400. The response's token is null at the end of the list.

Similar apps

Apps the store itself recommends alongside the given app. Same card shape as search.

lang — ISO 639-1 language code. Decides the language of the store listing text, prices and reviews.
country — ISO 3166-1 alpha-2 country code. Decides the storefront, and therefore price, currency and availability.
count — Maximum number of items to return: 1-200, default 20. Stores may return fewer.
token — Continuation token from the previous page; omit for the first. When present, every other parameter is ignored in favour of the token's own snapshot; a malformed token returns 400. The response's token is null at the end of the list.
<identifier> — The identifier for the store in the path: package_name, track_id / bundle_id, or product_id / package_family_name. Omitting it returns 422.

News

Recent articles about the app, filtered for relevance and recency. Resolves the app name first, then runs a widening query ladder so a niche app still gets results without a common-noun app returning noise.

lang — ISO 639-1 language code. Decides the language of the store listing text, prices and reviews.
country — ISO 3166-1 alpha-2 country code. Decides the storefront, and therefore price, currency and availability.
count — Maximum number of items to return: 1-200, default 20. Stores may return fewer.
token — Continuation token from the previous page; omit for the first. When present, every other parameter is ignored in favour of the token's own snapshot; a malformed token returns 400. The response's token is null at the end of the list.
<identifier> — The identifier for the store in the path: package_name, track_id / bundle_id, or product_id / package_family_name. Omitting it returns 422.

News thumbnails

Resolves Google News redirect URLs to their publisher URL and extracts an og:image for each. Store-agnostic: it takes any list of article URLs.

List deep links

Every deep link on the account, newest first, each with the visits counted for it. Needs the deeplink:read permission on the key.

Create a deep link

Creates a link and returns it with its short URL. The short id is assigned by us and cannot be chosen. Refused with 403 plan_limit when the plan's link allowance is already used up. Needs the deeplink:create permission.

Read a deep link

One link and its full routing config. Needs the deeplink:read permission.

short_id — The link's short id, the last part of its short URL.

Update a deep link

Replaces the link's name and routing config. The whole config is written, so send it complete: fields left out are dropped, not kept. The short URL never changes, so a link already in the wild keeps working. Needs the deeplink:update permission.

short_id — The link's short id, the last part of its short URL.

Delete a deep link

Deletes the link and every visit recorded for it. The short URL stops resolving at once, and the id is never reissued. Needs the deeplink:delete permission.

short_id — The link's short id, the last part of its short URL.

Deep-link analytics

What happened to the visits: totals, unique visitors, the route each launch settled on, and breakdowns by OS and country. A repeat visit seconds after one that counted is kept as a row but left out of every number here. The options block always describes the whole period, so a picker keeps entries the current filter excludes. Needs the deeplink:stats permission.

short_id — The link's short id, the last part of its short URL.
span — Which days to aggregate, in the window grammar the analytics endpoint reads. Default 30d. A record count (30c) is refused: a visit has none to count.
countries — Comma-separated country codes to narrow to; "unknown" selects visits with no country.
routes — Comma-separated routes to narrow to; "failed" selects launches where every candidate failed.
os — Comma-separated operating systems to narrow to.
channels — Comma-separated channels to narrow to; "unknown" selects visits with no ch label.
campaigns — Comma-separated campaigns to narrow to; "unknown" selects visits with no cp label.
sources — Comma-separated arrival sources to narrow to: qr, push, or web for an ordinary open.

Start observing

Registers the app for daily snapshot collection at 00:00 UTC. Once registered, the app info response starts carrying a snapshots history of rating, review count, totalInstalls and version over time.

country — ISO 3166-1 alpha-2 country code. Decides the storefront, and therefore price, currency and availability.
<identifier> — The identifier for the store in the path: package_name, track_id / bundle_id, or product_id / package_family_name. Omitting it returns 422.

Stop observing

Removes the registration. Collected history is not deleted, but no new snapshots are taken.

country — ISO 3166-1 alpha-2 country code. Decides the storefront, and therefore price, currency and availability.
<identifier> — The identifier for the store in the path: package_name, track_id / bundle_id, or product_id / package_family_name. Omitting it returns 422.

App Atlas · Embed Reference · SDK Reference · Terms of Service · Privacy Policy · Sign up

ko · zh