Returns detailed search volume and ranking difficulty scores for a keyword. The scoring algorithms analyze iTunes Search data, top app review volumes, autocomplete position, rating distributions, and developer diversity to produce actionable scores.
Query Parameters
| Name | Type | Required | Default | Description |
|---|
| keyword | string | Yes | — | Search keyword (min 2 characters) |
| country | string | No | us | ISO country code (e.g. us, gb, de, jp) |
Code Examples
curl "https://api.appeeky.com/v1/keywords/metrics?keyword=puzzle+game&country=us" \
-H "X-API-Key: YOUR_API_KEY"
Response
{
"data": {
"keyword": "puzzle game",
"country": "us",
"volumeScore": 72,
"difficulty": 85,
"resultCount": 3450,
"topAppsAvgRating": 4.6,
"topAppsAvgReviews": 284500,
"developerDiversity": 0.82
}
}
Response Fields
| Field | Type | Description |
|---|
| keyword | string | The queried keyword |
| country | string | ISO country code used |
| volumeScore | number | Estimated search volume score (0–100) |
| difficulty | number | Ranking difficulty score (0–100) |
| resultCount | number | Total apps in the iTunes Search index for this keyword |
| topAppsAvgRating | number | Average star rating of the top-ranking apps (1.0–5.0) |
| topAppsAvgReviews | number | Average review count of the top-ranking apps |
| developerDiversity | number | Ratio of unique developers in the top results (0.0–1.0). Higher = more diverse. |
Scoring Algorithms
Volume Score (0–100)
The volume score estimates relative search popularity using three weighted signals:
| Signal | Weight | Description |
|---|
| iTunes resultCount | 40% | Number of apps in search results, normalized to a max of 200 |
| Top app reviews | 40% | Average review count of top apps, normalized to a max of 500K |
| Autocomplete bonus | 20% | Bonus points if the keyword appears in Apple’s autocomplete suggestions |
Difficulty Score (0–100)
The difficulty score measures how hard it is to rank in the top results:
| Signal | Weight | Description |
|---|
| Average rating | 20% | Higher avg rating of top apps = harder to compete |
| Average review count | 35% | More reviews on top apps = stronger incumbents |
| Developer diversity | 25% | Low diversity = dominated by a few publishers = harder to break in |
| Dominance ratio | 20% | How much of the market the #1 app captures relative to others |
Score Ranges
| Range | Label | Volume Meaning | Difficulty Meaning |
|---|
| 0–20 | Very Low | Minimal search traffic | Very easy to rank — few strong competitors |
| 21–40 | Low | Some searches, niche keyword | Relatively easy — moderate competition |
| 41–60 | Medium | Moderate search volume | Competitive — established apps present |
| 61–80 | High | Popular keyword, significant traffic | Hard — strong incumbents dominate |
| 81–100 | Very High | Top-tier keyword, massive volume | Extremely hard — dominated by top publishers |
Caching
Metrics are cached for 30 minutes. Repeated requests with the same keyword and country within the cache window return instantly without recalculation.
The scoring algorithms analyze the top search results from iTunes at query time. Scores may fluctuate slightly between cache refreshes as the App Store rankings change.
Combine with opportunity score: Use this endpoint to evaluate individual keywords, then cross-reference with the opportunity score from GET /v1/apps/:id/keywords for a complete prioritization framework. High volume + low difficulty + high opportunity = your best ASO targets.
Errors
| Status | Code | When |
|---|
| 400 | INVALID_KEYWORD | Keyword shorter than 2 characters |
| 401 | UNAUTHORIZED | Missing or invalid API key |
| 429 | RATE_LIMITED | Too many requests — slow down |
| 500 | INTERNAL_ERROR | Error calculating metrics |
