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

# Downloads to Top

> Estimate daily downloads needed to reach specific chart positions in any App Store category

## Endpoint

```
GET /v1/categories/:genreId/downloads-to-top
```

## Authentication

Requires `X-API-Key` header.

## Path Parameters

| Parameter | Type   | Required | Description                                                                          |
| --------- | ------ | -------- | ------------------------------------------------------------------------------------ |
| genreId   | string | Yes      | Genre ID, or `all`. Apple: numeric (`6014` for Games); Google: category key (`GAME`) |

## Query Parameters

| Parameter | Type   | Default    | Description                                                                      |
| --------- | ------ | ---------- | -------------------------------------------------------------------------------- |
| platform  | string | `apple`    | `apple` (default) or `google` for Google Play — see [Platforms](/docs/platforms) |
| country   | string | `us`       | Two-letter ISO country code                                                      |
| chart     | string | `top-free` | Chart type: `top-free`, `top-paid`, or `top-grossing`                            |
| lang      | string | `en`       | Google Play language code (used when `platform=google`)                          |

## Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "category": {
      "id": "all",
      "name": "All"
    },
    "country": "us",
    "chartType": "top-free",
    "tiers": [
      {
        "rank": 1,
        "estimatedDailyDownloads": 699297,
        "estimatedMonthlyDownloads": 20978910,
        "app": {
          "appId": "6448311069",
          "name": "ChatGPT",
          "developer": "OpenAI OpCo, LLC",
          "icon": "https://is1-ssl.mzstatic.com/...",
          "rating": 4.8,
          "reviews": 5818679
        }
      },
      {
        "rank": 5,
        "estimatedDailyDownloads": 223626,
        "estimatedMonthlyDownloads": 6708780,
        "app": { "..." : "..." }
      },
      {
        "rank": 10,
        "estimatedDailyDownloads": 77183,
        "estimatedMonthlyDownloads": 2315490,
        "app": { "..." : "..." }
      },
      {
        "rank": 25,
        "estimatedDailyDownloads": 53666,
        "estimatedMonthlyDownloads": 1609980,
        "app": { "..." : "..." }
      },
      {
        "rank": 50,
        "estimatedDailyDownloads": 31910,
        "estimatedMonthlyDownloads": 957300,
        "app": { "..." : "..." }
      },
      {
        "rank": 100,
        "estimatedDailyDownloads": 18974,
        "estimatedMonthlyDownloads": 569220,
        "app": null
      }
    ],
    "disclaimer": "Download estimates use power-law models calibrated per category. Actual downloads may vary significantly based on seasonality, marketing spend, and viral effects."
  }
}
```

## Tier Ranks

The endpoint returns download estimates for these chart positions:

| Rank | Description                 |
| ---- | --------------------------- |
| #1   | Top of the chart            |
| #5   | Top 5                       |
| #10  | Top 10                      |
| #25  | Top 25                      |
| #50  | Top 50                      |
| #100 | Bottom of the visible chart |

## Fields

### Tier Object

| Field                     | Type   | Description                                  |
| ------------------------- | ------ | -------------------------------------------- |
| rank                      | number | Chart position                               |
| estimatedDailyDownloads   | number | Estimated daily downloads to reach this rank |
| estimatedMonthlyDownloads | number | Estimated monthly downloads (daily × 30)     |
| app                       | object | The app currently at this rank, or `null`    |

### App Object

| Field     | Type           | Description        |
| --------- | -------------- | ------------------ |
| appId     | string         | App Store ID       |
| name      | string         | App name           |
| developer | string         | Developer name     |
| icon      | string         | Icon URL           |
| rating    | number \| null | Average rating     |
| reviews   | number \| null | Total review count |

## Methodology

Download estimates use a **power-law model** calibrated per category:

```
Downloads(rank) = base / rank^exponent
```

* Parameters are tuned per genre (Games, Social Networking, Finance, etc.)
* Paid apps receive \~30× fewer downloads than free apps at the same rank
* When actual chart data is available, estimates are blended with review-based signals for improved accuracy

## Examples

### Top Free — All Categories (US)

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -H "X-API-Key: YOUR_KEY" \
  "https://api.appeeky.com/v1/categories/all/downloads-to-top?country=us&chart=top-free"
```

### Top Free — Games (US)

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -H "X-API-Key: YOUR_KEY" \
  "https://api.appeeky.com/v1/categories/6014/downloads-to-top?country=us&chart=top-free"
```

### Top Paid — All Categories (GB)

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -H "X-API-Key: YOUR_KEY" \
  "https://api.appeeky.com/v1/categories/all/downloads-to-top?country=gb&chart=top-paid"
```

## Credit Cost

**2 credits** per request.