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

# Keyword Movers (per app)

> Per-keyword rank changes for one app — top gainers, top losers, new entries, dropped out.

```
GET /v1/keywords/movers
```

Compares the latest snapshot of one app's keyword ranks vs the closest snapshot on or before `today − days`, then buckets every keyword into:

* **Top gainers** — rank improved (lower rank number)
* **Top losers** — rank dropped
* **New entries** — newly ranking keywords
* **Dropped out** — keywords the app no longer ranks for

Both `topGainers` and `topLosers` are sorted by `|rankChange| × volumeScore` so high-traffic moves bubble to the top.

***

## Query Parameters

| Name    | Type   | Required | Default  | Description                     |
| ------- | ------ | -------- | -------- | ------------------------------- |
| appId   | string | Yes      | —        | Numeric Apple app ID            |
| country | string | No       | `us`     | ISO 3166-1 alpha-2 storefront   |
| device  | string | No       | `iphone` | `iphone` or `ipad`              |
| days    | number | No       | `7`      | Comparison window in days, 1–90 |
| limit   | number | No       | `20`     | Max entries per bucket, 1–50    |

***

## Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "ok": true,
  "data": {
    "appId": "123456789",
    "country": "us",
    "device": "iphone",
    "days": 7,
    "period": { "current": "2026-04-21", "previous": "2026-04-14" },
    "summary": {
      "totalKeywords": 87,
      "gainers": 22,
      "losers": 14,
      "newEntries": 9,
      "droppedOut": 4
    },
    "topGainers": [
      {
        "keyword": "ai writer",
        "currentRank": 8,
        "previousRank": 41,
        "rankChange": 33,
        "volumeScore": 71,
        "difficulty": 58
      }
    ],
    "topLosers": [
      {
        "keyword": "notes",
        "currentRank": 64,
        "previousRank": 22,
        "rankChange": -42,
        "volumeScore": 88,
        "difficulty": 71
      }
    ],
    "newEntries": [
      {
        "keyword": "claude pro",
        "currentRank": 3,
        "previousRank": null,
        "rankChange": null,
        "volumeScore": 62,
        "difficulty": 35
      }
    ],
    "droppedOut": [
      {
        "keyword": "diary",
        "currentRank": null,
        "previousRank": 87,
        "rankChange": null,
        "volumeScore": 41,
        "difficulty": 28
      }
    ]
  }
}
```

## Rank Change Interpretation

| Field                    | Meaning                               |
| ------------------------ | ------------------------------------- |
| `rankChange > 0`         | Improved (e.g. went from rank 41 → 8) |
| `rankChange < 0`         | Dropped                               |
| `previousRank` is `null` | New keyword (newly ranking)           |
| `currentRank` is `null`  | No longer ranking                     |

## Credit Cost

3 credits per request.

## Use Cases

* "Monday morning ASO" digest.
* Smart Alerts trigger source ("a tracked keyword fell out of top 10").
* Correlating metadata changes with ranking impact (pair with the upcoming ASO Timeline endpoint).