> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appeeky.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Country Rankings

> Get an app's chart rankings across all supported countries

```
GET /v1/apps/:id/country-rankings
```

Retrieve an app's chart rankings across all supported countries. Returns the app's position in each country's Top 100 chart where it currently appears.

## Path Parameters

| Name | Type   | Required | Description                                                                              |
| ---- | ------ | -------- | ---------------------------------------------------------------------------------------- |
| id   | string | Yes      | App ID — numeric for Apple (`1617391485`), package name for Google (`com.spotify.music`) |

## Query Parameters

| Name           | Type   | Default    | Description                                                                      |
| -------------- | ------ | ---------- | -------------------------------------------------------------------------------- |
| platform       | string | `apple`    | `apple` (default) or `google` for Google Play — see [Platforms](/docs/platforms) |
| 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                                  |
| lang           | string | `en`       | Google Play language code (used when `platform=google`)                          |

## Code Examples

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X GET "https://api.appeeky.com/v1/apps/1617391485/country-rankings?chart=top-free&includeReviews=0" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch(
    "https://api.appeeky.com/v1/apps/1617391485/country-rankings?chart=top-free&includeReviews=0",
    {
      headers: {
        "X-API-Key": "YOUR_API_KEY",
      },
    }
  );

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  response = requests.get(
      "https://api.appeeky.com/v1/apps/1617391485/country-rankings",
      params={"chart": "top-free", "includeReviews": 0},
      headers={"X-API-Key": "YOUR_API_KEY"},
  )

  data = response.json()
  print(data)
  ```
</CodeGroup>

## Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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`

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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   |      |           |

<Warning>
  **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.
</Warning>

<Tip>
  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.
</Tip>

<Note>
  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.
</Note>

## 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                             |