Query Geo Locations
Search for geographic locations by entity type and ID for use in ad group geo targeting.
URL
POST https://api.ads.apple.com/v1/search/geoHeader Parameters
| Name | Type | Description |
|---|---|---|
X-Ap-Context Required | string |
Response Codes
| Status | Reason | Type | Description |
|---|---|---|---|
| 200 | OK Content-Type: application/json | GeoSearchResponse | |
| 400 | Bad Request Content-Type: application/json | Error | |
| 401 | Unauthorized Content-Type: application/json | Error | |
| 403 | Forbidden Content-Type: application/json | Error | |
| 404 | Not Found Content-Type: application/json | Error | |
| 429 | Too Many Requests Content-Type: application/json | Error | |
| 500 | Internal Server Error Content-Type: application/json | Error |
Discussion
This endpoint returns a list of geographic locations matching the specified entity criteria. To look up valid geo IDs and names before assigning geo targets to an ad group, use this endpoint.
The API sorts results alphabetically by displayName and paginates them using GeoSearchPagination. Each result is a SearchEntity and includes a hierarchy identifier in legacyId, which is a pipe-delimited string that encodes the full geographic hierarchy, such as US|CA|San Francisco. See GeoEntityType for the full list of entity granularities.
The supplySource field controls which entity types appear in the response. Use APPSTORE for App Store campaigns and MAPS for Apple Maps campaigns. Unlike the GET endpoint, the POST endpoint doesn’t filter by eligibility. The API always returns soft-blocked geos with their eligibility data included.