Keywords Report (Brands)

Retrieve performance metrics for Apple Maps keywords.

URL

POST https://api.ads.apple.com/v1/reports/business-brands/keywords/query

Header Parameters

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

Response Codes

Status	Reason	Type	Description
200	OK Content-Type: application/json	`BrandsKeywordReportResponse`	Successful response. Returns BrandsKeywordReportResponse (`result`: BrandsKeywordResultContainer).
400	Bad Request Content-Type: application/json	`Error`	Bad Request. Returns ErrorResponse.
401	Unauthorized Content-Type: application/json	`Error`	Unauthorized.
403	Forbidden Content-Type: application/json	`Error`	Forbidden.
404	Not Found Content-Type: application/json	`Error`	Not Found. Returns ErrorResponse.
429	Too Many Requests Content-Type: application/json	`Error`	Rate Limit Exceeded. Returns ErrorResponse.
500	Internal Server Error Content-Type: application/json	`Error`	Internal Server Error. Returns ErrorResponse.

Discussion

Apple Maps keyword performance reports return one row per keyword. Each row contains a metadata object with keyword identifiers (including campaignId, adGroupId, text, and matchType), totalMetrics aggregated over the full date range, and a granularMetrics array broken down by the selected granularity.

Use filters to scope results to specific campaigns or ad groups. For Apple Maps campaigns, keywords represent search queries that trigger ad delivery on Apple Maps.

See Filter for the full set of supported comparison operators.

Request Body

See BrandsReportingRequest.

groupBy Dimensions

Apple Maps keyword reports support a reduced set of groupBy dimensions. Neither supplyPlacement nor locationId is available at the keyword entity level.

Dimension	Description
`deviceClass`	Break down metrics by device type (`IPHONE`, `IPAD`).

The supplyPlacement and locationId fields are not supported for the KEYWORD entity under business-brands.

Granularity constraints mirror other Apple Maps entities, with lookback windows ranging from 7 days for HOURLY to 90 days for MONTHLY.

Granularity	Constraint
`DAILY`	Date range start must be within the last 90 days. Date range must be greater than one day.
`HOURLY`	Date range start must be within the last 7 days.
`WEEKLY`	Date range start within the last 365 days. End date must be at least 14 days in the past.
`MONTHLY`	End date must be at least 90 days in the past.

To request a single day of data, omit granularity entirely. For a single-day request, the response returns results in totalMetrics only, since there is no granularMetrics breakdown to compute.

Keyword reports also exclude EMPTY_METRICS and the supplyPlacement/locationId dimensions, and should always be filtered by adGroupId or campaignId.

Constraint	Detail
`EMPTY_METRICS`	Not supported for `business-brands`.
`supplyPlacement` groupBy	Not supported at the keyword level.
`locationId` groupBy	Not supported at the keyword level.
Filter scope	Always filter by `adGroupId` or `campaignId` to avoid retrieving all keywords across the account.