Skip to main content
GET /v1/keywords/expand
Returns the closest known keywords to the seed by semantic similarity. Unlike Apple’s autocomplete, semantic expansion catches keywords that share meaning but not letters — "to-do" finds "task list", "focus timer" finds "pomodoro". Each result also carries the keyword’s volumeScore and rankVolatility so you can rank by “high volume + similar to seed” without a second roundtrip.

​
Query Parameters

NameTypeRequiredDefaultDescription
keywordstringYes—The seed keyword to expand
countrystringNousISO 3166-1 alpha-2 storefront
limitnumberNo25Max related keywords returned, 1–100
appIdstringNo—Numeric Apple App ID. When supplied, each neighbour is also annotated with tracked and yourRank so you can immediately see which expansions are actionable opportunities for the app.

​
Response

{
  "data": {
    "seed": "ai chat",
    "country": "us",
    "appId": "284882215",
    "total": 8,
    "cachedSeed": true,
    "related": [
      {
        "keyword": "ai assistant",
        "similarity": 0.871,
        "volumeScore": 64,
        "rankVolatility": 21.3,
        "difficulty": 58,
        "tracked": true,
        "yourRank": 14
      },
      {
        "keyword": "chatbot",
        "similarity": 0.842,
        "volumeScore": 58,
        "rankVolatility": 14.8,
        "difficulty": 51,
        "tracked": true,
        "yourRank": null
      },
      {
        "keyword": "ai conversation",
        "similarity": 0.811,
        "volumeScore": 41,
        "rankVolatility": 9.0,
        "difficulty": 33,
        "tracked": false,
        "yourRank": null
      }
    ]
  },
  "meta": {
    "lastScrapedAt": "2026-04-21T07:30:00Z",
    "dataAgeHours": 0,
    "source": "stored",
    "freshness": "fresh"
  }
}
cachedSeed is true when an embedding for the seed was already on file (the request stays fast). false means the seed was embedded fresh for this call — subsequent calls within ~30 days will be cached. appId echoes the optional caller param so MCP/agent clients can correlate batched calls. null when not supplied.

​
Per-neighbour fields

FieldTypeNotes
keywordstringThe semantically-adjacent keyword.
similaritynumberSemantic similarity score to the seed (0.55–1.0; 1 = identical meaning).
volumeScorenumber | nullPersisted volume score; null if not yet enriched.
rankVolatilitynumber | nullPersisted volatility; null if not yet enriched.
difficultynumber | nullPersisted difficulty score (0–100); null if not yet enriched.
trackedbooleantrue when the keyword is in the actively tracked set for this country.
yourRanknumber | nullOwner app’s latest rank (only populated when appId is supplied). null = the app does not currently rank.
The difficulty + tracked + yourRank triple turns “interesting neighbour” into “actionable opportunity”: neighbours with tracked: false are completely undiscovered, neighbours with tracked: true and yourRank: null are pre-vetted easy wins. The response-level meta envelope describes data freshness — see Keyword Metrics → meta envelope for the schema. source will be hybrid when the seed had to be embedded fresh.

​
Credit Cost

4 credits per request.

​
Use Cases

  • “More like this” suggestions on a keyword detail page.
  • Brainstorm support: type a candidate, see semantically-adjacent search terms you would have missed.
  • Build a personalised tracking list by expanding a small set of seed keywords.