<!--
{
  "availability" : [
    "apple-ads-platform-api: 1.0.0 -"
  ],
  "documentType" : "article",
  "framework" : "apple-ads-platform-api",
  "identifier" : "/documentation/apple-ads-platform-api/suggestions-endpoints",
  "metadataVersion" : "0.1.0",
  "role" : "collectionGroup",
  "title" : "Suggestions Endpoints"
}
-->

# 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](/documentation/apple-ads-platform-api/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](/documentation/apple-ads-platform-api/campaigns-endpoints), use [`Query Target CPA Suggestion`](/documentation/Apple-Ads-Platform-API/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`](/documentation/Apple-Ads-Platform-API/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                                                                                                                                                                                                                                        |
|------|-----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|`POST`|`/v1/suggestions/keywords/query`   |Returns ranked keyword strings for a given app, scoped to a promoted object and optional App Store countries or regions. See <doc://com.apple.apple-ads-platform-api/documentation/Apple-Ads-Platform-API/Query-keyword-suggestions>.              |
|`POST`|`/v1/suggestions/phrases/query`    |Returns natural-language search phrases associated with an app or brand, or matched by text. Supports `SUGGESTION` and `SEARCH` routes. See <doc://com.apple.apple-ads-platform-api/documentation/Apple-Ads-Platform-API/Query-phrase-suggestions>.|
|`POST`|`/v1/suggestions/categories/query` |Returns genre category names for apps or brands, or matched by name. Supports `SUGGESTION` and `SEARCH` routes. See <doc://com.apple.apple-ads-platform-api/documentation/Apple-Ads-Platform-API/Query-category-suggestions>.                      |
|`POST`|`/v1/suggestions/target-cpas/query`|Retrieves the recommended target CPA for an App Store app based on recent tap-install CPI data. See <doc://com.apple.apple-ads-platform-api/documentation/Apple-Ads-Platform-API/Query-target-CPA-suggestion>.                                     |

### 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`](/documentation/Apple-Ads-Platform-API/KeywordSuggestion) objects. To activate a suggestion, create a keyword entity via [`Create a Keyword`](/documentation/Apple-Ads-Platform-API/POST-keywords). Here’s a sample request that scopes suggestions to a single app and two countries:

```json
{
  "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:

|`queryType` |Purpose                                                          |Required Filters                                                         |
|------------|-----------------------------------------------------------------|-------------------------------------------------------------------------|
|`SUGGESTION`|Discover suggestions for a specific app or brand.                |`promotedObjectId`, `promotedObjectType`                                 |
|`SEARCH`    |Look up popularity for known values, or search by partial string.|`phrase` or `category` with `IN` (exact lookup) or `LIKE` (partial match)|

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.

## Topics

[`Query Keyword Suggestions`](/documentation/Apple-Ads-Platform-API/Query-keyword-suggestions)

[`Query Phrase Suggestions`](/documentation/Apple-Ads-Platform-API/Query-phrase-suggestions)

[`Query Category Suggestions`](/documentation/Apple-Ads-Platform-API/Query-category-suggestions)

[`Query Target CPA Suggestion`](/documentation/Apple-Ads-Platform-API/Query-target-CPA-suggestion)

## See Also

[Recommendations Endpoints](/documentation/apple-ads-platform-api/recommendations-endpoints)

Endpoints for querying, applying, and dismissing budget and Target CPA recommendations.

[Managing Reports](/documentation/apple-ads-platform-api/reports)

Retrieve performance data for campaigns, ad groups, ads, keywords, and search terms.

[Insights Endpoints](/documentation/apple-ads-platform-api/insights-endpoints)

Query impression share and search term popularity data for your apps.


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)