# Ads on Apple Maps Endpoints Query and retrieve brands, business categories, and creative rejection reasons. ## Overview Use the Apple Ads Platform API to create and manage Apple Maps campaigns that promote business locations on Apple Maps. Ads on Apple Maps help users find businesses; you can reach people before they search, at the top of the Suggested Places list on Search home, or after they search for something specific, on Search results. For a full end-to-end walkthrough, see [Advertising Your Business on Apple Maps](/documentation/Apple-Ads-Platform-API/journey-apple-maps-brand-ads). ## Review the Prerequisites Ads on Apple Maps require an Apple Ads profile and a validated brand in Apple Ads. A brand must have `eligibility.status: ELIGIBLE` before you can use it in a campaign. Your ad account must also have `productFeatures: ["BUSINESS_BRAND_MANUAL"]` and a `BUSINESS_BRAND` delegation with the Brand ID as `resourceId` before campaigns can go live. See [`ProductFeatures`](/documentation/Apple-Ads-Platform-API/ProductFeatures) for full delegation requirements. All API calls require a Bearer token and the `X-AP-Context: adAccountId` header. ## Understand the Campaign Structure App Store campaigns use three objects: Campaign, Ad Group, and Ad, plus a Creative. Apple Maps campaigns add two more, [Understanding Locations](/documentation/Apple-Ads-Platform-API/locations-overview) and [Managing Location Groups](/documentation/Apple-Ads-Platform-API/location-groups-overview), that sit between the Brand and the Ad Group. The dependency chain is: - **Brand**: the root object for the account. Every Maps campaign’s `promotedObjectId` is a brand ID. - **Location**: a physical place of business belonging to one brand. Locations are read-only and come from Apple Business. You can’t create or edit locations through this API. - **Location Group**: a named collection of a brand’s location IDs. Ad groups target a location group, not individual locations. You must build a location group before an ad group can use location-based targeting. - **Asset**: an uploaded image tied to the brand through `promotedObjectId`. Assets must reach `eligibility.status: ELIGIBLE` before use. - **Creative**: combines a brand asset, promotional text, and the Apple Maps place card destination into the ad unit. A creative references the brand and one or more assets. A Campaign references the Brand directly. Its Ad Groups reference a Location Group for targeting, and its Ads reference a Creative. Both the Location Group and the Creative must exist, and be in a valid state, before the Ad Group and Ad that depend on them can serve. ## Follow the Campaign Workflow Follow these steps, in order, to launch an Apple Maps campaign once your brand and assets are ready: 1. **Find and validate your brand.** Query the Brands API to retrieve your brand’s identifier, filtering by `eligibility.status: ELIGIBLE`. Campaign creation requires both `promotedObjectType: BUSINESS_BRAND` and `promotedObjectId` (the brand ID), and both remain immutable afterward. Confirm the correct brand before creating a campaign. 2. **Upload and prepare assets.** Upload images directly with [`Upload Asset`](/documentation/Apple-Ads-Platform-API/Upload-Asset). The multipart request body must include the binary image file alongside `promotedObjectId` and `promotedObjectType: BUSINESS_BRAND`. To check the `eligibility.status` field, use [`Get Asset`](/documentation/Apple-Ads-Platform-API/Get-Asset-by-ID). Assets must reach `ELIGIBLE` before you can reference them in a creative. 3. **Create location groups.** Location groups let you group the business locations you want to promote together under an ad group, rather than requiring you to set each one individually. Location groups don’t control who sees the ad or how close they are to a location. Geo and radius targeting on the ad group handle that separately. - Create a group with [`Create Location Group`](/documentation/Apple-Ads-Platform-API/Create-Location-Group), supplying `name`, `brandId`, `adAccountId`, `groupType` (`STATIC` or `DYNAMIC`), and the Apple Maps location IDs for `STATIC` groups. - To look up valid location IDs, use [`Query for Locations`](/documentation/Apple-Ads-Platform-API/Query-Locations), filtering by country, name, or status. - Groups with `groupType: DYNAMIC` start in `systemStatus: PENDING` while Apple Ads evaluates the rules. Wait for `systemStatus: VALID` before referencing the group in ad group targeting. 4. **Choose placements and markets.** Set the campaign’s `targeting` to a `supplySource` of `MAPS`, one or both Apple Maps placements (`MAPS_SEARCH_RESULTS` for Search results, `MAPS_SEARCH_HOME` for Search home), and a `countryOrRegion` list that includes only the markets where your brand is eligible. You can combine both placements in one campaign, or create separate campaigns per placement for independent budget control and reporting. All three targeting dimensions remain mutable after you create the campaign. 5. **Create a creative.** A creative assembles an asset, promotional text, and the tap destination (always the Apple Maps place card) into the ad unit shown on Apple Maps. Apple Ads may review creatives before they can serve. To monitor approval status, use [`Query Ad Creatives`](/documentation/Apple-Ads-Platform-API/POST-creatives-query). If Apple Ads rejects a creative or brand entity, query rejection reason details with [`Query Rejection Reasons for Brands`](/documentation/Apple-Ads-Platform-API/Query-policy-assignments-(rejection-reasons)-for-external-consumers). 6. **Create a campaign.** Create the campaign with a POST to `/v1/campaigns`. - Set `promotedObjectType: BUSINESS_BRAND` and your brand ID as `promotedObjectId`. - Set the `targeting` object you configured in step 4. - Set a `dailyBudget` with an amount and currency. - If your ad account is on monthly invoicing (`paymentModel: LOC`), you can later use [Budget Orders Endpoints](/documentation/Apple-Ads-Platform-API/budget-orders-endpoints) to cap total spend across a group of campaigns, on top of each campaign’s `dailyBudget`. Accounts on `PAYG` can’t use budget orders. - Both `promotedObjectType` and `promotedObjectId` become immutable after creation. 7. **Create an ad group.** Ad groups sit under a campaign. Reference the location group from step 3 in `targeting.locationGroup.include` to restrict delivery to your chosen locations. This array accepts more than one location group. Apple Maps ad groups also support admin area, locality, postal code, radius, and daypart targeting. You can also add keywords with `PHRASE` or `CATEGORY` match types for the Search results placement. 8. **Create an ad.** Link the creative to the ad group by creating an Ad object that references the `creativeId`, `campaignId`, and `adGroupId`. Ads go through Apple review before serving. 9. **Pull reports.** Apple Maps campaigns use the fixed `business-brands` path segment in all report endpoints (`/v1/reports/business-brands/campaigns/query`, `/adgroups/query`, `/ads/query`, `/keywords/query`, and `/searchterms/query`). These endpoints support `timeZone: "ORTZ"` to align timestamps to your organization’s configured time zone. There’s no dedicated location-level report endpoint. Instead, group or filter any of these by `locationId` to see performance broken down by individual map location. ## Topics [`Query Brands`](/documentation/Apple-Ads-Platform-API/Query-Brands) [`Get Brand by ID`](/documentation/Apple-Ads-Platform-API/Get-Brand-by-ID) [`Query Business Categories`](/documentation/Apple-Ads-Platform-API/Query-Categories) [`Get Business Category`](/documentation/Apple-Ads-Platform-API/Get-Category-by-ID) [`Query Rejection Reasons for Brands`](/documentation/Apple-Ads-Platform-API/Query-policy-assignments-(rejection-reasons)-for-external-consumers) --- Copyright © 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)