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

# Keyword Compare

> Competitor keyword overlap and gap analysis between two apps

```
GET /v1/keywords/compare
```

Compares keyword rankings between two apps to reveal shared keywords, unique strengths, competitor opportunities, and gap threats. Essential for competitive ASO (App Store Optimization) strategy.

***

## Query Parameters

| Name         | Type   | Required | Default | Description                                    |
| ------------ | ------ | -------- | ------- | ---------------------------------------------- |
| appId        | string | Yes      | —       | Your app's Apple App ID                        |
| competitorId | string | Yes      | —       | Competitor's Apple App ID                      |
| country      | string | No       | `us`    | ISO country code (e.g. `us`, `gb`, `de`, `jp`) |

***

## Code Examples

<CodeGroup>
  ```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl "https://api.appeeky.com/v1/keywords/compare?appId=1617391485&competitorId=544007664&country=us" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const res = await fetch(
    "https://api.appeeky.com/v1/keywords/compare?appId=1617391485&competitorId=544007664&country=us",
    { headers: { "X-API-Key": "YOUR_API_KEY" } }
  );
  const { data } = await res.json();
  console.log(`Shared keywords: ${data.summary.totalShared}`);
  console.log(`Your unique: ${data.summary.totalYourUnique}`);
  console.log(`Competitor unique: ${data.summary.totalCompetitorUnique}`);
  console.log(`Gaps to close: ${data.summary.totalGaps}`);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  res = requests.get(
      "https://api.appeeky.com/v1/keywords/compare",
      params={
          "appId": "1617391485",
          "competitorId": "544007664",
          "country": "us",
      },
      headers={"X-API-Key": "YOUR_API_KEY"},
  )
  data = res.json()["data"]
  summary = data["summary"]
  print(f"Shared keywords: {summary['totalShared']}")
  print(f"Your unique: {summary['totalYourUnique']}")
  print(f"Competitor unique: {summary['totalCompetitorUnique']}")
  print(f"Gaps to close: {summary['totalGaps']}")
  ```
</CodeGroup>

***

## Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "shared": [
      {
        "keyword": "puzzle game",
        "yourRank": 5,
        "competitorRank": 3,
        "rankDiff": -2,
        "volumeScore": 72,
        "difficulty": 85
      },
      {
        "keyword": "block puzzle",
        "yourRank": 2,
        "competitorRank": 8,
        "rankDiff": 6,
        "volumeScore": 65,
        "difficulty": 68
      }
    ],
    "yourUnique": [
      {
        "keyword": "blast game",
        "yourRank": 4,
        "competitorRank": null,
        "rankDiff": null,
        "volumeScore": 38,
        "difficulty": 45
      }
    ],
    "competitorUnique": [
      {
        "keyword": "candy crush",
        "yourRank": null,
        "competitorRank": 1,
        "rankDiff": null,
        "volumeScore": 88,
        "difficulty": 95
      },
      {
        "keyword": "match 3 game",
        "yourRank": null,
        "competitorRank": 6,
        "rankDiff": null,
        "volumeScore": 55,
        "difficulty": 62
      }
    ],
    "gapAnalysis": [
      {
        "keyword": "puzzle game",
        "yourRank": 5,
        "competitorRank": 3,
        "rankDiff": -2,
        "volumeScore": 72,
        "difficulty": 85
      }
    ],
    "summary": {
      "totalShared": 2,
      "totalYourUnique": 1,
      "totalCompetitorUnique": 2,
      "totalGaps": 1,
      "overlapPercent": 40
    }
  }
}
```

***

## Response Sections

### `shared` — Keywords Both Apps Rank For

Keywords where both your app and the competitor appear in search results. Use `rankDiff` to see who ranks higher.

### `yourUnique` — Your Strengths

Keywords that **only your app** ranks for. These are your competitive advantages — keywords where you have visibility and the competitor does not.

### `competitorUnique` — Opportunities to Target

Keywords that **only the competitor** ranks for. These represent **opportunities** — keywords you could target to gain visibility in spaces where the competitor already has traction.

### `gapAnalysis` — Threats

Keywords where the competitor **significantly outranks** you. These are **threats** — high-value keywords where you're losing ground and should consider optimizing.

***

## Keyword Entry Fields

| Field          | Type         | Description                                                                            |
| -------------- | ------------ | -------------------------------------------------------------------------------------- |
| keyword        | string       | The search keyword                                                                     |
| yourRank       | number\|null | Your app's rank (null if your app doesn't rank for this keyword)                       |
| competitorRank | number\|null | Competitor's rank (null if competitor doesn't rank for this keyword)                   |
| rankDiff       | number\|null | `yourRank - competitorRank`. Positive = you rank better. Null if one app doesn't rank. |
| volumeScore    | number       | Estimated search volume score (0–100)                                                  |
| difficulty     | number       | Ranking difficulty score (0–100)                                                       |

## Summary Fields

| Field                 | Type   | Description                                                    |
| --------------------- | ------ | -------------------------------------------------------------- |
| totalShared           | number | Number of keywords both apps rank for                          |
| totalYourUnique       | number | Number of keywords only your app ranks for                     |
| totalCompetitorUnique | number | Number of keywords only the competitor ranks for               |
| totalGaps             | number | Number of keywords where competitor significantly outranks you |
| overlapPercent        | number | Percentage of keywords shared between both apps (0–100)        |

***

<Warning>
  **Both apps must have keyword data.** Before using this endpoint, call `GET /v1/apps/:id/keywords` for both your app and the competitor to trigger keyword discovery. If either app has no keyword data, the comparison will be incomplete or empty.
</Warning>

<Tip>
  **Competitive ASO strategy**: Focus on `competitorUnique` keywords with high `volumeScore` and low `difficulty` — these are the easiest wins for expanding your keyword footprint. Then address `gapAnalysis` keywords where you're being outranked on important terms.
</Tip>

***

## Errors

| Status | Code             | When                              |
| ------ | ---------------- | --------------------------------- |
| 400    | INVALID\_APP\_ID | Non-numeric or missing app ID     |
| 400    | MISSING\_PARAMS  | Missing `appId` or `competitorId` |
| 401    | UNAUTHORIZED     | Missing or invalid API key        |
| 429    | RATE\_LIMITED    | Too many requests — slow down     |
| 500    | INTERNAL\_ERROR  | Server error during comparison    |