---
title: Keywords Report (Brands)
framework: Apple Ads Platform API
role: symbol
role_heading: Web Service Endpoint
platforms: [apple ads platform api 1.0+]
path: apple-ads-platform-api/get-brand-keyword-reports
---

# 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

X-Ap-Context:

## Response Codes

200 OK: Successful response. Returns BrandsKeywordReportResponse (result: BrandsKeywordResultContainer). 400 Bad Request: Bad Request. Returns ErrorResponse. 401 Unauthorized: Unauthorized. 403 Forbidden: Forbidden. 404 Not Found: Not Found. Returns ErrorResponse. 429 Too Many Requests: Rate Limit Exceeded. Returns ErrorResponse. 500 Internal Server Error: Internal Server Error. Returns ErrorResponse.

## Discussion

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.  |   |  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.  |   |   |   |   |  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.  |   |   |   |   |  Payload Examples

## See Also

- [Campaigns Report (Brands)](apple-ads-platform-api/get-brand-campaign-reports.md)
- [Ad Groups Report (Brands)](apple-ads-platform-api/get-brand-ad-group-reports.md)
- [Ads Report (Brands)](apple-ads-platform-api/get-brand-ad-reports.md)
- [Search Terms Report (Brands)](apple-ads-platform-api/get-brand-search-term-reports.md)