<!--
{
  "availability" : [
    "Apple Ads Platform API: 1.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "Apple-Ads-Platform-API",
  "identifier" : "/documentation/Apple-Ads-Platform-API/Query-Location-Groups",
  "metadataVersion" : "0.1.0",
  "role" : "Web Service Endpoint",
  "symbol" : {
    "kind" : "Web Service Endpoint",
    "modules" : [
      "Apple Ads Platform API"
    ],
    "preciseIdentifier" : "rest:apple-ads-platform-api:post:location-groups-query"
  },
  "title" : "Query Location Groups"
}
-->

# Query Location Groups

Retrieve a paginated list of location groups using filters and sorting.

## Discussion

This endpoint returns a paginated list of location groups accessible to the authenticated ad account. An empty request body returns all non-deleted groups with default pagination applied.

See [`QueryFilterOperator`](/documentation/Apple-Ads-Platform-API/QueryFilterOperator) for the full set of supported comparison operators.

## Request Body

See [`QueryRequest`](/documentation/Apple-Ads-Platform-API/QueryRequest).

|Field       |Type  |Required|Description                                     |
|------------|------|--------|------------------------------------------------|
|`filters`   |array |No      |Filter conditions to narrow results.            |
|`sorting`   |array |No      |Sort order for results (field + ASC/DESC).      |
|`pagination`|object|No      |Offset and page size. Defaults apply if omitted.|

### Filterable Fields

The system combines multiple filters with AND logic. The `id` filter matches the group’s system-assigned identifier, the same `id` value returned in create and get responses, not the provider object ID. Filtering by `brandId` is the most common way to scope results to a single brand’s groups.

The system excludes soft-deleted groups from results by default. To include them, add a filter with `field: "deleted"`, `operator: "EQUALS"`, `value: true`.

> Note: There’s no dedicated filter for looking up location groups by location membership. To determine which groups contain a specific location, query location groups scoped to the location’s brand with a `brandId` filter, then inspect each returned group’s membership client-side. For `STATIC` groups, check whether the location’s `id` appears in the group’s `locationIds` array. For `DYNAMIC` groups, check whether the location satisfies the group’s `rules` criteria.

|Field                                      |Type         |Operators           |Sortable|Description                                            |
|-------------------------------------------|:-----------:|:------------------:|:------:|-------------------------------------------------------|
|`id`                                       |string       |`EQUALS`, `IN`      |Yes     |Matches the group’s system-assigned identifier.        |
|`name`                                     |string       |`EQUALS`, `CONTAINS`|Yes     |Group display name.                                    |
|`brandId`                                  |string       |`EQUALS`            |Yes     |Parent brand.                                          |
|`groupType`                                |string (enum)|`EQUALS`, `IN`      |Yes     |`STATIC` or `DYNAMIC`.                                 |
|`deleted`                                  |boolean      |`EQUALS`            |Yes     |Soft-delete flag. Defaults to excluding deleted groups.|
|`isAllLocationsGroup`                      |boolean      |`EQUALS`            |Yes     |All-locations group flag.                              |
|`eligibility.status`                       |string (enum)|`EQUALS`, `IN`      |Yes     |Eligibility status.                                    |
|`eligibility.blockedGroups.supplyPlacement`|string       |`CONTAINS_ANY`      |Yes     |Blocked placement.                                     |
|`eligibility.blockedGroups.countryOrRegion`|string       |`CONTAINS_ANY`      |Yes     |Blocked country.                                       |
|`eligibility.allowedGroups.supplyPlacement`|string       |`CONTAINS_ANY`      |Yes     |Allowed placement.                                     |
|`eligibility.allowedGroups.countryOrRegion`|string       |`CONTAINS_ANY`      |Yes     |Allowed country.                                       |

### Sorting and Pagination

You can sort results by any filterable field using the `sorting` array; see [`QuerySort`](/documentation/Apple-Ads-Platform-API/QuerySort) ([`QuerySortOrder`](/documentation/Apple-Ads-Platform-API/QuerySortOrder)) and [`QueryPagination`](/documentation/Apple-Ads-Platform-API/QueryPagination) for the request shape. The response includes a `pagination` object with `totalCount`, `offset`, and `pageSize`. Page through large result sets by incrementing `offset`.

## Payload Examples

**Filter by Brand:**

### Request

Returns all location groups belonging to a specific brand.

```json
{
 "filters": [
   {
     "field": "brandId",
     "operator": "EQUALS",
     "value": "9151314442816847872"
   }
 ],
 "pagination": {
   "offset": 0,
   "pageSize": 100
 }
}
```

### Response

```json
{
 "result": [
   {
     "id": "5764607523034238976",
     "name": "AwayFinder West Coast Stores",
     "brandId": "9151314442816847872",
     "groupType": "DYNAMIC",
     "systemStatus": "VALID",
     "groupTotal": 42,
     "isAllLocationsGroup": false,
     "eligibility": {
       "status": "ELIGIBLE"
     },
     "creationTime": "2025-02-01T09:00:00Z",
     "modificationTime": "2025-03-25T16:00:00Z"
   }
 ],
 "pagination": {
   "totalCount": 1,
   "offset": 0,
   "pageSize": 100
 }
}
```

**Filter Dynamic Groups:**

### Request

Returns only `DYNAMIC` location groups.

```json
{
 "filters": [
   {
     "field": "groupType",
     "operator": "EQUALS",
     "value": "DYNAMIC"
   }
 ]
}
```

### Response

```json
{
 "result": [
   {
     "id": "5764607523034238976",
     "name": "AwayFinder West Coast Stores",
     "brandId": "9151314442816847872",
     "groupType": "DYNAMIC",
     "systemStatus": "VALID",
     "groupTotal": 42,
     "isAllLocationsGroup": false,
     "eligibility": {
       "status": "ELIGIBLE"
     },
     "creationTime": "2025-02-01T09:00:00Z",
     "modificationTime": "2025-03-25T16:00:00Z"
   }
 ],
 "pagination": {
   "totalCount": 1,
   "offset": 0,
   "pageSize": 100
 }
}
```

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)