Get Keyword Ranks

GET /v1/keywords/ranks

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)
platform	string	No	`apple`	`apple` (default) or `google` for Google Play — see Platforms
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` (Apple only)
lang	string	No	`en`	Google Play language code (used when `platform=google`)
date	string	No	today	Date in `YYYY-MM-DD` format

Without 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"

const res = await fetch(
  "https://api.appeeky.com/v1/keywords/ranks?keyword=puzzle+game&country=us&device=iphone",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const { data } = await res.json();
console.log(`Found ${data.ranks.length} apps for "${data.keyword}"`);
console.log(`Volume Score: ${data.volumeScore}, Difficulty: ${data.difficulty}`);

import requests

res = requests.get(
    "https://api.appeeky.com/v1/keywords/ranks",
    params={"keyword": "puzzle game", "country": "us", "device": "iphone"},
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()["data"]
print(f"Found {len(data['ranks'])} apps for \"{data['keyword']}\"")
print(f"Volume Score: {data['volumeScore']}, Difficulty: {data['difficulty']}")

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"
      }
    ]
  }
}

Multi-country (?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

Getting Started

Apps

My Data - Appeeky Web

Keywords

ASO Tools

AI Visibility

Search & Discovery

Market Intelligence

RevenueCat

App Store Connect

Google Play Console

Apple Search Ads

Growth Channels

Reference

Query Parameters

Code Examples

Response

Response Fields

Rank Object

How It Works

Errors

​Query Parameters

​Code Examples

​Response

​Response Fields

​Rank Object

​How It Works

​Errors

Query Parameters

Code Examples

Response

Response Fields

Rank Object

How It Works

Errors