Contents

SearchEntity

A single geographic location result returned by the geo search endpoints.

Declaration

object SearchEntity

Properties

NameTypeDescription
idstring

Numeric geo location identifier. Example: "11390462". Read-only.

legacyIdstring

Pipe-delimited geo identifier encoding the hierarchy. Examples: US, US|CA, US|CA|San Francisco, US|TX|78238. Read-only.

entityGeoEntityType

Geo entity type. Values: Country, AdminArea, Locality, PostalCode. Read-only.

displayNamestring

Localized display name with full hierarchy. Example: "San Francisco, California, United States". Read-only.

countryOrRegionstring

ISO 3166-1 alpha-2 country code. Read-only.

adminAreastring

State or province identifier. Present for AdminArea, Locality, and PostalCode entities. Read-only.

localitystring

City or locality name. Present for Locality entities only. Read-only.

postalCodestring

Postal code value. Present for PostalCode entities only. Read-only.

eligibilitySearchEntity.Eligibility

Supply source eligibility restrictions scoped to the supplySource specified in the request. See GeoEligibility. Absent from the response when no restrictions apply. Read-only.

Discussion

The SearchEntity object is a single geographic location result returned by the geo search endpoints. It provides multiple identifiers for the same location: id (numeric) for use as a targeting value in AdGroupTargeting, and legacyId (pipe-delimited) for human-readable reference. The entity field classifies the geographic granularity from Country down to PostalCode.

The eligibility field indicates whether you can use the location for ads on the requested supply source.

  • If eligibility is absent from the response, no restrictions apply.

  • If it contains blockedGroups, the location has one or more blocking reasons for that supply source (for example, low search volume, sparse coverage, or a hard-block condition), but the API still returns it with this data so the client can decide how to present it.

  • The API scopes eligibility to the single supplySource specified in the request.

  • The response includes only blockedGroups matching that supply source.

Example

{
  "id": "555666777",
  "legacyId": "US|CA|San Francisco|94103",
  "entity": "PostalCode",
  "displayName": "94103, San Francisco, California, United States",
  "countryOrRegion": "US",
  "adminArea": "CA",
  "postalCode": "94103",
  "eligibility": {
    "blockedGroups": [
      {
        "supplySource": ["MAPS"],
        "reasons": ["POSTAL_CODE_SPARSE"]
      }
    ]
  }
}

Topics

Dictionaries

See Also