> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appeeky.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Keyword Ranks

> Get all apps ranking for a given keyword with live iTunes Search fallback

```
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](/docs/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

<CodeGroup>
  ```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl "https://api.appeeky.com/v1/keywords/ranks?keyword=puzzle+game&country=us&device=iphone" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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}`);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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']}")
  ```
</CodeGroup>

***

## Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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`):

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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:

1. **Stored data (fast)** — Checks for ranking data matching the keyword, country, device, and date. If found, returns results instantly.
2. **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.

<Note>
  Results from live iTunes Search are automatically saved for historical tracking, so subsequent requests for the same keyword return faster.
</Note>

<Tip>
  **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.
</Tip>

***

## 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   |