Skip to main content
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

NameTypeRequiredDefaultDescription
appIdstringYes—Numeric Apple app ID for your app
competitorIdsstringYes—1–5 numeric competitor IDs, comma separated
countrystringNousISO 3166-1 alpha-2 storefront
devicestringNoiphoneiphone or ipad
limitnumberNo25Max opportunities returned, 1–100

​
Response

{
  "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

​
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.”