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

# Compare Apps

> Put your app next to up to 4 competitors — ratings, category rank, keyword visibility, top keywords and keyword overlap in one call.

**Compare Apps** returns a side-by-side snapshot of your app and up to four competitors: store profile, category rank, how many keywords each ranks for, a 30-day visibility trend, each app's strongest non-branded keywords, and how much their keyword sets overlap.

Works for the App Store and Google Play. Pair it with [Keyword Rank History](https://docs.appeeky.com/docs/keyword-rank-history.md) to chart the keywords you care about over time.

***

## API

| Method | Endpoint | Description | Credits |
| - | - | - | - |
| GET | `/v1/aso/compare/:appId` | Compare one app with 1–4 competitors | 5 |

| Name | Type | Required | Default | Description |
| - | - | - | - | - |
| `appId` | path | Yes | — | Your app: App Store numeric id or Google Play package name |
| `competitors` | string | Yes | — | Comma-separated competitor ids, 1–4, same platform as `appId` |
| `platform` | string | No | `apple` | `apple` or `google` |
| `country` | string | No | `us` | Storefront country code |
| `lang` | string | No | — | Google Play listing language, e.g. `en` |

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.appeeky.com/v1/aso/compare/123456789?competitors=987654321,555555555&country=us" \
  -H "X-API-Key: $APPEEKY_API_KEY"
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "platform": "apple",
    "country": "us",
    "device": "iphone",
    "appIds": ["123456789", "987654321", "555555555"],
    "apps": [
      {
        "appId": "123456789",
        "isPrimary": true,
        "found": true,
        "title": "Example Habits",
        "developer": "Example Inc.",
        "icon": "https://…",
        "rating": 4.7,
        "ratingCount": 12840,
        "category": "Health & Fitness",
        "version": "3.2.0",
        "lastUpdated": "2026-10-20T00:00:00Z",
        "categoryRank": { "rank": 42, "chartType": "free", "genreName": "Health & Fitness", "date": "2026-10-31" },
        "rankedKeywords": 214,
        "top10Keywords": 18,
        "visibilityScore": 31.4,
        "visibilityChange": 2.1,
        "visibilitySeries": [{ "date": "2026-10-31", "score": 31.4, "rankedCount": 214 }],
        "topKeywords": [{ "keyword": "habit tracker", "rank": 5, "volumeScore": 62 }]
      }
    ],
    "overlap": {
      "matrix": {
        "123456789": { "123456789": 214, "987654321": 96, "555555555": 40 }
      },
      "unique": { "123456789": 88, "987654321": 120, "555555555": 61 },
      "sharedByAll": 22,
      "totalKeywords": 512
    }
  }
}
```

### Fields

| Field | Meaning |
| - | - |
| `found` | `false` when the store listing couldn't be loaded; the other profile fields are then empty |
| `categoryRank` | App Store only. Best chart position on the latest day it charted in the last 7 days; `null` on Google Play or when not charting |
| `rankedKeywords` | Keywords the app currently ranks for |
| `top10Keywords` | Of those, how many rank in the top 10 |
| `visibilityScore`, `visibilityChange`, `visibilitySeries` | Keyword visibility over the last 30 days. See [Keyword Visibility](https://docs.appeeky.com/docs/keyword-visibility.md) |
| `topKeywords` | Up to 5 strongest non-branded keywords ranked in the top 30, weighted by volume and rank |
| `overlap.matrix[a][b]` | Keywords both `a` and `b` rank for. `matrix[a][a]` is `a`'s total |
| `overlap.unique` | Keywords only that app ranks for, within the compared set |
| `overlap.sharedByAll` | Keywords every compared app ranks for |

The first app in `apps` is always yours (`isPrimary: true`). Results are cached for about 15 minutes.

***

## Errors

| Status | Code | When |
| - | - | - |
| 400 | `INVALID_APP_ID` | `appId` doesn't match the platform's id format |
| 400 | `INVALID_COMPETITORS` | No valid competitor ids, or more than 4 |
| 400 | `INVALID_PLATFORM` | `platform` is not `apple` or `google` |

***

## Related

* [Competitor Keyword Gap](https://docs.appeeky.com/docs/keyword-gap.md): keywords competitors rank for and you don't
* [Compare Keywords](https://docs.appeeky.com/docs/keyword-compare.md): keyword overlap between two apps
* [ASO Competitor Report](https://docs.appeeky.com/docs/aso-competitor-report.md): a deeper written comparison of two apps


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.