GET /v1/apps/:id/keywords
Path Parameters
| Name | Type | Description |
|---|
| id | string | Apple App ID (numeric, e.g. 1617391485) |
Query Parameters
| Name | Type | Default | Description |
|---|
| country | string | us | ISO country code (e.g. us, gb, de) |
| device | string | iphone | iphone or ipad |
| discover | string | — | Deprecated. Auto-discovery is now the default behavior. Passing 1 has no additional effect. |
Code Examples
curl "https://api.appeeky.com/v1/apps/1617391485/keywords?country=us" \
-H "X-API-Key: YOUR_API_KEY"
Response
{
"data": {
"appId": "1617391485",
"keywords": [
{
"keyword": "puzzle game",
"rank": 5,
"appsCount": 215,
"popularity": 86,
"competitiveness": 97,
"volumeScore": 72,
"difficulty": 85,
"opportunity": 34,
"rankChange7d": 3,
"trend": "improving"
},
{
"keyword": "block puzzle",
"rank": 2,
"appsCount": 180,
"popularity": 72,
"competitiveness": 82,
"volumeScore": 65,
"difficulty": 68,
"opportunity": 58,
"rankChange7d": -1,
"trend": "declining"
},
{
"keyword": "brain teaser",
"rank": 18,
"appsCount": 120,
"popularity": 48,
"competitiveness": 55,
"volumeScore": 44,
"difficulty": 42,
"opportunity": 71,
"rankChange7d": 0,
"trend": "stable"
}
]
}
}
Keyword Object
| Field | Type | Description |
|---|
| keyword | string | The search keyword |
| rank | number | App’s organic rank for this keyword (1 = top result) |
| appsCount | number | Total number of apps ranking for this keyword |
| popularity | number | Deprecated. Legacy popularity score (0–100). Use volumeScore instead. |
| competitiveness | number | Deprecated. Legacy competition score (0–100). Use difficulty instead. |
| volumeScore | number | Estimated search volume score (0–100). Higher = more searches. |
| difficulty | number | Ranking difficulty score (0–100). Higher = harder to rank. |
| opportunity | number | Composite opportunity score (0–100). Balances volume, difficulty, and current rank — higher is better. |
| rankChange7d | number | Rank change over the last 7 days. Positive = improved (rank number decreased). |
| trend | string | Trend direction: "improving", "declining", or "stable" |
Metric Details
volumeScore (0–100)
Estimated relative search volume for the keyword. Derived from iTunes result counts, top app review volumes, and autocomplete position. A score of 80+ indicates a high-traffic keyword.
difficulty (0–100)
How hard it is to rank in the top results for this keyword. Factors in average rating of top apps, review count distribution, developer diversity, and market dominance. A score of 70+ means the keyword is dominated by strong incumbents.
opportunity (0–100)
A composite score that combines volume, difficulty, and your current rank into a single prioritization metric. High opportunity means the keyword has good search volume, manageable difficulty, and room for your app to climb.
trend
| Value | Meaning |
|---|
improving | Rank has been getting better (lower number) over 7 days |
declining | Rank has been getting worse (higher number) over 7 days |
stable | Rank has not changed significantly |
Auto-Discovery
When no keyword data exists for an app, the API automatically runs keyword discovery:
- Extracts keywords from the app’s title, subtitle, and description
- Adds category-relevant keywords based on the app’s primary category
- Expands with Apple Search Suggestions to find related long-tail keywords
- Scrapes iTunes Search for up to 30 keywords to determine rankings
- Returns enriched results immediately with all scoring metrics
Auto-discovery runs transparently on the first request for any app. Subsequent requests return stored data instantly. There is no need to pass discover=1 — this parameter is deprecated and kept only for backward compatibility.
Prioritize with opportunity score: Sort keywords by opportunity descending to find the best keywords to optimize for. High opportunity keywords have strong search volume, achievable difficulty, and room for rank improvement — these are your quick wins for ASO.
Errors
| Status | Code | When |
|---|
| 400 | INVALID_APP_ID | Non-numeric or missing app ID |
| 401 | UNAUTHORIZED | Missing or invalid API key |
| 404 | APP_NOT_FOUND | App does not exist in iTunes |
| 429 | RATE_LIMITED | Too many requests — slow down |
| 500 | INTERNAL_ERROR | Server error during discovery |
