Location
The brand location object.
Declaration
object LocationProperties
| Name | Type | Description |
|---|---|---|
id Required | string | ID of the location. Read-only. |
brandId | string | Associated brand identifier. Read-only. |
status | string | Possible values: |
name | string | The location’s display name. Read-only. |
categories | [string] | Category identifiers (first is primary). Read-only. |
address | Location.Address | Postal address of the location, sourced from Apple Maps. See Location.Address for the full subfield breakdown. Read-only. |
displayPoint | Location.DisplayPoint | Geographic coordinates used for map placement rendering. Read-only. |
countryOrRegion | string | ISO 3166-1 alpha-2 country code, for example, |
creationTime | date-time | ISO-8601 timestamp when the location record was created. Read-only. |
modificationTime | date-time | ISO-8601 timestamp of the last modification to the location record. Read-only. |
eligibility | Eligibility | Eligibility details for this location. See Eligibility. Read-only. |
Discussion
The Location object represents a physical brand location sourced from Apple Maps. An id identifies each location, and each location belongs to a brandId. The status field reflects the operational state of the location. Typically, brands campaigns target only OPEN locations.
The API always returns the eligibility field, which describes whether the location can be promoted through ads. Use categories to understand the business type, and address.countryOrRegion to verify country or region targeting compatibility. The address and displayPoint provide the geographic data used for map placement rendering.
Example
{
"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",
"unit": "Suite 100",
"floor": "1",
"building": "Main Building"
},
"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"
]
}
]
}
}