App Store Rankings — Charts & Keyword Positions

Apple publishes where an app stands today and keeps no history of it. This Actor captures both kinds of ranking as clean JSON, for any storefront:

• Chart rank — "this app is #3 in Top Free / Germany / Games right now"
• Keyword rank — "this app is #7 when someone searches vpn in Germany"

Run it on a schedule and you own a ranking history nobody can reconstruct later — Apple does not serve yesterday's charts at any price.

What you get

One row per app, per list, per run:

{
  "capturedOn": "2026-08-22",
  "country": "de",
  "listKind": "chart",
  "listId": "chart:top-free",
  "chart": "top-free",
  "genreId": null,
  "term": null,
  "rank": 3,
  "app": {
    "id": "1234567890",
    "name": "Example App",
    "developer": "Example GmbH",
    "bundleId": "com.example.app",
    "price": 0,
    "currency": "EUR",
    "genre": "Utilities"
  }
}

Keyword rows carry listKind: "keyword", term, and chart: null.

Input

Field	Meaning	Default
countries	Storefronts, two-letter lowercase (de, us, gb); max 4	["de","us"]
charts	top-free, top-paid, top-grossing	["top-free","top-paid"]
genreIds	Apple genre ids collected in addition to the overall chart, e.g. 6014 (Games)	[]
keywords	Search terms to rank (max 10)	["vpn","photo editor","budget"]
chartLimit	Positions per chart (Apple caps at 200)	50
keywordLimit	Positions per keyword	25
maxResults	Hard cap on rows for the run	5000

Runtime

Apple's endpoints are queried politely, and the run time is set by how many lists you ask for, not by how many rows come back:

lists = countries × charts × (1 + genreIds) + countries × keywords

The first ten lists take about two seconds each; beyond that the politeness budget holds at ten requests a minute, so each further list adds roughly six seconds.

Input	Lists	Roughly
Defaults (2 countries, 2 charts, 3 keywords)	10	30 seconds
3 countries, 3 charts, 5 keywords	24	~2 minutes
The input maximum	76	7–8 minutes

The maxItems limits (4 countries, 3 charts, 2 genres, 10 keywords) exist to keep a run from silently becoming a half-hour job. Split a bigger job across scheduled runs.

Notes

• Public, unauthenticated Apple endpoints only: the iTunes RSS chart feeds and the iTunes Search API. No login, no paywall, nothing circumvented.
• No personal data, and no reviews — only app metadata and list positions.
• A ranking is a snapshot of the moment it was taken. Charts move during the day; schedule the run at a fixed hour if you want comparable days.