Get the most popular applications for a category and type in a country for a device.
Retrieve current or historical top charts for all the countries that are available on AppTweak. A top chart is dependent on:
- a country
- a category
- a device
- a chart type (Free, Paid or Grossing)
You need to pass the correct category ID when making an API call on Top Charts, you can find Android Categories IDs or App Store Categories IDs. in their dedicated our reference sections.
You can get up to 500 app results. Refer to the following tables to find the maximum available top charts by Store & by chart type (Free, Paid or Grossing) for the Current and Historical Endpoints.
Top Charts - Current
| Store | Free | Paid | Grossing |
|---|---|---|---|
| App Store | Top 500 | Top 500 | Top 200 |
| Google Play | Top 200 | Top 200 | Top 200 |
Top Charts - History
| Store | Free | Paid | Grossing |
|---|---|---|---|
| App Store | Top 500 | Top 500 | Top 200 |
| Google Play | Top 200 | Top 200 | Top 200 |
Change in top charts of Google PlayOn the 24th of February 2023 Google Play lowered the top charts from Top 500 to Top 200 for all chart type (free, paid & grossing).
FAQs
How do I fetch an app's current category ranking via API?
You can pull an app's current position in a category chart with AppTweak's Top Charts - Current endpoint (GET /charts/top-results/current.json). Pass the category ID via categories, the device (iphone, ipad, or android), the country, and a types value (free, paid, or grossing, default free). The response returns a ranked array of app IDs (or bundle IDs for Android) under that category and chart type, with the chart's date — look up your app's ID in the array to get its rank.
How do I retrieve historical app store category rankings over a date range via API?
You can pull a date range of past category rankings with AppTweak's Top Charts - History endpoint (GET /charts/top-results/history), using start_date and end_date (format YYYY-MM-DD; default is the last 30 days). Combined with categories, country, device, and types, it returns one ranked array of app IDs per day in the range, so you can plot how a category's ranking order changed day by day rather than seeing only the current snapshot.
Can I get top chart rankings for both iOS and Google Play through one API?
Yes — both Top Charts endpoints (GET /charts/top-results/current.json and GET /charts/top-results/history) cover the App Store and Google Play through the same device parameter (iphone, ipad, or android). The category IDs differ by store, though: App Store and Google Play use separate category ID systems, referenced on their own dedicated category-ID pages, so the categories value you pass has to match the store you're querying.
How many apps can I retrieve from a single app store ranking API call?
The number of apps returned depends on the store and chart type, up to a documented maximum, and is capped further by the limit parameter (max 500) on each call. For App Store, free and paid charts go up to top 500 and grossing up to top 200. For Google Play, free, paid, and grossing charts all cap at top 200 — a limit Google Play applied to every chart type on 24 February 2023, replacing its earlier top 500 depth.
What does a top charts API call return for a ranked app — just an ID, or more?
A Top Charts call returns only the ranked list of app identifiers for the requested category and chart type, not full app details. Each result is keyed by category and chart type, holding a value array of app IDs (numeric IDs for iOS, bundle IDs like com.example.app for Android) in rank order, plus a date for when that ranking applied. To get metadata (name, icon, ratings) for the ranked apps, look those IDs up against AppTweak's app metadata endpoint separately.