Query for Locations

Retrieve a paginated list of business locations using filters and sorting.

URL

POST https://api.ads.apple.com/v1/locations/query

Header Parameters

Name	Type	Description
`X-Ap-Context` Required	string

Response Codes

Status	Reason	Type
200	OK Content-Type: application/json	`LocationQueryResponse`
400	Bad Request Content-Type: application/json	`LocationQueryResponse`
401	Unauthorized Content-Type: application/json	`Error`
403	Forbidden Content-Type: application/json	`Error`
404	Not Found Content-Type: application/json	`Error`
429	Too Many Requests Content-Type: application/json	`Error`
500	Internal Server Error Content-Type: application/json	`Error`

Discussion

This endpoint retrieves a paginated list of physical business locations associated with a brand. Locations are the physical stores or venues that BUSINESS_BRAND campaigns advertise. When creating ad groups for these campaigns, use location id values from this endpoint to scope delivery to specific stores or venues.

Locations are registered entities that represent physical places of business, such as retail stores, restaurants, and service centers. An empty request body returns all locations with default pagination. Filter by brandId to retrieve locations for a specific brand.

See QueryFilterOperator for the full set of supported comparison operators.

Filterable Fields

Field	Type	Operators	Sortable	Description
`brandId`	string	`EQUALS`		Filter by the brand the location belongs to.
`name`	string	`EQUALS`, `STARTS_WITH`	Yes	Filter by location display name or prefix.
`status`	string (enum)	`EQUALS`, `IN`		Filter by operational status: `OPEN`, `OPENING_SOON`, `CLOSED`, `MOVED`, `TEMPORARILY_CLOSED`.
`address.countryOrRegion`	string	`EQUALS`, `IN`		Filter by ISO 3166-1 alpha-2 country or region code.
`address.adminArea`	string	`EQUALS`, `IN`		Filter by state or province name.
`address.locality`	string	`EQUALS`, `STARTS_WITH`		Filter by city or town name.
`address.postalCode`	string	`EQUALS`, `IN`		Filter by postal or ZIP code.
`eligibility.status`	string (enum)	`EQUALS`, `IN`		Filter by eligibility status: `ELIGIBLE`, `INELIGIBLE`, `LIMITED`, `PENDING`, `UNDEFINED`.

The request body is a QueryRequest composed of QueryFilter conditions and QuerySort directives (QuerySortOrder), controlled by QueryPagination.

Request Body

See QueryRequest.

Each location record returned by this endpoint includes the following fields:

Field	Type	Description
`id`	string	Unique identifier for the location. Used in ad group targeting.
`name`	string	Display name of the location.
`address.countryOrRegion`	string	ISO 3166-1 alpha-2 country code.
`address.adminArea`	string	State or province name.
`address.locality`	string	City or town name.
`address.postalCode`	string	Postal or ZIP code.
`status`	string	Operational status: `OPEN`, `OPENING_SOON`, `CLOSED`, `MOVED`, `TEMPORARILY_CLOSED`.
`eligibility`	object	System-managed eligibility for ad targeting.

A few limitations apply to querying locations and using the results for targeting:

Constraint	Detail
Filter by `brandId`	Omitting this returns locations across all brands, which may be a large result set.
Location IDs in targeting	Add location `id` values to a `LocationGroup`, then reference the group via `targeting.locationGroup` in ad group targeting.
Open locations only	Only locations with `status: OPEN` are typically eligible for ad group targeting.