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

# Category Screenshots

> Get screenshots for top-ranked apps in an App Store category

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

Fetch screenshots for the top-ranked apps in a specific App Store category. Acts as a creative explorer for ASO — see what screenshot styles, layouts, and messaging the top apps in any category are using.

## Path Parameters

| Name    | Type   | Required | Description                                                                          |
| ------- | ------ | -------- | ------------------------------------------------------------------------------------ |
| genreId | string | Yes      | Genre ID, or `all`. 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`, `jp`)                                   |
| 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 | `10`       | Number of apps to include (1-25)                                                 |

## Code Examples

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

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

## Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "genreId": "6014",
    "chart": "top-free",
    "country": "us",
    "apps": [
      {
        "rank": 1,
        "appId": "1617391485",
        "title": "Block Blast!",
        "developer": "Hungry Studio",
        "icon": "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/.../512x512bb.jpg",
        "screenshots": {
          "iphone": [
            "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/.../screen1.jpg",
            "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/.../screen2.jpg",
            "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/.../screen3.jpg"
          ],
          "ipad": [
            "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/.../ipad1.jpg"
          ]
        },
        "screenshotCount": 4
      },
      {
        "rank": 2,
        "appId": "1594703498",
        "title": "Woodoku",
        "developer": "Tripledot Studios",
        "icon": "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/.../512x512bb.jpg",
        "screenshots": {
          "iphone": [
            "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/.../screen1.jpg",
            "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/.../screen2.jpg"
          ],
          "ipad": []
        },
        "screenshotCount": 2
      },
      {
        "rank": 3,
        "appId": "1614645498",
        "title": "Cube Block - Puzzle Games",
        "developer": "Easybrain",
        "icon": "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/.../512x512bb.jpg",
        "screenshots": {
          "iphone": [
            "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/.../screen1.jpg",
            "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/.../screen2.jpg",
            "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/.../screen3.jpg",
            "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/.../screen4.jpg"
          ],
          "ipad": [
            "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/.../ipad1.jpg",
            "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/.../ipad2.jpg"
          ]
        },
        "screenshotCount": 6
      }
    ]
  }
}
```

## Response Fields

| Field   | Type   | Description                           |
| ------- | ------ | ------------------------------------- |
| genreId | string | The genre ID that was queried         |
| chart   | string | Chart type used                       |
| country | string | Country code used                     |
| apps    | array  | Array of ranked apps with screenshots |

### App Entry

| Field           | Type   | Description                       |
| --------------- | ------ | --------------------------------- |
| rank            | number | Position in the chart (1-based)   |
| appId           | string | Apple App ID                      |
| title           | string | App name                          |
| developer       | string | Developer / publisher name        |
| icon            | string | App icon URL (512px)              |
| screenshots     | object | Screenshot URLs grouped by device |
| screenshotCount | number | Total screenshots (iPhone + iPad) |

### Screenshots Object

| Field  | Type      | Description            |
| ------ | --------- | ---------------------- |
| iphone | string\[] | iPhone screenshot URLs |
| ipad   | string\[] | iPad screenshot URLs   |

## Chart Types

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

## Genre IDs

Use `GET /v1/categories` to get the full list. Common genre IDs:

| Genre ID | Category         | Genre ID | Category          |
| -------- | ---------------- | -------- | ----------------- |
| `6014`   | Games            | `6015`   | Finance           |
| `6016`   | Entertainment    | `6017`   | Education         |
| `6018`   | Books            | `6000`   | Business          |
| `6013`   | Health & Fitness | `6005`   | Social Networking |
| `6007`   | Productivity     | `all`    | All categories    |

<Tip>
  Use `genreId=all` to get screenshots for the overall top apps across all categories — great for spotting cross-category screenshot trends.
</Tip>

<Note>
  This endpoint combines two data sources: Apple's RSS charts for ranking data and the iTunes Lookup API for screenshot URLs. If an app appears in the chart but its iTunes lookup fails, it will be included with empty screenshot arrays.
</Note>

## Errors

| Status | Code              | When                                                     |
| ------ | ----------------- | -------------------------------------------------------- |
| 400    | INVALID\_GENRE    | Genre ID is missing                                      |
| 400    | INVALID\_CHART    | 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                               |