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

# Competitor Screenshots

> Compare screenshots between an app and its competitors side by side

```
GET /v1/apps/:id/screenshots/competitors
```

Compare App Store screenshots between an app and its automatically detected competitors. Returns screenshot URLs for the target app and up to 10 similar apps, making it easy to analyze creative strategies, screenshot styles, and visual trends in a category.

## 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) |
| country  | string | `us`    | ISO country code (e.g. `us`, `gb`, `de`, `jp`)                                   |
| limit    | number | `5`     | Number of competitor apps to include (1-10)                                      |
| 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/screenshots/competitors?country=us&limit=5" \
    -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/screenshots/competitors?country=us&limit=5",
    {
      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/screenshots/competitors",
      params={"country": "us", "limit": 5},
      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",
    "apps": [
      {
        "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
      },
      {
        "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
      },
      {
        "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"
          ],
          "ipad": [
            "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/.../ipad1.jpg",
            "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/.../ipad2.jpg"
          ]
        },
        "screenshotCount": 5
      }
    ]
  }
}
```

## Response Fields

| Field | Type   | Description                                                          |
| ----- | ------ | -------------------------------------------------------------------- |
| appId | string | The target app's Apple App ID                                        |
| apps  | array  | Array of app screenshot entries (target app first, then competitors) |

### App Screenshot Entry

| Field           | Type   | Description                       |
| --------------- | ------ | --------------------------------- |
| 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   |

<Tip>
  The **first entry** in the `apps` array is always the target app itself. This makes it easy to compare — just iterate the array and the first element is your baseline.
</Tip>

<Note>
  Competitors are automatically detected using a 3-layer matching algorithm: keyword overlap from the database, title search with genre filtering, and same-developer apps. The quality of competitor detection improves when the app has keyword ranking data in the system.
</Note>

## Errors

| Status | Code              | When                                                  |
| ------ | ----------------- | ----------------------------------------------------- |
| 400    | INVALID\_APP\_ID  | Non-numeric or missing app ID                         |
| 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 in the specified country |