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

> Autocomplete suggestions from Apple's App Store search

```
GET /v1/keywords/suggestions
```

Returns autocomplete suggestions from the store's search for a given term. These are the same suggestions users see when they type into the App Store (or Google Play, with `platform=google`) search bar — making them a powerful source for discovering real search queries.

***

## Query Parameters

| Name     | Type   | Required | Default | Description                                                                           |
| -------- | ------ | -------- | ------- | ------------------------------------------------------------------------------------- |
| term     | string | Yes      | —       | Search prefix to get suggestions for (min 2 characters)                               |
| platform | string | No       | `apple` | `apple` (default) or `google` for Google Play — see [Platforms](/docs/platforms)      |
| country  | string | No       | `us`    | ISO country code (e.g. `us`, `gb`, `de`, `jp`)                                        |
| lang     | string | No       | `en`    | Google Play language code (used when `platform=google`)                               |
| expand   | number | No       | `0`     | Set to `1` to query prefix variants (`term a`, `term b`, ...) for long-tail discovery |
| metrics  | number | No       | `0`     | Set to `1` to enrich the top 10 suggestions with volume and difficulty scores         |

***

## Code Examples

### Basic Suggestions

<CodeGroup>
  ```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl "https://api.appeeky.com/v1/keywords/suggestions?term=puzzle&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/suggestions?term=puzzle&country=us",
    { headers: { "X-API-Key": "YOUR_API_KEY" } }
  );
  const { data } = await res.json();
  data.suggestions.forEach((s) => {
    console.log(`#${s.suggestRank}: ${s.term}`);
  });
  ```

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

  res = requests.get(
      "https://api.appeeky.com/v1/keywords/suggestions",
      params={"term": "puzzle", "country": "us"},
      headers={"X-API-Key": "YOUR_API_KEY"},
  )
  data = res.json()["data"]
  for s in data["suggestions"]:
      print(f"#{s['suggestRank']}: {s['term']}")
  ```
</CodeGroup>

### With Expand (Long-Tail Discovery)

<CodeGroup>
  ```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl "https://api.appeeky.com/v1/keywords/suggestions?term=puzzle&country=us&expand=1" \
    -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/suggestions?term=puzzle&country=us&expand=1",
    { headers: { "X-API-Key": "YOUR_API_KEY" } }
  );
  const { data } = await res.json();
  console.log(`${data.suggestions.length} long-tail suggestions found`);
  ```

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

  res = requests.get(
      "https://api.appeeky.com/v1/keywords/suggestions",
      params={"term": "puzzle", "country": "us", "expand": 1},
      headers={"X-API-Key": "YOUR_API_KEY"},
  )
  data = res.json()["data"]
  print(f"{len(data['suggestions'])} long-tail suggestions found")
  ```
</CodeGroup>

### With Metrics (Volume & Difficulty)

<CodeGroup>
  ```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl "https://api.appeeky.com/v1/keywords/suggestions?term=puzzle&country=us&metrics=1" \
    -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/suggestions?term=puzzle&country=us&metrics=1",
    { headers: { "X-API-Key": "YOUR_API_KEY" } }
  );
  const { data } = await res.json();
  data.suggestions.forEach((s) => {
    console.log(`${s.term}: volume ${s.volumeScore ?? "—"}, difficulty ${s.difficulty ?? "—"}`);
  });
  ```

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

  res = requests.get(
      "https://api.appeeky.com/v1/keywords/suggestions",
      params={"term": "puzzle", "country": "us", "metrics": 1},
      headers={"X-API-Key": "YOUR_API_KEY"},
  )
  data = res.json()["data"]
  for s in data["suggestions"]:
      vol = s.get("volumeScore", "—")
      diff = s.get("difficulty", "—")
      print(f"{s['term']}: volume {vol}, difficulty {diff}")
  ```
</CodeGroup>

***

## Response

### Basic (default)

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "term": "puzzle",
    "country": "us",
    "suggestions": [
      { "term": "puzzle game", "suggestRank": 1 },
      { "term": "puzzle games free", "suggestRank": 2 },
      { "term": "puzzle & dragons", "suggestRank": 3 },
      { "term": "puzzle bobble", "suggestRank": 4 },
      { "term": "puzzle page", "suggestRank": 5 }
    ]
  }
}
```

### With `metrics=1`

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "term": "puzzle",
    "country": "us",
    "suggestions": [
      {
        "term": "puzzle game",
        "suggestRank": 1,
        "volumeScore": 72,
        "difficulty": 85
      },
      {
        "term": "puzzle games free",
        "suggestRank": 2,
        "volumeScore": 58,
        "difficulty": 71
      },
      {
        "term": "puzzle & dragons",
        "suggestRank": 3,
        "volumeScore": 45,
        "difficulty": 32
      },
      {
        "term": "puzzle bobble",
        "suggestRank": 4
      },
      {
        "term": "puzzle page",
        "suggestRank": 5
      }
    ]
  }
}
```

<Note>
  When `metrics=1` is set, only the **top 10 suggestions** are enriched with `volumeScore` and `difficulty`. Suggestions beyond position 10 will not include these fields. This keeps response times reasonable since metric calculation requires additional API calls.
</Note>

***

## Response Fields

| Field       | Type   | Description                             |
| ----------- | ------ | --------------------------------------- |
| term        | string | The original search prefix              |
| country     | string | ISO country code used                   |
| suggestions | array  | List of autocomplete suggestion objects |

### Suggestion Object

| Field       | Type   | Always Present | Description                                                      |
| ----------- | ------ | -------------- | ---------------------------------------------------------------- |
| term        | string | Yes            | The suggested search keyword                                     |
| suggestRank | number | Yes            | Position in Apple's autocomplete results (1 = most popular)      |
| volumeScore | number | No             | Search volume score (0–100). Only present when `metrics=1`.      |
| difficulty  | number | No             | Ranking difficulty score (0–100). Only present when `metrics=1`. |

***

## How suggestRank Works

The `suggestRank` value represents the position of this suggestion in Apple's autocomplete dropdown. A rank of **1** means this is the most popular completion that Apple shows first when a user types the given prefix.

Lower `suggestRank` values generally correlate with higher search volume, making this a useful proxy for keyword popularity even without the `metrics` flag.

***

## Expand Mode

When `expand=1` is set, the API queries **prefix variants** by appending each letter of the alphabet to your term:

* `puzzle a` → puzzle adventure, puzzle action, ...
* `puzzle b` → puzzle bobble, puzzle blocks, ...
* `puzzle c` → puzzle craft, puzzle cats, ...
* ... and so on through `puzzle z`

This dramatically increases the number of suggestions returned and is ideal for **long-tail keyword discovery**. You may receive 50–200+ suggestions in a single request depending on the term.

***

<Tip>
  **Discover long-tail keywords**: Use suggestions to find keywords that real users are actively searching for in the App Store. Combine `expand=1` with `metrics=1` to get a comprehensive list of long-tail keywords ranked by search volume — these often have lower competition and are easier to rank for.
</Tip>

***

## Errors

| Status | Code            | When                                  |
| ------ | --------------- | ------------------------------------- |
| 400    | INVALID\_TERM   | Term shorter than 2 characters        |
| 401    | UNAUTHORIZED    | Missing or invalid API key            |
| 429    | RATE\_LIMITED   | Too many requests — slow down         |
| 500    | INTERNAL\_ERROR | Error fetching suggestions from Apple |