Geo Targeting Endpoints

Overview

Geo targeting lets you focus ad delivery on specific countries, regions, cities, or postal codes associated with where the ad viewer is located.

• The API doesn’t use precise location for either channel: App Store campaigns use the device’s location, and Apple Maps campaigns use either the current map view or the device’s location.

• Whether device location is available depends on whether the user has location services enabled for the app.

• Apple Maps campaigns discover users based on their location while they’re using Apple Maps, not based on the business locations the ads promote.

• The API provides dedicated endpoints for discovering valid location identifiers, which you then reference in ad group targeting dimensions.

Query Geo Location Metadata

App Store and Apple Maps campaigns both use the Geo Search endpoints (GET and POST /v1/search/geo (Query Geo Locations)). The supplySource parameter controls which entity types appear in the results and scopes eligibility evaluation to the relevant campaign context.

Use the two geo search endpoints to retrieve geographic location metadata:

• Use GET /v1/search/geo (Search Geo Locations) to perform a text search by name or wildcard. It requires the supplySource query parameter, and it accepts optional parameters query (minimum two characters, or * to return all), entity, countrycode, eligible, offset, and pageSize.

• Use POST /v1/search/geo (Query Geo Locations) to look up locations by ID. It accepts a GeoSearchPostRequest body with a geoRequest array of (entity ID, type) or (legacyID, type) pairs, and it also requires supplySource.

Each result includes id, legacyId (pipe-delimited hierarchy, for example, US|CA|San Francisco), entity, displayName, countryOrRegion, adminArea, locality, postalCode, and an eligibility object scoped to the requested supply source.

By default, the API includes soft-blocked geos (low search volume, sparse coverage) with eligibility data. Pass eligible=true on the GET endpoint to exclude them from results.

Target Apple Maps Campaigns by Geography

For Apple Maps campaigns, geo targeting controls where the ad viewer is located when the ad is shown, not which advertiser business locations the ad group promotes. To reach users in specific geographic areas on Maps, use the postalCode, locality, and adminArea targeting dimensions.

To find valid locality and postal code identifiers for Maps campaigns, use GET /v1/search/geo (Search Geo Locations) with supplySource=MAPS. The API restricts results to the US and Canada. You can only use the PostalCode entity type under supplySource=MAPS.

You can view location-level reporting for Apple Maps campaigns by grouping or filtering the Apple Maps report endpoints (POST /v1/reports/business-brands/{campaigns,adgroups,ads,keywords,searchterms}/query) by locationId, rather than through a dedicated locations-report endpoint.

Apply Geo Targeting Dimensions to an Ad Group

You apply geo targeting through the targeting field on an ad group, alongside the ad group’s other audience and placement dimensions. See AdGroupTargeting for the full set of available dimensions. Each geo dimension uses a TargetingData object with include and exclude arrays of location identifiers.

The following geo targeting dimensions are available:

Dimensions can be combined. For example, target a country while excluding specific cities within it. Use exclude arrays to suppress delivery in locations that overlap with a broader inclusion.

Check Supported Languages by Market

This applies to App Store campaigns only. To retrieve the languages supported for App Store advertising in each country or region, use POST /v1/metadata/apps/supported-languages/query (Query Supported App Languages). The response includes adsSupportedLanguages and adsDefaultLanguages per country code. To validate creative language selection before targeting a new market, use this data.

Report on Performance by Geography

Both Apps and Apple Maps reports support geographic breakdowns via the groupBy parameter. The following table lists which geographic dimensions each report type supports:

For Apple Maps, locationId groups report rows by individual business location, enabling per-location performance analysis across the full campaign hierarchy.

Use the Geo Search Endpoints

Use these endpoints to retrieve and search geographic location metadata:

Topics

• Query Geo Locations
• Search Geo Locations

See Also

Geo Targeting

• Geo Targeting Data Objects
• Geo Targeting Data Types