---
title: Search Geo Locations
framework: Apple Ads Platform API
role: symbol
role_heading: Web Service Endpoint
platforms: [apple ads platform api 1.0+]
path: apple-ads-platform-api/searches-for-a-list-of-geo-locations
---

# 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

supplySource: 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: 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: Geo entity type to filter results. Values: Country, AdminArea, Locality, PostalCode. Example: entity=Locality. countrycode: 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: 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: Zero-based index of the first result to return. Defaults to 0. Example: offset=20. pageSize: Maximum number of results per page. Defaults to 20. Example: pageSize=50.

## Header Parameters

X-Ap-Context:

## Response Codes

200 OK: 400 Bad Request: 401 Unauthorized: 403 Forbidden: 404 Not Found: 429 Too Many Requests: 500 Internal Server Error:

## Discussion

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

- [Query Geo Locations](apple-ads-platform-api/gets-a-list-of-geo-locations.md)