--- title: Search Terms 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-search-term-reports --- # 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 X-Ap-Context: ## Response Codes 200 OK: Successful response. Returns BrandsSearchTermReportResponse (result: BrandsSearchTermResultContainer). 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 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. note: Note: Apple Maps search term reports require the ORTZ timezone. The UTC timezone isn’t supported. The supplyPlacement and locationId dimensions are excluded from groupBy for the SEARCHTERM entity. 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. | | 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. | | | | | 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. | | | | | | | 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) - [Keywords Report (Brands)](apple-ads-platform-api/get-brand-keyword-reports.md)