Query Phrase Suggestions

Query phrase suggestions using either a discovery or search route based on the query type.

URL

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

Header Parameters

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

Response Codes

Status	Reason	Type
200	OK Content-Type: application/json	`RecommendationQueryPhraseSuggestionResponse`
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 PhraseSuggestion object. Sort by popularity DESC and use pagination to page through results.

Use SUGGESTION to discover new candidate phrases for an app or brand. It requires promotedObjectId and promotedObjectType, and works well when building a phrase list from scratch. Use SEARCH to look up or match specific phrases you already have in mind, using phrase with IN for an exact popularity lookup or LIKE for a partial match. The SEARCH route doesn’t require promotedObjectId.

See FilterOperator for the full set of supported comparison operators.

Filterable Fields

Field	Type	Operators	Description
`queryType`	string (enum)	`EQUALS`	Required. `SUGGESTION` discovers phrases for an app or brand, and `SEARCH` looks up or searches specific phrases.
`promotedObjectId`	string	`EQUALS`	Required for the `SUGGESTION` route. The App Store app ID or brand ID, depending on `promotedObjectType`.
`promotedObjectType`	string (enum)	`EQUALS`	Required for the `SUGGESTION` route. `APPSTORE_APP` or `BUSINESS_BRAND`.
`phrase`	string	`IN`, `LIKE`	Required for the `SEARCH` route. `IN` fetches popularity for specific phrases. `LIKE` performs a string match search.

Payload Examples

These examples discover relevant search phrases for an app or brand using the SUGGESTION route, and look up or search specific phrases using the SEARCH route.

HTTP Body

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