--- title: Search for Geolocations framework: Apple Ads role: symbol role_heading: Web Service Endpoint platforms: [search ads 5.0+] path: apple_ads/search-for-geolocations --- # Search for Geolocations Fetches a list of geolocations for targeting. ## URL GET https://api.searchads.apple.com/api/v5/search/geo ## Query Parameters countrycode: The country or region to serve ads in. Campaigns that serve multiple countries or regions can’t use geotargeting. The query uses a countrycode value in an ISO alpha-2 country code format. GET https://api.searchads.apple.com/api/v5/search/geo?countrycode=US entity: The country, AdminArea, or Locality locations available for targeting. An AdminArea is the state or the equivalent according to its associated country. A Locality is the city or the equivalent according to its associated AdminArea. A countrycode is a mandatory parameter. GET https://api.searchads.apple.com/api/v5/search/geo?entity=AdminArea&countrycode=US GET https://api.searchads.apple.com/api/v5/search/geo?entity=Locality&countrycode=US The entity query parameter searches the displayNames for country, adminArea, and Locality in all languages. Search results in the response payload are in the preferred language according to your organization. If you don’t input a query parameter, all applicable values return in the response payload as a default. limit: The limit on the number of geolocations in the response. GET https://api.searchads.apple.com/api/v5/search/geo?limit=1000 offset: The offset pagination that limits the number of returned records. The start of each page is offset by the specified number. You can apply offset to most API calls, but not all GET endpoints support it. query: The query search pattern uses a prefix-matching algorithm. You can use spaces in search patterns. Prefixes require a minimum of three characters. If you’re sending a quoted search string, use HTML encoding. GET https://api.searchads.apple.com/api/v5/search/geo?query=%22New%20H%22 ## Response Codes 200 OK: If the call succeeds, the API returns the SearchEntity object in the response payload with an HTTP status code of 200 (OK). If unsuccessful, the HTTP status code indicates the error with details in the error message. 400 Bad Request: An invalid query or missing required parameters. 401 Unauthorized: An unauthenticated call fails to get the requested response. 403 Forbidden: Insufficient rights to the resource. 404 Not Found: The API can’t locate the resource. 429 : The API calls exceed rate-limit thresholds. See the Rate Limits subsection of Calling the Apple Ads API. 500 Internal Server Error: The Apple Ads server is temporarily down or unreachable. The request may be valid, but you need to retry it later. ## Discussion Discussion Use this endpoint to obtain App Store locations you can use to refine your target audience. Specify the criteria for a geolocation search using the geotargeting criteria CountryCriteria, AdminAreaCriteria, and LocalityCriteria, and then apply them to ad groups using Create an Ad Group and Update an Ad Group endpoints. Payload Example: Search for Geolocations ## See Also ### Search Geolocation Endpoints - [Get a List of Geo Locations](apple_ads/get-a-list-of-geo-locations.md)