> ## 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](https://docs.appeeky.com/docs/platforms.md) |
| 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

> [!NOTE]
>
> 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.

> [!TIP]
>
> **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 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.