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

# Categories

> List App Store categories and get top apps per category

```
GET /v1/categories
```

Returns all App Store categories with their genre IDs. Use these IDs with the Top Apps endpoint below. Pass `platform=google` to list **Google Play** categories instead (e.g. `GAME`, `MUSIC_AND_AUDIO`).

| Name     | Type   | Default | Description                                                                      |
| -------- | ------ | ------- | -------------------------------------------------------------------------------- |
| platform | string | `apple` | `apple` (default) or `google` for Google Play — see [Platforms](/docs/platforms) |

### Code Examples

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X GET "https://api.appeeky.com/v1/categories" \
    -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/categories", {
    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/categories",
      headers={"X-API-Key": "YOUR_API_KEY"},
  )

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

### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "categories": [
      { "id": "6000", "name": "Business" },
      { "id": "6001", "name": "Weather" },
      { "id": "6002", "name": "Utilities" },
      { "id": "6003", "name": "Travel" },
      { "id": "6004", "name": "Sports" },
      { "id": "6005", "name": "Social Networking" },
      { "id": "6006", "name": "Reference" },
      { "id": "6007", "name": "Productivity" },
      { "id": "6008", "name": "Photo & Video" },
      { "id": "6009", "name": "News" },
      { "id": "6010", "name": "Navigation" },
      { "id": "6011", "name": "Music" },
      { "id": "6012", "name": "Lifestyle" },
      { "id": "6013", "name": "Health & Fitness" },
      { "id": "6014", "name": "Games" },
      { "id": "6015", "name": "Finance" },
      { "id": "6016", "name": "Entertainment" },
      { "id": "6017", "name": "Education" },
      { "id": "6018", "name": "Books" },
      { "id": "6020", "name": "Medical" },
      { "id": "6023", "name": "Food & Drink" },
      { "id": "6024", "name": "Shopping" },
      { "id": "6025", "name": "Stickers" },
      { "id": "6026", "name": "Developer Tools" },
      { "id": "6027", "name": "Graphics & Design" }
    ]
  }
}
```

### Category Object

| Field | Type   | Description                            |
| ----- | ------ | -------------------------------------- |
| id    | string | Apple genre ID (e.g. `6014` for Games) |
| name  | string | Category display name (e.g. `"Games"`) |

***

## Top Apps in Category

```
GET /v1/categories/:genreId/top
```

Returns top-ranked apps in a specific category, sorted by chart position. Use `all` as the genreId to get the overall chart without filtering by category.

### Path Parameters

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

### Query Parameters

| Name     | Type   | Default    | Description                                                                      |
| -------- | ------ | ---------- | -------------------------------------------------------------------------------- |
| platform | string | `apple`    | `apple` (default) or `google` for Google Play — see [Platforms](/docs/platforms) |
| country  | string | `us`       | ISO country code (e.g. `us`, `gb`, `de`)                                         |
| chart    | string | `top-free` | Chart type: `top-free`, `top-paid`, or `top-grossing`                            |
| lang     | string | `en`       | Google Play language code (used when `platform=google`)                          |
| limit    | number | `25`       | Max results (capped at 100)                                                      |

### Code Examples

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X GET "https://api.appeeky.com/v1/categories/6014/top?country=us&chart=top-free&limit=25" \
    -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/categories/6014/top?country=us&chart=top-free&limit=25",
    {
      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/categories/6014/top",
      params={"country": "us", "chart": "top-free", "limit": 25},
      headers={"X-API-Key": "YOUR_API_KEY"},
  )

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

### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "category": { "id": "6014", "name": "Games" },
    "chartType": "top-free",
    "country": "us",
    "apps": [
      {
        "appId": "1617391485",
        "rank": 1,
        "title": "Block Blast!",
        "developer": "Hungry Studio",
        "icon": "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/.../512x512bb.jpg",
        "rating": 4.73,
        "reviewsCount": 1832497,
        "price": 0,
        "url": "https://apps.apple.com/us/app/block-blast/id1617391485"
      },
      {
        "appId": "544007664",
        "rank": 2,
        "title": "Candy Crush Saga",
        "developer": "King",
        "icon": "https://is1-ssl.mzstatic.com/image/thumb/Purple221/v4/.../512x512bb.jpg",
        "rating": 4.69,
        "reviewsCount": 3254891,
        "price": 0,
        "url": "https://apps.apple.com/us/app/candy-crush-saga/id544007664"
      },
      {
        "appId": "1040639975",
        "rank": 3,
        "title": "Hexa Sort",
        "developer": "IEC Global Pty Ltd",
        "icon": "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/.../512x512bb.jpg",
        "rating": 4.51,
        "reviewsCount": 89450,
        "price": 0,
        "url": "https://apps.apple.com/us/app/hexa-sort/id1040639975"
      }
    ],
    "total": 25
  }
}
```

### App Object

| Field        | Type           | Description                     |
| ------------ | -------------- | ------------------------------- |
| appId        | string         | Apple App ID                    |
| rank         | number         | Position in the chart (1-based) |
| title        | string         | App name                        |
| developer    | string         | Developer name                  |
| icon         | string         | App icon URL (512px)            |
| rating       | number \| null | Average star rating (0–5)       |
| reviewsCount | number \| null | Total ratings count             |
| price        | number \| null | Price in USD (0 = free)         |
| url          | string         | App Store URL                   |

### Chart Types

| Chart          | Description                        |
| -------------- | ---------------------------------- |
| `top-free`     | Most downloaded free apps          |
| `top-paid`     | Most downloaded paid apps          |
| `top-grossing` | Highest revenue apps (free + paid) |

<Tip>
  **Use `genreId=all`** to get the overall App Store chart without filtering by category. This returns the raw Apple RSS chart (top-free, top-paid, or top-grossing) enriched with full metadata from iTunes Lookup. Great for seeing what's trending across the entire store.
</Tip>

<Tip>
  **Per-category filtering**: When using a specific genre ID, the API fetches the overall Apple chart (top 100), filters by genre, and enriches each app with full metadata via iTunes Lookup. If the chart doesn't have enough results for the category, it supplements with iTunes Search results sorted by popularity.
</Tip>

### Errors

| Status | Code                 | When                                                                        |
| ------ | -------------------- | --------------------------------------------------------------------------- |
| 400    | INVALID\_GENRE\_ID   | genreId not provided or not in the valid list (use `all` for overall chart) |
| 400    | INVALID\_CHART\_TYPE | Chart not one of `top-free`, `top-paid`, `top-grossing`                     |
| 401    | MISSING\_API\_KEY    | No API key in the request                                                   |
| 401    | INVALID\_API\_KEY    | Invalid or expired API key                                                  |