Keyword Suggestions

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

curl "https://api.appeeky.com/v1/keywords/suggestions?term=puzzle&country=us" \
  -H "X-API-Key: YOUR_API_KEY"

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}`);
});

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']}")

With Expand (Long-Tail Discovery)

curl "https://api.appeeky.com/v1/keywords/suggestions?term=puzzle&country=us&expand=1" \
  -H "X-API-Key: YOUR_API_KEY"

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

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

With Metrics (Volume & Difficulty)

curl "https://api.appeeky.com/v1/keywords/suggestions?term=puzzle&country=us&metrics=1" \
  -H "X-API-Key: YOUR_API_KEY"

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 ?? "—"}`);
});

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}")

Response

Basic (default)

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

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

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.

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.

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.

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

Getting Started

Apps

My Data - Appeeky Web

Keywords

ASO Tools

AI Visibility

Search & Discovery

Market Intelligence

RevenueCat

App Store Connect

Google Play Console

Apple Search Ads

Growth Channels

Reference

Query Parameters

Code Examples

Basic Suggestions

With Expand (Long-Tail Discovery)

With Metrics (Volume & Difficulty)

Response

Basic (default)

With `metrics=1`

Response Fields

Suggestion Object

How suggestRank Works

Expand Mode

Errors

​Query Parameters

​Code Examples

​Basic Suggestions

​With Expand (Long-Tail Discovery)

​With Metrics (Volume & Difficulty)

​Response

​Basic (default)

​With metrics=1

​Response Fields

​Suggestion Object

​How suggestRank Works

​Expand Mode

​Errors

Query Parameters

Code Examples

Basic Suggestions

With Expand (Long-Tail Discovery)

With Metrics (Volume & Difficulty)

Response

Basic (default)

With `metrics=1`

Response Fields

Suggestion Object

How suggestRank Works

Expand Mode

Errors