Contents

Search Geo Locations

Search for geographic locations for use in ad group geo targeting.

URL

GET https://api.ads.apple.com/v1/search/geo

Query Parameters

NameTypeDescription
supplySource RequiredSearchSupplySourceType

Supply source context for eligibility evaluation. Case-insensitive. Values: APPSTORE, MAPS. Controls which entity types are available. APPSTORE excludes the PostalCode entity, which is a MAPS-level geo. MAPS excludes the Country entity and restricts results to the US and Canada. Example: supplySource=APPSTORE. Omitting it returns a 400 error.

query Optionalstring

Search string. Minimum 2 characters. The API rejects shorter values with error code MIN_QUERY_LENGTH. Use \* to return all matching geos, or omit the parameter for the same result. Example: query=San Francisco.

entity OptionalGeoEntityType

Geo entity type to filter results. Values: Country, AdminArea, Locality, PostalCode. Example: entity=Locality.

countrycode Optionalstring

ISO 3166-1 alpha-2 country code to scope results. When entity is AdminArea, Locality, or PostalCode and countrycode is omitted, defaults to US. Example: countrycode=US.

eligible Optionalboolean

Controls soft-block filtering. When false (default), the API includes soft-blocked geos (low search volume, sparse coverage) with eligibility data. When true, the API excludes them from results entirely. Example: eligible=true.

offset Optionalint32

Zero-based index of the first result to return. Defaults to 0. Example: offset=20.

pageSize Optionalint32

Maximum number of results per page. Defaults to 20. Example: pageSize=50.

Header Parameters

NameTypeDescription
X-Ap-Context Requiredstring

Response Codes

StatusReasonTypeDescription
200OK
Content-Type: application/json
GeoSearchResponse
400Bad Request
Content-Type: application/json
Error
401Unauthorized
Content-Type: application/json
Error
403Forbidden
Content-Type: application/json
Error
404Not Found
Content-Type: application/json
Error
429Too Many Requests
Content-Type: application/json
Error
500Internal Server Error
Content-Type: application/json
Error

Discussion

This endpoint returns a list of geographic locations matching the search criteria. To discover valid geo location identifiers by name before assigning targets to an ad group, use this endpoint. For ID-based lookup of known locations, use the POST endpoint POST /v1/search/geo (Query Geo Locations) instead.

The API sorts results alphabetically by displayName and paginates them. Each result includes a legacyId, which is a pipe-delimited string encoding the full geographic hierarchy (such as US|CA|San Francisco), and an eligibility object scoped to the requested supplySource.

Every request requires supplySource, which determines which entity types are available. See the supplySource parameter below for details.

Payload Examples

See Also