Query Category Suggestions

Query category suggestions for apps or brands using either a discovery or search route based on the query type.

URL

POST https://api.ads.apple.com/v1/suggestions/categories/query

Header Parameters

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

Response Codes

Status	Reason	Type
200	OK Content-Type: application/json	`RecommendationQueryCategorySuggestionResponse`
400	Bad Request Content-Type: application/json	`RecommendationResponseBody`
401	Unauthorized Content-Type: application/json	`RecommendationResponseBody`
403	Forbidden Content-Type: application/json	`RecommendationResponseBody`
404	Not Found Content-Type: application/json	`RecommendationResponseBody`
429	Too Many Requests Content-Type: application/json	`RecommendationResponseBody`
500	Internal Server Error Content-Type: application/json	`RecommendationResponseBody`

Discussion

Each result is a CategorySuggestion object with a category name (for example, "Productivity") and a popularity score. Sort by popularity DESC and use pagination to page through results.

See FilterOperator for the full set of supported comparison operators.

Filterable Fields

Field	Type	Operators	Description
`queryType`	string (enum)	`EQUALS`	Required. Selects this query route: `SUGGESTION` discovers categories for an app or brand, and `SEARCH` looks up or searches categories by name.
`promotedObjectId`	string	`EQUALS`	Required for the `SUGGESTION` route. The app or brand ID.
`promotedObjectType`	string (enum)	`EQUALS`	Required for the `SUGGESTION` route. Can be either `APPSTORE_APP` or `BUSINESS_BRAND`.
`category`	string	`IN`, `LIKE`	Required for the `SEARCH` route. `IN` fetches popularity for specific named categories. `LIKE` performs a partial string match search across all available categories.

Payload Examples

This example discovers category suggestions for a brand using the SUGGESTION route. The response is a list of category names with their relative popularity scores. The same route also works for apps, using APPSTORE_APP as the promotedObjectType.

HTTP Body

See RecommendationQueryRequest. This endpoint supports two query routes selected by the queryType filter: SUGGESTION discovers categories for a specific app or brand, and SEARCH looks up or searches categories by name.