Charts

Top free/paid/grossing chart with day-over-day movement

Market-wide store chart (no tracked apps needed). 1 credit. The first request for a (store, country, chart, category) combo on a given day fetches it live and snapshots it; later requests that day are served from the snapshot. summary, movers and droppedApps always describe the whole top 200 — limit truncates entries only. A combo requested for the first time has no previous snapshot, so previousMeasuredAt is null and every delta is null. A live fetch is awaited only until the request deadline (API_REQUEST_DEADLINE_MS, or X-Sonar-Time-Budget-Ms minus 2s); past it the newest stored snapshot (≤7 days old) is served with stale: true and its measuredAt date while the fetch finishes in the background, so the next request is fresh. With nothing stored the endpoint returns 503 refresh_in_progress (Retry-After 20).

get/api/v1/charts/top

Request

  • Base URL: https://api.trysonar.app
  • URL: https://api.trysonar.app/api/v1/charts/top
  • Auth: one of:
    • none
    • HTTP bearer

Query parameters

store'ios' | 'android'

App store

countrystring

ISO 3166-1 alpha-2 country code. Every Google Play market and every App Store storefront except 58 small ones that have no numeric storefront id (Apple would silently answer with the US store, so they return 400 with error.reason: "unsupported_market"; app lookup, search and reviews still work there).

chart'free' | 'paid' | 'grossing'

Chart type

categorystring

Normalized category key (e.g. HEALTH_AND_FITNESS on iOS, GAME on Android), or overall for the store-wide chart

limitinteger

Chart entries to return

Headers

X-Sonar-Time-Budget-Msinteger

Optional: total milliseconds the caller will wait for the response. The server stops starting store work before it ends and answers with what it has — cached, stale, or pending keywords (queued on the scrape fleet, not billed); charts serve the newest stored snapshot. Can only shorten the server default (API_REQUEST_DEADLINE_MS, 40s on the API box); values under 3000 are treated as 3000. The MCP tools send it.

Response

Chart entries with movement, summary, movers and dropped apps

Changes

No recorded changes to this operation across all 1 revision of this API.