Returns all apps that rank for a specific keyword, ordered by rank. This endpoint never returns empty results if iTunes has data — it checks the database first for pre-scraped rankings, 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 (e.g. us, gb, de, jp) |
| device | string | No | iphone | iphone or ipad |
| date | string | No | today | Scrape date in YYYY-MM-DD format |
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"
}
]
}
}
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 results in the iTunes Search index for this keyword |
| 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:
- Database lookup (fast) — Checks for pre-scraped ranking data matching the keyword, country, device, and date. If found, returns results instantly from the database.
- 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 to the database for historical tracking. The keyword is also auto-registered in the background scraping pipeline, so future requests for the same keyword will return pre-scraped data with faster response times.
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 |
