Returns all apps that rank for a specific keyword, ordered by rank. This endpoint never returns empty results if iTunes has data — it checks for stored rankings first, and automatically falls back to a live iTunes Search when no stored data exists.
Query Parameters
| Name | Type | Required | Default | Description |
|---|
| keyword | string | Yes | — | Search keyword (min 2 characters) |
| country | string | No | us | ISO country code — used when countries is omitted (legacy single-store) |
| countries | string | No | — | Comma-separated ISO codes (e.g. us,gb,de) for multi-country results in one request (max 25). When set, country is ignored. |
| device | string | No | iphone | iphone or ipad |
| date | string | No | today | Date in YYYY-MM-DD format |
countries, the response shape is unchanged (single country + ranks). With countries, the response includes countries and a results object keyed by ISO code — each value matches the single-country payload for that storefront.
Code Examples
curl "https://api.appeeky.com/v1/keywords/ranks?keyword=puzzle+game&country=us&device=iphone" \
-H "X-API-Key: YOUR_API_KEY"
Response
{
"data": {
"keyword": "puzzle game",
"country": "us",
"volumeScore": 72,
"difficulty": 85,
"resultCount": 3450,
"ranks": [
{
"appId": "1617391485",
"rank": 1,
"title": "Block Blast!",
"developer": "Hungry Studio",
"iconUrl": "https://is1-ssl.mzstatic.com/.../512x512bb.jpg"
},
{
"appId": "544007664",
"rank": 2,
"title": "Candy Crush Saga",
"developer": "King",
"iconUrl": "https://is1-ssl.mzstatic.com/.../512x512bb.jpg"
},
{
"appId": "1040639975",
"rank": 3,
"title": "Hexa Sort",
"developer": "IEC Global",
"iconUrl": "https://is1-ssl.mzstatic.com/.../512x512bb.jpg"
}
]
}
}
?countries=us,gb):
{
"data": {
"keyword": "puzzle game",
"countries": ["us", "gb"],
"results": {
"us": {
"keyword": "puzzle game",
"country": "us",
"volumeScore": 72,
"difficulty": 85,
"resultCount": 3450,
"ranks": []
},
"gb": {
"keyword": "puzzle game",
"country": "gb",
"volumeScore": 70,
"difficulty": 80,
"resultCount": 3200,
"ranks": []
}
}
}
}
Response Fields
| Field | Type | Description |
|---|
| keyword | string | The queried keyword |
| country | string | ISO country code (single-country response only) |
| countries | array | List of ISO codes (multi-country response only) |
| results | object | Per-country payloads keyed by ISO code (multi-country only) |
| volumeScore | number | Estimated search volume score (0–100) |
| difficulty | number | Ranking difficulty score (0–100) |
| resultCount | number | Total results in the iTunes Search index for this keyword |
| lastScrapedAt | string | null | ISO timestamp of the last historical observation for this keyword + storefront. null if there is no historical data yet. |
| source | string | "scrape" when ranks come from historical data, "live" when freshly fetched from iTunes Search. |
| ranks | array | Ordered list of ranking apps (see Rank Object below) |
Rank Object
| Field | Type | Description |
|---|
| appId | string | Apple App ID |
| rank | number | Organic rank for this keyword (1 = top) |
| title | string | App name |
| developer | string | Developer / seller name |
| iconUrl | string | App icon URL (512×512) |
How It Works
This endpoint uses a two-tier data strategy to ensure you always get results:
- Stored data (fast) — Checks for ranking data matching the keyword, country, device, and date. If found, returns results instantly.
- Live iTunes Search fallback (real-time) — If no stored data exists, the API performs a live search against Apple’s iTunes Search API and returns real-time results. This guarantees you get data for any keyword that has results in the App Store.
Results from live iTunes Search are automatically saved for historical tracking, so subsequent requests for the same keyword return faster.
Real-time keyword research: Use this endpoint to explore any keyword on-demand without needing to set up tracking first. Simply query any keyword and get instant results — the API handles everything behind the scenes including data persistence and future monitoring.
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 | Server error during live search |
