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

# Query Category Suggestions

Query category suggestions for apps or brands using either a discovery or search route based on the query type.

## Discussion

Each result is a [`CategorySuggestion`](/documentation/Apple-Ads-Platform-API/CategorySuggestion) object with a `category` name (for example, `"Productivity"`) and a `popularity` 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                                                                                                                                                           |
|--------------------|-------------|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|`queryType`         |string (enum)|`EQUALS`    |Required. Selects this query route: `SUGGESTION` discovers categories for an app or brand, and `SEARCH` looks up or searches categories by name.                      |
|`promotedObjectId`  |string       |`EQUALS`    |Required for the `SUGGESTION` route. The app or brand ID.                                                                                                             |
|`promotedObjectType`|string (enum)|`EQUALS`    |Required for the `SUGGESTION` route. Can be either `APPSTORE_APP` or `BUSINESS_BRAND`.                                                                                |
|`category`          |string       |`IN`, `LIKE`|Required for the `SEARCH` route. `IN` fetches popularity for specific named categories. `LIKE` performs a partial string match search across all available categories.|

## Payload Examples

This example discovers category suggestions for a brand using the SUGGESTION route. The response is a list of category names with their relative popularity scores. The same route also works for apps, using `APPSTORE_APP` as the `promotedObjectType`.

**Suggestion for Brand:**

### Request

```json
POST /v1/suggestions/categories/query

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

### Response

```json
{
 "result": [
   {
     "category": "Productivity",
     "popularity": 90
   },
   {
     "category": "Business",
     "popularity": 78
   },
   {
     "category": "Utilities",
     "popularity": 65
   }
 ],
 "pagination": {
   "offset": 0,
   "pageSize": 20,
   "totalCount": 3
 }
}
```

**Search by Category Name:**

### Request

```json
POST /v1/suggestions/categories/query

{
 "filters": [
   {
     "field": "queryType",
     "operator": "EQUALS",
     "value": [
       "SEARCH"
     ]
   },
   {
     "field": "category",
     "operator": "IN",
     "value": [
       "Productivity",
       "Business"
     ]
   }
 ]
}
```

### Response

```json
{
 "result": [
   {
     "category": "Productivity",
     "popularity": 90
   },
   {
     "category": "Business",
     "popularity": 78
   }
 ],
 "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 categories, rather than looking up specific named categories with `IN`.

### Request

```json
POST /v1/suggestions/categories/query

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

### Response

```json
{
 "result": [
   {
     "category": "Productivity",
     "popularity": 90
   },
   {
     "category": "Food & Drink",
     "popularity": 42
   }
 ],
 "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)