LocationGroupCreate

The request body object for creating a new location group.

Declaration

object LocationGroupCreate

Properties

Name	Type	Description
`name` Required	string	Display name for the location group.
`brandId` Required	string	Associated brand identifier.
`adAccountId` Required	string	Ad account ID that will own this location group.
`groupType` Required	`LocationGroupType`	Type of location grouping. Values: `STATIC`, `DYNAMIC`. See groupType Details in the Discussion section.
`rules`	[`Rule`]	Array of Rule objects for `DYNAMIC` groups. Provide when `groupType` is `DYNAMIC`.
`locationIds`	[string]	Array of location IDs for `STATIC` groups. Provide when `groupType` is `STATIC`.
`description`	string	Optional description of the location group.

Discussion

The LocationGroupCreate object is the payload sent to Create Location Group.

groupType Details

The groupType you choose determines how membership is defined and maintained:

Type	How Membership Is Defined
`STATIC`	An explicit list of `locationIds` associated with the brand. Membership changes only when you update the `locationIds` array.
`DYNAMIC`	A set of `rules` evaluated against the brand’s full location catalog. Membership updates automatically as locations are added to or removed from the brand.

The STATIC groups give precise control over which locations are targeted. The DYNAMIC groups reduce maintenance when the brand’s footprint changes frequently, for example always including every location in a given city without manually updating the group. Once evaluation completes, groupTotal reflects the number of matched locations.

Two fields set at creation are locked in permanently:

Field	Notes
`brandId`	Scopes the group to a single brand. Cannot be changed after creation.
`adAccountId`	Determines which ad account owns and can access the group.

Creating a group also requires satisfying the following constraints:

Constraint	Detail
`locationIds` required for `STATIC`	At least one location ID must be provided when `groupType` is `STATIC`.
`rules` required for `DYNAMIC`	At least one rule must be provided when `groupType` is `DYNAMIC`.
`groupTotal` on creation	For `STATIC` groups, `groupTotal` equals the number of IDs supplied. For `DYNAMIC` groups, `groupTotal` is `0` until evaluation completes.
`locality` value format	A `rules` entry with `field: locality` must use the pipe-delimited format `countryOrRegion\|adminArea\|locality`, for example `"US\|New York\|Brooklyn"`, not a bare city name.

Dynamic Rule Field Values

When field is adminArea, the value must be the full English name of the administrative area, such as "Illinois" rather than "IL" or "California" rather than "CA".

Status

After creation, a DYNAMIC group’s systemStatus is initially PENDING while Apple Ads evaluates the rules. The STATIC groups are VALID immediately, since membership is an explicit list rather than something to evaluate. Wait for systemStatus: VALID before using a DYNAMIC group in ad group targeting.

Example

{
  "name": "West Coast Stores",
  "brandId": "9151314442816847872",
  "adAccountId": "293897290",
  "groupType": "DYNAMIC",
  "rules": [
    {
      "field": "adminArea",
      "operator": "IN",
      "value": [
        "California",
        "New York"
      ]
    }
  ],
  "description": "All AwayFinder retail stores on the West Coast"
}