GET /v1/keywords/compare (two-way compare is unchanged).
Query parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| appId | string | Yes | — | Your app’s Apple App ID |
| competitors | string | Yes | — | Comma-separated competitor app IDs (1–5), e.g. 544007664,284882215 |
| country | string | No | us | ISO country code (e.g. us, gb, de, jp) |
appId itself in the list are ignored. Competitors are sorted numerically in the response.
Code examples
Response shape
Top-level fields:| Field | Description |
|---|---|
| appId | Your app ID |
| competitorIds | Sorted competitor IDs |
| country | Storefront used |
| appIds | Cluster order: your app first, then competitors |
| summary | Counts and volume/difficulty averages per bucket |
| inAllApps | Sample rows (up to 80): keyword in every app in the cluster |
| partialOverlap | Sample rows: keyword in 2..n−1 apps (not universal) |
| primaryOnly | Sample rows: only your app ranks |
| competitorExclusive | Sample rows: exactly one competitor ranks; you do not |
| withoutPrimary | Sample rows: you have no rank; at least one competitor does (gap view) |
| perCompetitorExclusive | Same as competitor-exclusive terms, split by competitor app ID |
keyword, ranks (map of app ID → rank or null), appsWithKeyword, volumeScore, and difficulty.
Summary buckets
| Field | Meaning |
|---|---|
| totalUniqueKeywords | Distinct keywords across the union of all apps’ tracked lists |
| withoutPrimaryCount | Number of keywords where your app does not rank (subset view; see withoutPrimary) |
| inAllApps | count, avgVolumeScore, avgDifficulty for universal keywords |
| partialOverlap | Same for partial overlap (2..n−1 apps) |
| primaryOnly | Same for only-you singletons |
| competitorExclusive | Same for single-competitor terms (you absent) |
inAllApps, partialOverlap, primaryOnly, or competitorExclusive. The withoutPrimary list is a separate convenience slice (all keywords where you do not rank).
Credits
This endpoint costs 4 credits per successful call (see Rate limits).Errors
| Status | Code | When |
|---|---|---|
| 400 | INVALID_APP_ID | Missing or non-numeric appId |
| 400 | INVALID_COMPETITORS | Missing competitors, no valid IDs, only duplicates of appId, or more than five competitors |
| 401 | MISSING_API_KEY / INVALID_API_KEY | Auth |
| 429 | RATE_LIMIT_EXCEEDED | Insufficient monthly credits |