Contents

GeoSearchPostRequest

Request body for querying geo locations.

Declaration

object GeoSearchPostRequest

Properties

NameTypeDescription
geoRequest Required[GeoRequest]

Array of GeoRequest objects. Each entry specifies a geo entity to look up. Supports (entity ID, type) or (legacyID, type) pairs. Supply exactly one of id (numeric) or legacyId (pipe-delimited) per entry along with the required entity type.

supplySource RequiredGeoSearchPostRequest.SupplySource

Supply source context for eligibility scoping. Case-insensitive. Values: APPSTORE, MAPS.

paginationGeoSearchPagination

Optional pagination parameters controlling page size and offset. See GeoSearchPagination. Defaults to offset: 0, pageSize: 20 if omitted.

Discussion

The GeoSearchPostRequest object is the request body for the POST /v1/search/geo (Query Geo Locations) endpoint. It accepts an array of GeoRequest objects, each specifying a geo entity, and returns eligibility data for all of them in a single call scoped to the specified supplySource. Use this for batch-validating a list of location IDs before setting them as ad group targeting values.

Each GeoRequest must supply exactly one of id (numeric geo_location_id) or legacyId (pipe-delimited string such as US|CA|San Francisco) plus the required entity field. The response is a GeoSearchResponse containing a result array of matching entities.

Available results and entity restrictions differ by supplySource, as shown below:

supplySource

Behavior

APPSTORE

Returns results for App Store campaigns. PostalCode entities are excluded.

MAPS

Returns results for Apple Maps campaigns. Restricted to US and CA. Country entity type excluded. PostalCode entities are available.

Example

{
  "geoRequest": [
    {
      "id": "123456789",
      "entity": "AdminArea"
    },
    {
      "legacyId": "US|CA|San Francisco",
      "entity": "Locality"
    }
  ],
  "supplySource": "APPSTORE",
  "pagination": {
    "offset": 0,
    "pageSize": 20
  }
}

Topics

Type Aliases

See Also