rank

not read-only

Keyword rank

Where does an app rank in App Store search — right now, per storefront?

rank is an App Store keyword ranking API in one call: give it a search term and an app's numeric appId (the trackId in every App Store URL), and it returns the app's live position in that storefront's search results — the same top-200 result list a user scrolling the App Store would walk through.

Ranks are per storefront, because Apple's are: the US, UK and Japan stores run separate indexes and return different results for the same query. Pass up to 25 countries in one call and each is queried separately. A null rank is an answer too — the app is not in that storefront's top 200 for the term.

Apps rank for more than their literal title: Apple matches queries against the combined word pool of title, subtitle and hidden keyword field. So when a rank surprises you, the explanation is usually in the pool — that model is what the coverage tool computes.

worked example

Where does HabitKit (appId 6443918070) rank for “habit tracker” in the US, UK and Germany?

tools/call → rank

{
  "name": "rank",
  "arguments": {
    "keyword": "habit tracker",
    "appId": 6443918070,
    "countries": [
      "US",
      "GB",
      "DE"
    ]
  }
}

rank → structuredContent

{
  "keyword": "habit tracker",
  "appId": 6443918070,
  "storefronts": [
    { "country": "US", "appName": "Habit Tracker - HabitKit", "rank": 2, "totalResults": 189 },
    { "country": "GB", "appName": "Habit Tracker - HabitKit", "rank": 2, "totalResults": 189 },
    { "country": "DE", "appName": "Habit Tracker - HabitKit", "rank": 2, "totalResults": 185 }
  ]
}

real response, captured 2026-07-29 — trimmed only where marked with …

rank: 2 means the second result a user sees for that query in that store; totalResults is how many apps the search surfaced (capped at 200 by Apple's public API).
When the app is not in the top 200, rank is null and appName stays null — a real answer, not an error.
With save: true the call also appends a snapshot to a history file and reports the change since the last check — though for daily tracking, track_config does this managed, server-side.

when to use it

Verifying a metadata change: you shipped a new title or keyword field and want to know whether the phrases you targeted actually rank.
Spot-checking a keyword across markets before localizing — the same term can be position 2 in one storefront and absent in another.
Confirming phrases assembled cross-field really rank: coverage says a phrase is *possible*; rank says whether it *happens*.
Not for daily monitoring — that is what the managed tracker (track_config + history) is for, so you never re-poll manually.

description — as served to agents

App's position in App Store search results for a keyword (top 200), per storefront. Apps rank not only for literal metadata phrases: queries match the combined word pool of title + subtitle + hidden keyword field (see the coverage tool). With save=true, appends a snapshot to a JSONL history file and reports the change since the previous snapshot for the same keyword/app/storefront. Relative historyFile paths resolve against $OPENASO_HOME or the server's working directory.

input

keyword *

string

App Store search term

appId *

integer

App Store trackId of the app

countries

string[]

2-letter storefront codes, e.g. ["US", "GB", "JP"]. Each storefront is queried separately; at most 25 per call.(default ["US"])

save

boolean

Append a rank snapshot to history and report the change(default false)

historyFile

string

History JSONL path (default .openaso-history.jsonl); requires save=true

output

keyword *

string

appId *

integer

historyFile

string

resolved absolute path; only with save

storefronts *

object[]

country *

string

appName *

string | null

rank *

integer | null

1-based position, null = not in top 200

totalResults *

integer

integer | null

previous saved rank (null = was not ranked); only with save

change

string

human-readable movement; only with save

pairs with

volumea rank is only worth chasing if the keyword has demand›competitorssee who holds the positions above you›track_configturn a one-off check into a daily tracked series›

endpoint https://mcp.openaso.ai/mcp · auth Authorization: Bearer <key> · get a key