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

# Expand Keyword

> Embedding-based semantic neighbourhood for one keyword.

```
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

| Name    | Type   | Required | Default | Description                                                                                                                                                                               |
| ------- | ------ | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| keyword | string | Yes      | —       | The seed keyword to expand                                                                                                                                                                |
| country | string | No       | `us`    | ISO 3166-1 alpha-2 storefront                                                                                                                                                             |
| limit   | number | No       | `25`    | Max related keywords returned, 1–100                                                                                                                                                      |
| appId   | string | No       | —       | 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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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

| Field          | Type           | Notes                                                                                                        |
| -------------- | -------------- | ------------------------------------------------------------------------------------------------------------ |
| keyword        | string         | The semantically-adjacent keyword.                                                                           |
| similarity     | number         | Semantic similarity score to the seed (0.55–1.0; 1 = identical meaning).                                     |
| volumeScore    | number \| null | Persisted volume score; `null` if not yet enriched.                                                          |
| rankVolatility | number \| null | Persisted volatility; `null` if not yet enriched.                                                            |
| difficulty     | number \| null | Persisted difficulty score (0–100); `null` if not yet enriched.                                              |
| tracked        | boolean        | `true` when the keyword is in the actively tracked set for this country.                                     |
| yourRank       | number \| null | Owner 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](/docs/keyword-metrics#meta-envelope-response-level) 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.