GET /v1/apps/:id/country-rankings
Path Parameters
| Name | Type | Required | Description |
|---|
| id | string | Yes | Apple App ID (numeric, e.g. 1617391485) |
Query Parameters
| Name | Type | Default | Description |
|---|
| chart | string | top-free | Chart type: top-free, top-paid, or top-grossing |
| includeReviews | number | 0 | Set to 1 to include per-country review counts |
Code Examples
curl -X GET "https://api.appeeky.com/v1/apps/1617391485/country-rankings?chart=top-free&includeReviews=0" \
-H "X-API-Key: YOUR_API_KEY"
Response
{
"data": {
"appId": "1617391485",
"chart": "top-free",
"rankings": [
{
"rank": 3,
"rankChange1D": null,
"country": "United States",
"countryCode": "US",
"reviewsCount": null
},
{
"rank": 1,
"rankChange1D": null,
"country": "United Kingdom",
"countryCode": "GB",
"reviewsCount": null
},
{
"rank": 7,
"rankChange1D": null,
"country": "Germany",
"countryCode": "DE",
"reviewsCount": null
},
{
"rank": 2,
"rankChange1D": null,
"country": "France",
"countryCode": "FR",
"reviewsCount": null
},
{
"rank": 12,
"rankChange1D": null,
"country": "Japan",
"countryCode": "JP",
"reviewsCount": null
},
{
"rank": 5,
"rankChange1D": null,
"country": "Canada",
"countryCode": "CA",
"reviewsCount": null
},
{
"rank": 9,
"rankChange1D": null,
"country": "Australia",
"countryCode": "AU",
"reviewsCount": null
},
{
"rank": 4,
"rankChange1D": null,
"country": "Brazil",
"countryCode": "BR",
"reviewsCount": null
},
{
"rank": 18,
"rankChange1D": null,
"country": "India",
"countryCode": "IN",
"reviewsCount": null
},
{
"rank": 6,
"rankChange1D": null,
"country": "Mexico",
"countryCode": "MX",
"reviewsCount": null
}
]
}
}
Response with includeReviews=1
{
"data": {
"appId": "1617391485",
"chart": "top-free",
"rankings": [
{
"rank": 3,
"rankChange1D": null,
"country": "United States",
"countryCode": "US",
"reviewsCount": 1832497
},
{
"rank": 1,
"rankChange1D": null,
"country": "United Kingdom",
"countryCode": "GB",
"reviewsCount": 284510
}
]
}
}
Ranking Object
| Field | Type | Description |
|---|
| rank | number | Position in the country’s Top 100 chart (1–100) |
| rankChange1D | number | null | Rank change in the last 24 hours. Always null without historical data |
| country | string | Full country name (e.g. "United States") |
| countryCode | string | ISO 3166-1 alpha-2 country code (e.g. "US") |
| reviewsCount | number | null | Total review count in that country. null unless includeReviews=1 |
Chart Types
| Chart | Description |
|---|
top-free | Most downloaded free apps |
top-paid | Most downloaded paid apps |
top-grossing | Highest revenue apps (free + paid) |
Supported Countries
The API checks the following 26 countries for chart presence:
| Code | Country | Code | Country | Code | Country |
|---|
| US | United States | GB | United Kingdom | DE | Germany |
| FR | France | JP | Japan | CN | China |
| KR | South Korea | IN | India | BR | Brazil |
| RU | Russia | NG | Nigeria | AR | Argentina |
| PK | Pakistan | CA | Canada | AU | Australia |
| ES | Spain | IT | Italy | MX | Mexico |
| IQ | Iraq | AF | Afghanistan | AO | Angola |
| AZ | Azerbaijan | BH | Bahrain | BJ | Benin |
| BO | Bolivia | BF | Burkina Faso | | |
Only apps in a country’s Top 100 chart will appear. If an app isn’t charting in any country’s Top 100 for the specified chart type, the rankings array will be empty. A popular app may still not appear if it ranks outside the top 100 in every tracked country.
Setting includeReviews=1 adds per-country review counts to each ranking, but this makes the request significantly slower (~25 extra API calls, one per country). Only enable this when you specifically need per-country review data.
An empty rankings array doesn’t mean the app has zero downloads — it means the app is not currently in any tracked country’s Top 100 for the specified chart type. Try different chart types (top-free, top-paid, top-grossing) for broader results.
Errors
| Status | Code | When |
|---|
| 400 | INVALID_APP_ID | Non-numeric or missing app ID |
| 400 | INVALID_CHART_TYPE | Chart type not top-free, top-paid, or top-grossing |
| 401 | MISSING_API_KEY | No API key in the request |
| 401 | INVALID_API_KEY | Invalid or expired API key |
| 404 | APP_NOT_FOUND | App not found or unavailable |
