Contents

GeoSearchResponse

Response envelope for the geo location search endpoints.

Declaration

object GeoSearchResponse

Properties

NameTypeDescription
result[SearchEntity]

Array of SearchEntity objects matching the request criteria. Results are sorted alphabetically by displayName and deduplicated across the requested geo entities. Read-only.

paginationGeoSearchPagination

Pagination metadata including totalCount, offset, and pageSize. See GeoSearchPagination. Read-only.

Discussion

The GeoSearchResponse object is the response envelope for both GET /v1/search/geo (Search Geo Locations) and POST /v1/search/geo (Query Geo Locations). The result array contains SearchEntity objects sorted alphabetically by displayName. To determine how many pages of results are available and iterate using offset, use the pagination.totalCount value.

Each SearchEntity in the array includes id (numeric string, use as targeting value in ad group targetingDimensions), legacyId (pipe-delimited hierarchy for human reference), entity type, localized displayName, countryOrRegion, adminArea, locality, postalCode, and an eligibility object scoped to the supplySource specified in the request. If eligibility is absent from the response, no restrictions apply for that supply source.

If the request is invalid, for example an unknown supply source or a query string shorter than two characters, the API returns an HTTP error status with a structured error body rather than this response.

Example

{
  "result": [
    {
      "id": "11390462",
      "legacyId": "US|CA|San Francisco",
      "entity": "Locality",
      "displayName": "San Francisco, California, United States",
      "countryOrRegion": "US",
      "adminArea": "CA",
      "locality": "San Francisco"
    }
  ],
  "pagination": {
    "totalCount": 1,
    "offset": 0,
    "pageSize": 20
  }
}

See Also