Query Business Categories

Retrieve a paginated list of business categories using filters and sorting.

URL

POST https://api.ads.apple.com/v1/business-categories/query

Header Parameters

Name	Type	Description
`X-Ap-Context` Required	string

Response Codes

Status	Reason	Type
200	OK Content-Type: application/json	`BusinessCategoryQueryResponse`
400	Bad Request Content-Type: application/json	`BusinessCategoryQueryResponse`
401	Unauthorized Content-Type: application/json	`Error`
403	Forbidden Content-Type: application/json	`Error`
404	Not Found Content-Type: application/json	`Error`
429	Too Many Requests Content-Type: application/json	`Error`
500	Internal Server Error Content-Type: application/json	`Error`

Discussion

This endpoint returns a paginated list of business categories from the Maps taxonomy. Categories classify brands and locations. You use them to scope targeting and discovery within Apple Maps campaigns. An empty request body returns all categories with default pagination.

Each category has a qualifiedId using a dot to separate each level of the taxonomy hierarchy (for example, dining.restaurant). A single hierarchy level’s own name can itself contain underscores (for example, association_or_organization), so a dot always marks a hierarchy boundary, but an underscore doesn’t. Use the text value on a CATEGORY match-type Keyword to target Apple Maps searches within that category.

See QueryFilterOperator for the full set of supported comparison operators.

Filterable Fields

Field	Type	Operators	Sortable	Description
`name`	string	`STARTS_WITH`		English display name of the category.

Only name is confirmed filterable; other category fields (id, qualifiedId, eligibility) aren’t documented as query filters. The request body is a QueryRequest composed of QueryFilter conditions and QuerySort directives (QuerySortOrder), controlled by QueryPagination.

Request Body

See QueryRequest.

Each category record returned includes the following fields:

Field	Type	Description
`id`	string	Unique category identifier (MUID).
`name`	string	English display name of the category.
`qualifiedId`	string	Dot-delimited taxonomy path. Example: `dining.restaurant`.
`eligibility`	object	Ad serving eligibility for this category. See Eligibility.
`creationTime`	string	ISO-8601 creation timestamp. Read-only.
`modificationTime`	string	ISO-8601 last-modified timestamp. Read-only.

The qualifiedId format and eligibility status both carry specific rules:

Constraint	Detail
`qualifiedId` format	Dot-delimited hierarchy string. A dot always marks a hierarchy boundary, but an individual level’s name can itself contain underscores. Use this value as the `text` on a `CATEGORY` match-type Keyword.
Eligibility check	Only categories with `ELIGIBLE` status can be used in active Apple Maps campaigns.