> ## 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.
# Get App Keywords
> Enriched organic keyword rankings for an app with auto-discovery
```
GET /v1/apps/:id/keywords
```
Returns enriched organic keyword rankings for the specified app. When no keyword data exists, the API **automatically discovers keywords** — no special flags needed. Each keyword includes volume, difficulty, opportunity scores, rank changes, and trend direction.
***
## Path Parameters
| Name | Type | Description |
| ---- | ------ | ---------------------------------------------------------------------------------------- |
| id | string | App ID — numeric for Apple (`1617391485`), package name for Google (`com.spotify.music`) |
## Query Parameters
| Name | Type | Default | Description |
| -------- | ------ | -------- | ------------------------------------------------------------------------------------------------- |
| platform | string | `apple` | `apple` (default) or `google` for Google Play — see [Platforms](/docs/platforms) |
| country | string | `us` | ISO country code (e.g. `us`, `gb`, `de`) |
| device | string | `iphone` | `iphone` or `ipad` (Apple only) |
| lang | string | `en` | Google Play language code (used when `platform=google`) |
| discover | string | — | **Deprecated.** Auto-discovery is now the default behavior. Passing `1` has no additional effect. |
***
## Code Examples
```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.appeeky.com/v1/apps/1617391485/keywords?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/apps/1617391485/keywords?country=us",
{ headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const { data } = await res.json();
data.keywords.forEach((kw) => {
console.log(`${kw.keyword}: rank #${kw.rank}, opportunity ${kw.opportunity}`);
});
```
```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import requests
res = requests.get(
"https://api.appeeky.com/v1/apps/1617391485/keywords",
params={"country": "us"},
headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()["data"]
for kw in data["keywords"]:
print(f"{kw['keyword']}: rank #{kw['rank']}, opportunity {kw['opportunity']}")
```
***
## Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"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:
1. **Extracts keywords** from the app's title, subtitle, and description
2. **Adds category-relevant keywords** based on the app's primary category
3. **Expands with Apple Search Suggestions** to find related long-tail keywords
4. **Queries iTunes Search** for up to **30 keywords** to determine rankings
5. **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 |