Suggestions Endpoints
Endpoints for querying keyword, phrase, category, and Target CPA suggestions.
Overview
Suggestions are read-only discovery tools for campaign setup and keyword expansion. Unlike Recommendations Endpoints, they’re stateless. There’s no apply or dismiss step and no lifecycle to track.
Query the Suggestions Endpoints
For bid sizing when launching a new App Store Campaigns Endpoints, use Query Target CPA Suggestion to retrieve the recommended target CPA based on recent tap-install CPI data. That endpoint uses a filters-only request body.
The three keyword discovery endpoints use a POST /query pattern with a RecommendationQueryRequest body. Each result includes a popularity score on a 0–100 scale. To prioritize the highest-impact candidates, sort by popularity DESC. The suggestions API exposes four endpoints, each returning a different type of suggestion:
Method | Path | Description |
|---|---|---|
|
| Returns ranked keyword strings for a given app, scoped to a promoted object and optional App Store countries or regions. See Query Keyword Suggestions. |
|
| Returns natural-language search phrases associated with an app or brand, or matched by text. Supports |
|
| Returns genre category names for apps or brands, or matched by name. Supports |
|
| Retrieves the recommended target CPA for an App Store app based on recent tap-install CPI data. See Query Target Cpa Suggestion. |
Keywords vs. Phrases
Keyword and phrase suggestions serve different targeting needs. Query Keyword Suggestions returns single ranked keyword strings meant to seed exact-match keyword targeting, and its results feed directly into Create a Keyword. Query Phrase Suggestions returns natural-language, multi-word search phrases people actually type, useful for broader phrase-level discovery or gauging phrase traffic rather than picking discrete keyword terms.
Request Keyword Suggestions
The promotedObjectId and promotedObjectType fields are both required. Optionally scope results to specific App Store countries or regions with countriesOrRegions, or seed with specific terms to get related suggestions. Results are KeywordSuggestion objects. To activate a suggestion, create a keyword entity via Create a Keyword. Here’s a sample request that scopes suggestions to a single app and two countries:
{
"filters": [
{
"field": "promotedObjectId",
"operator": "EQUALS",
"value": [
"123456"
]
},
{
"field": "promotedObjectType",
"operator": "EQUALS",
"value": [
"APPSTORE_APP"
]
},
{
"field": "countriesOrRegions",
"operator": "IN",
"value": [
"US",
"GB"
]
}
],
"sorting": [
{
"field": "popularity",
"order": "DESC"
}
],
"pagination": {
"offset": 0,
"pageSize": 20
}
}Request Phrase and Category Suggestions
Phrase and category suggestions support two distinct query routes, and you can use only one per request:
| Purpose | Required Filters |
|---|---|---|
| Discover suggestions for a specific app or brand. |
|
| Look up popularity for known values, or search by partial string. |
|
Use SUGGESTION when building a keyword list from scratch. Use SEARCH to check whether a specific phrase or category name has meaningful traffic, or to enumerate options with a partial string.