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 — when countries is omitted (single storefront) |
| countries | string | No | — | Comma-separated ISO codes (e.g. us,gb,de) for multiple storefronts in one request (max 25). When set, country is ignored. |
Code Examples
curl "https://api.appeeky.com/v1/keywords/metrics?keyword=puzzle+game&country=us" \
-H "X-API-Key: YOUR_API_KEY"
Response
Single storefront (default — same as before):
{
"data": {
"keyword": "puzzle game",
"country": "us",
"volumeScore": 72,
"difficulty": 85,
"resultCount": 3450,
"topAppsAvgRating": 4.6,
"topAppsAvgReviews": 284500,
"developerDiversity": 0.82,
"rankVolatility": 12.4,
"marketDominance": 0.31,
"historicalDays": 90,
"updatedAt": "2026-04-21T03:14:00Z"
}
}
?countries=us,gb):
{
"data": {
"keyword": "puzzle game",
"countries": ["us", "gb"],
"results": {
"us": {
"keyword": "puzzle game",
"country": "us",
"volumeScore": 72,
"difficulty": 85,
"resultCount": 3450,
"topAppsAvgRating": 4.6,
"topAppsAvgReviews": 284500,
"developerDiversity": 0.82
},
"gb": {
"keyword": "puzzle game",
"country": "gb",
"volumeScore": 68,
"difficulty": 80,
"resultCount": 3100,
"topAppsAvgRating": 4.5,
"topAppsAvgReviews": 200000,
"developerDiversity": 0.78
}
}
}
}
Response Fields
| Field | Type | Description |
|---|
| keyword | string | The queried keyword |
| country | string | ISO country code (single-storefront response only) |
| countries | array | List of ISO codes (multi-storefront response only) |
| results | object | Per-country metric objects keyed by ISO code (multi-storefront only) |
| 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. |
| rankVolatility | number | null | Average daily rank change observed across the top results — higher = more chaotic SERP, lower = stable incumbents. null if no historical data yet. |
| marketDominance | number | null | Share of total review weight held by the #1 app on this keyword (0.0–1.0). High dominance = one app owns the keyword. null if no historical data yet. |
| historicalDays | number | null | Number of days of historical observations the enriched signals are based on. null if not yet enriched. |
| updatedAt | string | null | ISO timestamp of the last enrichment refresh. null if not yet enriched. |
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 |
The scoring algorithms analyze the top search results from iTunes at query time. Scores may fluctuate slightly over time 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 |
