> ## 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 Keyword Gap

> Top-N keywords competitors rank for that the primary app doesn't (or ranks > 50).

```
GET /v1/keywords/gap
```

Surfaces the keyword opportunities you're leaving on the table. For up to five competitors, returns the top keywords where:

1. At least one competitor ranks, AND
2. Your app either doesn't rank or ranks worse than 50.

Each opportunity carries an `opportunityScore`:

```
opportunityScore =
    volumeScore                                  // bigger traffic = bigger upside
  × (1 − difficulty/100)                          // prefer attainable
  × (1 − bestCompetitorRank/100)                  // competitor in top 10 = real signal
  × (yourRank IS NULL ? 1.0
        : yourRank/100)                          // bigger gap to close = bigger upside
```

Results are sorted by `opportunityScore` descending.

***

## Query Parameters

| Name          | Type   | Required | Default  | Description                                 |
| ------------- | ------ | -------- | -------- | ------------------------------------------- |
| appId         | string | Yes      | —        | Numeric Apple app ID for your app           |
| competitorIds | string | Yes      | —        | 1–5 numeric competitor IDs, comma separated |
| country       | string | No       | `us`     | ISO 3166-1 alpha-2 storefront               |
| device        | string | No       | `iphone` | `iphone` or `ipad`                          |
| limit         | number | No       | `25`     | Max opportunities returned, 1–100           |

***

## Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "ok": true,
  "data": {
    "appId": "123456789",
    "competitorIds": ["456", "789"],
    "country": "us",
    "device": "iphone",
    "opportunities": [
      {
        "keyword": "school",
        "bestCompetitor": "456",
        "bestCompetitorRank": 18,
        "yourRank": null,
        "volumeScore": 82,
        "difficulty": 43,
        "opportunityScore": 38.33
      },
      {
        "keyword": "productivity",
        "bestCompetitor": "456",
        "bestCompetitorRank": 18,
        "yourRank": 71,
        "volumeScore": 68,
        "difficulty": 43,
        "opportunityScore": 22.59
      }
    ],
    "summary": {
      "totalGaps": 25,
      "avgVolumeScore": 54.7,
      "avgDifficulty": 41.2
    }
  }
}
```

`yourRank: null` means you don't rank for the keyword at all. Otherwise it's your current rank (always > 50 by definition of "gap").

## Credit Cost

4 credits per request.

## Relationship to other endpoints

* [`/v1/keywords/compare`](./keyword-compare.md) — full pairwise comparison (shared / unique / gap).
* [`/v1/keywords/compare-cluster`](./keyword-compare-cluster.md) — multi-app overlap buckets.
* This endpoint is the **action-oriented** view: ranked, capped, decision-ready.

## Use Cases

* Mobile **Insights** tab "Opportunities" section.
* One-tap → `POST /v1/keywords/track` to start tracking the suggested keyword.
* Daily / weekly digest emails: "5 keywords you should target this week."