Dates are UTC
Every timestamp is UTC ISO 8601. Every daily value is adate string such as 2026-07-30, with no time and no offset, because the underlying column is a PostgreSQL date.
Today means the UTC date. An instance in Auckland and an instance in Los Angeles agree on which day a position belongs to, which is what makes histories comparable.
Do not localize a date string before comparing it. Parsing 2026-07-30 as local midnight and formatting it back can shift it by a day.
Positions are 1 based and null is meaningful
Position 1 is the top result.null means the keyword was checked and the app was not found within that row’s depth, which defaults to 200.
Render null as a bound derived from the row’s own depth, such as >200. See Positions and rank depth.
Queued operations return 202
Anything that enqueues store work answers immediately with202 and a job reference rather than waiting for a result.
Poll the resource afterwards rather than expecting the response to carry the result. A
202 is not a promise that the job succeeded, only that it was accepted.
Scores are 0 to 100
Traffic, difficulty and opportunity are all 0 to 100. Traffic and difficulty are stored with their provenance, while opportunity is computed per app on read and never persisted. Apple and Google Play scores come from different public evidence and are not directly comparable. See Traffic, difficulty and opportunity.installs is a BigInt
installs exceeds the safe integer range in the database, so it is stored as a BigInt and serialized as a JSON number. A client reading it into a 64 bit integer type is fine. A client reading it into a JavaScript number is also fine at realistic install counts.
Country codes are two letters
A country is two lowercase letters such asus, gb or de, validated by shape rather than against a fixed list, so any live storefront works. Uppercase is rejected.
Country belongs to the keyword, not to the app, which is why so many endpoints take one. See Countries and markets.
Rate limits apply to collection, not to the API
Reading the API is not rate limited beyond the auth endpoints, which throttle per client IP address. What is limited is store collection, bySCRAPE_ITUNES_RPM and SCRAPE_GPLAY_RPM.
So a script may read as often as it likes, but queuing work has a real cost. GET /jobs/budget returns the estimated daily fan out broken down by kind alongside your capacity, which is the right thing to check before adding keywords or markets programmatically. See The daily pipeline and rate limits.
Related
Error responses
What a failure looks like.
Data model
The entities behind the endpoints.