<!--
{
  "availability" : [
    "Apple Ads Platform API: 1.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "Apple-Ads-Platform-API",
  "identifier" : "/documentation/Apple-Ads-Platform-API/Query-keyword-suggestions",
  "metadataVersion" : "0.1.0",
  "role" : "Web Service Endpoint",
  "symbol" : {
    "kind" : "Web Service Endpoint",
    "modules" : [
      "Apple Ads Platform API"
    ],
    "preciseIdentifier" : "rest:apple-ads-platform-api:post:suggestions-keywords-query"
  },
  "title" : "Query Keyword Suggestions"
}
-->

# Query Keyword Suggestions

Query keyword suggestions based on search terms and App Store countries or regions using structured filters.

## Discussion

Each [`KeywordSuggestion`](/documentation/Apple-Ads-Platform-API/KeywordSuggestion) result contains `text` (the suggested keyword string) and `popularity` (a relative score). Sort by `popularity DESC` and use `pagination` to page through results.

See [`FilterOperator`](/documentation/Apple-Ads-Platform-API/RecommendationFilterOperator) for the full set of supported comparison operators.

### Filterable Fields

|Field               |Type            |Operators|Description                                                                   |
|--------------------|----------------|---------|------------------------------------------------------------------------------|
|`promotedObjectId`  |string          |`EQUALS` |Required. The app Adam ID. Keyword suggestions are scoped to the promoted app.|
|`promotedObjectType`|string (enum)   |`EQUALS` |Required. The type of promoted object.                                        |
|`terms`             |array of strings|`IN`     |Optional. Specific search terms to get suggestions for.                       |
|`countriesOrRegions`|array of strings|`IN`     |Optional. App Store country or region codes to scope results to.              |

## Payload Examples

This example queries keyword suggestions for an app scoped to the US and GB App Store countries or regions, seeded by specific search terms. The response returns suggested keyword strings with their relative popularity scores.

**Query Keyword Suggestions:**

### Request

```json
POST /v1/suggestions/keywords/query

{
 "filters": [
   {
     "field": "promotedObjectId",
     "operator": "EQUALS",
     "value": [
       "123456"
     ]
   },
   {
     "field": "promotedObjectType",
     "operator": "EQUALS",
     "value": [
       "APPSTORE_APP"
     ]
   },
   {
     "field": "terms",
     "operator": "IN",
     "value": [
       "productivity",
       "task management"
     ]
   },
   {
     "field": "countriesOrRegions",
     "operator": "IN",
     "value": [
       "US",
       "GB"
     ]
   }
 ]
}
```

### Response

```json
{
 "result": [
   {
     "text": "productivity app",
     "popularity": 85
   },
   {
     "text": "task manager",
     "popularity": 72
   },
   {
     "text": "to do list",
     "popularity": 68
   }
 ],
 "pagination": {
   "offset": 0,
   "pageSize": 20,
   "totalCount": 3
 }
}
```

---

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)