Search Terms Report (Brands)

Retrieve performance metrics for the actual search terms that triggered keyword matches in Apple Maps campaigns.

URL

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

Header Parameters

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

Response Codes

Status	Reason	Type	Description
200	OK Content-Type: application/json	`BrandsSearchTermReportResponse`	Successful response. Returns BrandsSearchTermReportResponse (`result`: BrandsSearchTermResultContainer).
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 search term reports show the actual user-entered queries that matched a keyword and generated an impression on the Search Results placement. Each row contains the searchTermText field and the associated keyword object, allowing you to map observed search behavior back to specific bid keywords in your Apple Maps campaign.

Use Apple Maps search term data to:

Discover high-intent queries (“coffee near me”, “best pizza downtown”) to promote to dedicated exact-match keywords.
Identify irrelevant or off-brand queries to add as negative keywords.
Understand match expansion breadth for BROAD-match keywords in Apple Maps campaigns.

Filter by adGroupId or campaignId to scope results to a specific part of your account.

See Filter for the full set of supported comparison operators.

Request Body

See BrandsReportingRequest.

Search term reports for Apple Maps support only the deviceClass groupBy dimension.

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

The following dimensions are not supported for the SEARCHTERM entity under business-brands:

supplyPlacement
locationId

Granularity constraints follow the same date range rules as other Apple Maps reports, except HOURLY isn’t available for search terms.

Granularity	Constraint
`DAILY`	Date range start must be within the last 90 days. Date range must be greater than one day.
`HOURLY`	Not supported for the `SEARCHTERM` entity.
`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.

Search term reporting carries several restrictions beyond granularity, including a required ORTZ timezone and privacy-based suppression of low-volume terms.

Constraint	Detail
Timezone	Only `ORTZ` is supported. `UTC` is excluded for search term reporting.
`HOURLY` granularity	Not available for search terms.
`EMPTY_METRICS` option	Not supported for `SEARCHTERM` in `business-brands`.
`supplyPlacement` groupBy	Not supported at the search term entity level.
`locationId` groupBy	Not supported at the search term entity level.
Privacy threshold	Low-volume search terms may be suppressed or aggregated to protect user privacy.