Ads Report (Brands)
Retrieve performance metrics for Apple Maps ads.
URL
POST https://api.ads.apple.com/v1/reports/business-brands/ads/queryHeader Parameters
| Name | Type | Description |
|---|---|---|
X-Ap-Context Required | string |
Response Codes
| Status | Reason | Type | Description |
|---|---|---|---|
| 200 | OK Content-Type: application/json | BrandsAdReportResponse | Successful response. Returns BrandsAdReportResponse ( |
| 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
Brand ad reports return one row per ad. Each row contains a metadata object with ad identifiers (including campaignId and adGroupId), totalMetrics aggregated over the full date range, and a granularMetrics array broken down by the selected granularity.
For Apple Maps ads, the metadata object includes a nested creative object (BrandsReportingCreative) with the creative’s id, creativeType, and systemStatus. There is no flat creativeId field. Filter by adGroupId or campaignId in the filters array to scope results.
See Filter for the full set of supported comparison operators.
Request Body
Brand ad reports can be grouped by device type, business location, or ad placement.
Dimension | Description |
|---|---|
| Break down metrics by device type ( |
| Break down metrics per business location. |
| Break down metrics by ad placement. |
Ad reports follow the standard date range rules per granularity, except HOURLY isn’t available at the ad level.
Granularity | Constraint |
|---|---|
| Date range start must be within the last 90 days. Date range must be greater than one day. |
| Not supported for the |
| Date range start within the last 365 days. End date must be at least 14 days in the past. |
| 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.
The EMPTY_METRICS value isn’t supported for business-brands ads, HOURLY granularity isn’t available, and only ORTZ or UTC timezones are accepted.
Constraint | Detail |
|---|---|
| Not supported for |
| Not available for ads. Use |
Timezone | Use |