<!--
{
  "availability" : [
    "Apple Ads Platform API: 1.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "Apple-Ads-Platform-API",
  "identifier" : "/documentation/Apple-Ads-Platform-API/Query-phrase-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-phrases-query"
  },
  "title" : "Query Phrase Suggestions"
}
-->

# Query Phrase Suggestions

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

## Discussion

Each result is a [`PhraseSuggestion`](/documentation/Apple-Ads-Platform-API/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`](/documentation/Apple-Ads-Platform-API/RecommendationFilterOperator) 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.

**Discover Phrases for an App:**

### Request

```json
POST /v1/suggestions/phrases/query

{
 "filters": [
   {
     "field": "promotedObjectId",
     "operator": "EQUALS",
     "value": [
       "123456"
     ]
   },
   {
     "field": "promotedObjectType",
     "operator": "EQUALS",
     "value": [
       "APPSTORE_APP"
     ]
   },
   {
     "field": "queryType",
     "operator": "EQUALS",
     "value": [
       "SUGGESTION"
     ]
   }
 ]
}
```

### Response

```json
{
 "result": [
   {
     "phrase": "best productivity apps",
     "popularity": 82
   },
   {
     "phrase": "task management tools",
     "popularity": 75
   },
   {
     "phrase": "organize my day app",
     "popularity": 61
   }
 ],
 "pagination": {
   "offset": 0,
   "pageSize": 20,
   "totalCount": 3
 }
}
```

**Discover Phrases for Maps:**

### Request

```json
POST /v1/suggestions/phrases/query

{
 "filters": [
   {
     "field": "promotedObjectId",
     "operator": "EQUALS",
     "value": [
       "9151314442816847872"
     ]
   },
   {
     "field": "promotedObjectType",
     "operator": "EQUALS",
     "value": [
       "BUSINESS_BRAND"
     ]
   },
   {
     "field": "queryType",
     "operator": "EQUALS",
     "value": [
       "SUGGESTION"
     ]
   }
 ]
}
```

### Response

```json
{
 "result": [
   {
     "phrase": "coffee shop near me",
     "popularity": 88
   },
   {
     "phrase": "family friendly restaurant",
     "popularity": 70
   },
   {
     "phrase": "best brunch spot",
     "popularity": 64
   }
 ],
 "pagination": {
   "offset": 0,
   "pageSize": 20,
   "totalCount": 3
 }
}
```

**Search by Phrase:**

This example uses `IN` to fetch popularity for specific known phrases, using the SEARCH route.

### Request

```json
POST /v1/suggestions/phrases/query

{
 "filters": [
   {
     "field": "queryType",
     "operator": "EQUALS",
     "value": [
       "SEARCH"
     ]
   },
   {
     "field": "phrase",
     "operator": "IN",
     "value": [
       "best productivity apps",
       "task management tools"
     ]
   }
 ]
}
```

### Response

```json
{
 "result": [
   {
     "phrase": "best productivity apps",
     "popularity": 82
   },
   {
     "phrase": "task management tools",
     "popularity": 75
   }
 ],
 "pagination": {
   "offset": 0,
   "pageSize": 20,
   "totalCount": 2
 }
}
```

**Search by Partial Match:**

This example uses `LIKE` to perform a partial string match search across all available phrases, rather than looking up specific phrases with `IN`.

### Request

```json
POST /v1/suggestions/phrases/query

{
 "filters": [
   {
     "field": "queryType",
     "operator": "EQUALS",
     "value": [
       "SEARCH"
     ]
   },
   {
     "field": "phrase",
     "operator": "LIKE",
     "value": [
       "productivity"
     ]
   }
 ]
}
```

### Response

```json
{
 "result": [
   {
     "phrase": "best productivity apps",
     "popularity": 82
   },
   {
     "phrase": "productivity tools for teams",
     "popularity": 58
   }
 ],
 "pagination": {
   "offset": 0,
   "pageSize": 20,
   "totalCount": 2
 }
}
```

---

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)