GET /v1/keywords/suggestions
Query Parameters
| Name | Type | Required | Default | Description |
|---|
| term | string | Yes | — | Search prefix to get suggestions for (min 2 characters) |
| country | string | No | us | ISO country code (e.g. us, gb, de, jp) |
| 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"
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"
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"
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.
Caching
Suggestions are cached for 60 minutes. Repeated requests with the same parameters within the cache window will return instantly without hitting Apple’s servers.
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 |
