Search Term Popularity Query

Retrieve the relative search volume ranking of search terms for a given App Store genre and country or region.

URL

POST https://api.ads.apple.com/v1/insights/apps/search-term-popularity/query

Header Parameters

Name	Type	Description
`X-Ap-Context` Required	string

Response Codes

Status	Reason	Type	Description
200	OK Content-Type: application/json	`SearchTermPopularityQueryResponse`	Successful response. Returns SearchTermPopularityQueryResponse (`result`: SearchTermPopularityResultContainer).
400	Bad Request Content-Type: application/json	`Error`	Bad Request. Returns Error.
401	Unauthorized Content-Type: application/json	`Error`	Unauthorized.
403	Forbidden Content-Type: application/json	`Error`	Forbidden.
404	Not Found Content-Type: application/json	`Error`	Not Found. Returns Error.
429	Too Many Requests Content-Type: application/json	`Error`	Rate Limit Exceeded. Returns Error.
500	Internal Server Error Content-Type: application/json	`Error`	Internal Server Error. Returns Error.

Discussion

This endpoint returns the most popular search terms for a given App Store genre and country, showing top search terms by search volume. To discover high-volume terms to target during campaign setup, use this data.

See Filter for the full set of supported comparison operators.

Filterable Fields

Field	Type	Operators	Description
`week`	string	`IN`	Available only when `granularity` is `WEEKLY_SUN_SAT`. Values must be valid week boundary dates.
`month`	string	`IN`	Available only when `granularity` is `MONTHLY`.
`countryOrRegion`	string	`EQUALS`, `IN`	App Store country or region code to scope results to. Use `IN` with an array to query multiple countries or regions in one request.
`genre`	string	`EQUALS`, `IN`	App Store genre name. Enumeration values are: BUSINESS, EDUCATION, ENTERTAINMENT, FINANCE, FOOD_DRINK, GAMES, HEALTH_FITNESS, LIFESTYLE, NEW_PUBLICATION, PHOTO_VIDEO, PRODUCTIVITY_UTILITIES, SHOPPING, SOCIAL_NETWORKING, SPORTS, TRAVEL.
`searchTerm`	string	`EQUALS`, `IN`, `CONTAINS`, `STARTS_WITH`	The search term text. `CONTAINS` and `STARTS_WITH` match case-insensitively.
`rankInGenre`	integer	`EQUALS`, `GREATER_THAN`, `LESS_THAN`, `GREATER_THAN_OR_EQUAL_TO`, `LESS_THAN_OR_EQUAL_TO`, `BETWEEN`	`BETWEEN` requires exactly two values.
`searchPopularityInGenre`	integer	`EQUALS`, `GREATER_THAN`, `LESS_THAN`, `GREATER_THAN_OR_EQUAL_TO`, `LESS_THAN_OR_EQUAL_TO`, `BETWEEN`	`BETWEEN` requires exactly two values.
`searchPopularity1to100`	integer	`EQUALS`, `GREATER_THAN`, `LESS_THAN`, `GREATER_THAN_OR_EQUAL_TO`, `LESS_THAN_OR_EQUAL_TO`, `BETWEEN`	`BETWEEN` requires exactly two values.
`searchPopularity1to5`	integer	`EQUALS`, `GREATER_THAN`, `LESS_THAN`, `GREATER_THAN_OR_EQUAL_TO`, `LESS_THAN_OR_EQUAL_TO`, `BETWEEN`	`BETWEEN` requires exactly two values.

Sortable Fields

All fields are sortable. There is a maximum two sort fields per request.

Field	Sort Directions	Default
`week`	`ASC`, `DESC`	—
`month`	`ASC`, `DESC`	—
`countryOrRegion`	`ASC`, `DESC`	—
`genre`	`ASC`, `DESC`	1st: `ASC`
`searchTerm`	`ASC`, `DESC`	—
`rankInGenre`	`ASC`, `DESC`	2nd: `ASC`
`searchPopularityInGenre`	`ASC`, `DESC`	—
`searchPopularity1to100`	`ASC`, `DESC`	—
`searchPopularity1to5`	`ASC`, `DESC`	—