<!--
{
  "availability" : [
    "Apple Ads Platform API: 1.0.0 -"
  ],
  "documentType" : "article",
  "framework" : "Apple-Ads-Platform-API",
  "identifier" : "/documentation/Apple-Ads-Platform-API/journey-apple-maps-brand-ads",
  "metadataVersion" : "0.1.0",
  "role" : "article",
  "title" : "Advertising Your Business on Apple Maps"
}
-->

# Advertising Your Business on Apple Maps

Identify your brand, upload creative assets, build location groups, and create campaigns, ad groups, creatives, and ads to promote it on Apple Maps.

## Overview

You can promote ads on Apple Maps across two placements: Search results and Search home. Every Maps campaign uses `promotedObjectType: BUSINESS_BRAND`. For the full endpoint reference, see [Ads on Apple Maps Endpoints](/documentation/Apple-Ads-Platform-API/brands-endpoints).

Before you begin:

- Ads on Apple Maps require an Apple Ads profile and a validated brand in Apple Ads.
- Your ad account must have `productFeatures: ["BUSINESS_BRAND_MANUAL"]` and a `BUSINESS_BRAND` delegation to create Maps campaigns.
- All API calls require a `Bearer` token as described in [Implementing OAuth for the Apple Ads Platform API](/documentation/Apple-Ads-Platform-API/implementing-oauth-for-the-apple-ads-platform-api) and [Calling the Apple Ads Platform API](/documentation/Apple-Ads-Platform-API/calling-apple-ads-platform-api).
- All ad-account-scoped calls also require the `X-AP-Context: adAccountId` header.
- When automating campaign, creative, or location group operations at scale, watch the rate-limit headers described in [Applying Rate Limits](/documentation/Apple-Ads-Platform-API/rate-limits) and back off before hitting a `429`.
- For full delegation requirements, see [`ProductFeatures`](/documentation/Apple-Ads-Platform-API/ProductFeatures).

## Identify Your Brand

Retrieve your brand with [`Query Brands`](/documentation/Apple-Ads-Platform-API/Query-Brands), as shown below. The response returns the brand `id` you use as the `promotedObjectId` throughout campaign creation.

```json
POST /v1/business-brands/query

{
  "filters": [
    {
      "field": "eligibility.status",
      "operator": "EQUALS",
      "value": "ELIGIBLE"
    }
  ]
}
```

To fetch a single brand’s full details, use [`Get Brand by ID`](/documentation/Apple-Ads-Platform-API/Get-Brand-by-ID). A brand must have `eligibility.status: ELIGIBLE` before you can use it in an active campaign.

## Upload Creative Assets

Ads on Apple Maps can use image assets. Use [`Upload Asset`](/documentation/Apple-Ads-Platform-API/Upload-Asset) to upload an image file. The response returns an `assetId` you can use in the ad creative, as shown here:

```json
POST /v1/assets/upload

{
  "file": "hero.png",
  "promotedObjectId": "9876543",
  "promotedObjectType": "BUSINESS_BRAND"
}
```

After upload is complete, use [`Query Assets`](/documentation/Apple-Ads-Platform-API/Query-Assets) to list and filter your asset library by status, type, or brand, and use [`Get Asset`](/documentation/Apple-Ads-Platform-API/Get-Asset-by-ID) to inspect a specific asset’s processing state. Assets must reach `ELIGIBLE` (`eligibility.status`) before you can use them in a creative.

## Build Location Groups

Location groups organize the business locations you want to promote together under an ad group, rather than requiring you to set each location individually. Create a location group with [`Create Location Group`](/documentation/Apple-Ads-Platform-API/Create-Location-Group) by supplying the required `adAccountId`, `brandId`, `groupType`, and a list of location IDs for `STATIC` groups, as shown here:

```json
POST /v1/location-groups

{
  "name": "AwayFinder - West Coast Stores",
  "adAccountId": "293897290",
  "brandId": "9876543",
  "groupType": "STATIC",
  "locationIds": [
    "1001",
    "1002",
    "1003"
  ]
}
```

Notes when creating location groups:

- A group with a fixed, manually curated list of location IDs reaches `systemStatus: VALID` immediately.
- `DYNAMIC` groups use rule-based criteria to automatically include matching locations and start with `systemStatus: PENDING` while Apple Ads evaluates the rules against the brand’s locations. Wait for `systemStatus: VALID` before referencing a `DYNAMIC` group in ad group targeting.
- To find valid location IDs, query [`Query for Locations`](/documentation/Apple-Ads-Platform-API/Query-Locations), which returns Apple Ads locations for a brand and filters by country, name, or status.

For more information, see [Managing Location Groups](/documentation/Apple-Ads-Platform-API/location-groups-overview).

- To list existing groups, use [`Query Location Groups`](/documentation/Apple-Ads-Platform-API/Query-Location-Groups). To add or remove locations over time, use [`Update Location Group`](/documentation/Apple-Ads-Platform-API/Update-Location-Group).

## Choose Placements and Markets

Before creating the campaign, select where you want your ads to run on Apple Maps, and choose one or more markets for the campaign. These choices populate the [`CampaignTargetingCreate`](/documentation/Apple-Ads-Platform-API/CampaignTargetingCreate) object. Here are the fields that control placement and market:

|Field            |What it controls                                                                    |
|-----------------|------------------------------------------------------------------------------------|
|`supplySource`   |The ad channel. For all Apple Maps campaigns, set this to `MAPS`.                   |
|`supplyPlacement`|The specific Apple Maps placement where the ad appears.                             |
|`countryOrRegion`|The markets where the campaign is eligible to serve, using ISO 3166-1 alpha-2 codes.|

Apple Maps campaigns support two placements:

|Value                |Placement     |Notes                                                                                                                                                                                                           |
|---------------------|--------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|`MAPS_SEARCH_RESULTS`|Search results|Reaches people after they search for something specific and supports radius targeting at the ad group level. See <doc://com.apple.apple-ads-platform-api/documentation/Apple-Ads-Platform-API/AdGroupTargeting>.|
|`MAPS_SEARCH_HOME`   |Search home   |Reaches people at the top of the Suggested Places list, before they search.                                                                                                                                     |

You can include both placement values in a single campaign, or create separate campaigns per placement for independent budget control and reporting. The brand you identified earlier includes a `countryOrRegion` field indicating the markets where the brand is eligible. Set `countryOrRegion.include` to the subset of those markets this campaign should target, like this:

```json
"targeting":
{
  "supplySource": {
    "include": [
      "MAPS"
    ]
  },
  "supplyPlacement": {
    "include": [
      "MAPS_SEARCH_RESULTS"
    ]
  },
  "countryOrRegion": {
    "include": [
      "US"
    ]
  }
}
```

After creation, all three dimensions remain mutable and you can update them via [`CampaignTargeting`](/documentation/Apple-Ads-Platform-API/CampaignTargeting).

## Create an Apple Maps Campaign

You can create a campaign with [`Create a Campaign`](/documentation/Apple-Ads-Platform-API/POST-campaigns), like this:

```json
POST /v1/campaigns

{
  "name": "AwayFinder - West Coast Brand - Q1",
  "adAccountId": 293897290,
  "billingEvent": "TAPS",
  "promotedObjectType": "BUSINESS_BRAND",
  "promotedObjectId": "9876543",
  "dailyBudget": {
    "value": { "amount": "200.00", "currency": "USD" }
  },
  "targeting": {
    "supplySource": { "include": ["MAPS"] },
    "supplyPlacement": { "include": ["MAPS_SEARCH_RESULTS"] }
  },
  "bidStrategy": {
    "bidStrategyType": "MAX_ENGAGEMENTS",
    "bidStrategyGoal": "TAP"
  },
  "status": "ENABLED"
}
```

## Create an Ad Group with Location Targeting

Create an ad group under your Apple Maps campaign with [`Create an Ad Group`](/documentation/Apple-Ads-Platform-API/POST-adgroups). Apple Maps ad groups support admin area, locality, postal code, location group, radius, and daypart targeting. You can add keyword phrases and keyword categories for the Search results placement, as shown below, though keyword bids don’t apply to ad groups that use location groups.

For a full description of targeting dimensions, see [Ad Groups Endpoints](/documentation/Apple-Ads-Platform-API/adgroups-endpoints). Reference the location group IDs from the previous step in the `targeting.locationGroup` field to restrict delivery to your chosen locations. This ad group’s `bidStrategy` matches the `MAX_ENGAGEMENTS` / `TAP` pairing you set on the campaign.

```json
POST /v1/adgroups

{
  "campaignId": 542317099,
  "name": "AwayFinder - West Coast Locations",
  "pricingModel": "CPT",
  "bidStrategy": {
    "bidStrategyType": "MAX_ENGAGEMENTS",
    "bidStrategyGoal": "TAP"
  },
  "targeting": {
    "locationGroup": {
      "include": ["LG-77001"]
    }
  },
  "status": "ENABLED"
}
```

## Create a Creative

A creative ties together an asset, promotional text, and the destination (always the Apple Maps place card) into the ad unit shown in Apple Maps. You can create one with [`Create an Ad Creative`](/documentation/Apple-Ads-Platform-API/POST-creatives), referencing the brand and the asset IDs from the previous steps, like this:

```json
POST /v1/creatives

{
  "name": "AwayFinder - Summer Promo - Logo Banner",
  "creativeType": "LOCAL_ADS_SEARCH_CREATIVE",
  "creativeSpec": {
    "brandId": "9876543",
    "creativeSubtype": "BUSINESS_ASSET",
    "creativeAssets": [
      { "assetId": "770e8400-e29b-41d4-a716-446655440002" }
    ],
    "localizedText": {
      "en-US": { "promoText": "Visit us today for special offers!" }
    },
    "defaultLocale": "en-US"
  },
  "destination": {
    "destinationType": "LOCAL_ADS_PLACECARD"
  }
}
```

To audit your creative library, use [`Query Ad Creatives`](/documentation/Apple-Ads-Platform-API/POST-creatives-query) and [`Get an Ad Creative`](/documentation/Apple-Ads-Platform-API/GET-creatives-_id_). Creatives go through a review process. If Apple Ads doesn’t approve a creative, [`Query Rejection Reasons for Brands`](/documentation/Apple-Ads-Platform-API/Query-policy-assignments-(rejection-reasons)-for-external-consumers) returns rejection reason details.

## Create an Ad Linking a Creative and an Ad Group

With the creative and ad group ready, create the ad with [`Create an Ad`](/documentation/Apple-Ads-Platform-API/POST-ads) to connect them, as in the code below. Ads for Apple Maps campaigns reference the creative ID you got from the Create a Creative section above.

```json
POST /v1/ads

{
  "adGroupId": 542317200,
  "creativeId": 666777888,
  "name": "Summer Promo Ad",
  "status": "ENABLED"
}
```

## Pull Apple Maps Campaign Reports

Apple Maps campaigns use the `business-brands` promoted object type in all report endpoints. You can retrieve campaign-level performance with [`Campaigns Report (Brands)`](/documentation/Apple-Ads-Platform-API/Get-brand-campaign-reports) and drill into ad group or creative performance as needed, like this:

```json
POST /v1/reports/business-brands/campaigns/query

{
  "timeRange": {
    "start": "2026-01-01",
    "end": "2026-01-31",
    "timeZone": "ORTZ",
    "granularity": "DAILY"
  },
  "filters": [
    { "field": "campaignId", "operator": "EQUALS", "value": 542317099 }
  ]
}
```

Apple Maps campaigns don’t have a dedicated location-level report endpoint. Instead, you can group or filter any of the five `business-brands` report endpoints (`campaigns`, `adgroups`, `ads`, `keywords`, `searchterms`) by `locationId` to see performance broken down by individual map location. For deeper funnel analysis, use [`Ad Groups Report (Brands)`](/documentation/Apple-Ads-Platform-API/Get-brand-ad-group-reports), [`Ads Report (Brands)`](/documentation/Apple-Ads-Platform-API/Get-brand-ad-reports), [`Keywords Report (Brands)`](/documentation/Apple-Ads-Platform-API/Get-brand-keyword-reports), and [`Search Terms Report (Brands)`](/documentation/Apple-Ads-Platform-API/Get-brand-search-term-reports).

## Optimize Campaigns

With Apple Maps campaigns running, you can:

- Audit your asset library over time with [`Query Assets`](/documentation/Apple-Ads-Platform-API/Query-Assets) and replace underperforming creatives.
- Add keywords to ad groups with [`Create a Keyword`](/documentation/Apple-Ads-Platform-API/POST-keywords) for the Search results placement within Maps.
- Audit any changes made to campaigns or creatives using [`Query Change History`](/documentation/Apple-Ads-Platform-API/Query-audit-summary-_-grouped-by-transaction).

---

Copyright &copy; 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)