App Store search suggestions
Return native App Store autocomplete suggestions for a keyword stem and country. Each item contains term and priority, the one-based source rank; no popularity score or search-volume estimate is invented. query accepts 1–200 characters. country defaults to us and is case-insensitive; use gb, not uk. Unsupported storefronts return a free 400 before a source call. A nonempty fresh response costs one credit; validated empty results, errors, cache hits and idempotent replays are free. Exact requests cache for five minutes. No pagination.
items entry contains { term, priority }: the suggested phrase and its one-based position in Apple’s response. This endpoint returns suggestions, not app search records. Rank is not a search-volume or popularity score.
query is required and accepts 1–200 characters without control characters; surrounding whitespace is removed. country defaults to us, is case-insensitive, and selects the requested Apple storefront. Use gb, not uk, for the United Kingdom. Unsupported countries return a free 400 UNSUPPORTED_COUNTRY before contacting Apple. Unsupported options such as cursor or limit return 422.
The country map matches the 175 codes in Apple’s App Store region picker, captured October 12, 2026. Apple’s public storefront directory supplied 174 numeric mappings; the mainland China mapping was checked separately with a live Chinese-language response. This dated mapping is not a guarantee that every country is available continuously. Apple’s hints response does not echo its country.
A fresh nonempty response costs 1 credit. A validated empty suggestion list, errors, cache hits and successful idempotent replays cost zero. Use X-Max-Credits: 1 to cap the charge. Exact requests cache for five minutes; Cache-Control: no-cache requests fresh suggestions.
total and returned_count count the returned suggestions, dropped is zero and next_cursor is null. Malformed or failed upstream responses remain errors; they are never reported as an empty successful list. Suggestions represent the current store response, not historical keyword demand.Authorizations
Headers
Optional nonnegative integer cap on the maximum request hold. A live request whose hold exceeds this cap returns 422 CREDIT_BUDGET_EXCEEDED before spending. Metered holds use the requested limit; cache hits and successful idempotent replays cost zero.
x >= 0Query Parameters
Partial search keyword to autocomplete, without control characters. Surrounding whitespace is removed.
1 - 200Case-insensitive App Store country code, default us. Use gb for the United Kingdom; uk and unsupported codes return free 400. Country mappings match the 175 codes in the Apple region picker captured October 12, 2026.
Response
Return native App Store autocomplete suggestions for a keyword stem and country. Each item contains term and priority, the one-based source rank; no popularity score or search-volume estimate is invented. query accepts 1–200 characters. country defaults to us and is case-insensitive; use gb, not uk. Unsupported storefronts return a free 400 before a source call. A nonempty fresh response costs one credit; validated empty results, errors, cache hits and idempotent replays are free. Exact requests cache for five minutes. No pagination.
x >= 0The selected operation determines the resource fields in this object. Source data can omit a metric or report it as null.