Skip to main content
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

NameTypeRequiredDefaultDescription
appIdstringYesNumeric Apple app ID
countrystringNousISO 3166-1 alpha-2 storefront
devicestringNoiphoneiphone or ipad
daysnumberNo7Comparison window in days, 1–90
limitnumberNo20Max entries per bucket, 1–50

Response

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

FieldMeaning
rankChange > 0Improved (e.g. went from rank 41 → 8)
rankChange < 0Dropped
previousRank is nullNew keyword (newly ranking)
currentRank is nullNo 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).