Contents

LocationQueryResponse

The paginated response envelope returned by the Query Locations endpoint.

Declaration

object LocationQueryResponse

Properties

NameTypeDescription
result[Location]

Array of Location objects matching the supplied query filters. Empty array if no locations match. Read-only.

paginationQueryPaginationResult

Pagination metadata for the result set, including totalCount, offset, and pageSize. See QueryPaginationResult. Read-only.

errorError

Error details if the request failed. Absent on success. Read-only.

Discussion

The LocationQueryResponse object is the top-level envelope returned by Query for Locations. The result array contains Location objects matching the filters you supplied in the request body. Use pagination.totalCount together with pagination.offset and pagination.pageSize to page through large result sets.

Always filter by brandId to scope results to a specific brand. Omitting a brand filter returns locations across all brands in the ad account, which can produce very large result sets.

You can assign only locations with eligibility.status: ELIGIBLE to ad group targeting. Use the status filter to narrow to OPEN locations before referencing them in a LocationGroup.

Example

{
  "result": [
    {
      "id": "123456789",
      "brandId": "987654321",
      "status": "OPEN",
      "name": "AwayFinder Downtown",
      "categories": [
        "shopping.retail",
        "technology"
      ],
      "address": {
        "countryOrRegion": "US",
        "adminArea": "California",
        "adminAreaCode": "CA",
        "locality": "Cupertino",
        "subLocality": "De Anza",
        "subAdminArea": "Santa Clara County",
        "postalCode": "95014",
        "thoroughfare": "Infinite Loop",
        "subThoroughfare": "1",
        "fullThoroughfare": "1 Infinite Loop",
        "fullAddress": "1 Infinite Loop, Cupertino, California 95014, US"
      },
      "displayPoint": {
        "latitude": "37.3318",
        "longitude": "-122.0312"
      },
      "countryOrRegion": "US",
      "creationTime": "2025-01-10T08:00:00.000",
      "modificationTime": "2025-03-20T14:45:00.000",
      "eligibility": {
        "status": "ELIGIBLE",
        "blockedGroups": [],
        "allowedGroups": [
          {
            "supplyPlacement": [
              "SEARCH_TAB",
              "TODAY_TAB"
            ],
            "countryOrRegion": [
              "US"
            ]
          }
        ]
      }
    }
  ],
  "pagination": {
    "pageSize": 20,
    "offset": 0,
    "totalCount": 1
  }
}

See Also