Examples and flow

Flow

City targeting is applied via the campaigns endpoint.
In the updated Campaign Object, the value property stores the targeted collection.

Notes for these examples

account_id = "demo-advertiser" and campaign_id = "1234"
Examples are successive (later examples presume values from earlier examples).

First - apply country targeting

POST /backstage/api/1.0/demo-advertiser/campaigns/1234/

{
   "country_targeting": {
      "type": "INCLUDE",
      "value": [
         "US"
      ]
   }
}

{
   "id": "1234",
   //...
   "country_targeting": {
      "type": "INCLUDE",
      "value": [
         "US"
      ],
      "href": null
   }
   //...
}

Then - apply city targeting (for the targeted country)

POST /backstage/api/1.0/demo-advertiser/campaigns/1234/

{
   "city_targeting": {
      "type": "INCLUDE",
      "value": [
         "229",
         "301",
         "149"
      ]
   }
}

{
   "id": "1234",
   //...
   "country_targeting": {
      "type": "INCLUDE",
      "value": [
         "US"
      ],
      "href": null
   },
   "sub_country_targeting": {
      "type": "ALL",
      "value": [],
      "href": null
   },
   "dma_country_targeting": {
      "type": "ALL",
      "value": [],
      "href": null
   },
   "region_country_targeting": {
      "type": "ALL",
      "value": [],
      "href": null
   },
   "city_targeting": {
      "type": "INCLUDE",
      "value": [
         "229",
         "301",
         "149"
      ],
      "href": null
   }
   //...
}

📘
Country and region targeting can also be applied within the same request.

🚧
When you apply city_targeting, you clear any sub_country_targeting or postal_code targeting that are present.

Remove some cities

POST /backstage/api/1.0/demo-advertiser/campaigns/1234/

{
   "city_targeting": {
      "type": "INCLUDE",
      "value": [
         "229"
      ]
   }
}

{
   "id": "1234",
   //...
   "country_targeting": {
      "type": "INCLUDE",
      "value": [
         "US"
      ],
      "href": null
   },
   "sub_country_targeting": {
      "type": "ALL",
      "value": [],
      "href": null
   },
   "dma_country_targeting": {
      "type": "ALL",
      "value": [],
      "href": null
   },
   "region_country_targeting": {
      "type": "ALL",
      "value": [],
      "href": null
   },
   "city_targeting": {
      "type": "INCLUDE",
      "value": [
         "229"
      ],
      "href": null
   }
   //...
}

📘
Patch operations are not supported. To update the collection, submit a new collection and overwrite the old one.

Remove Targeting (Target ALL)

POST /backstage/api/1.0/demo-advertiser/campaigns/1234/

{
   "city_targeting": {
      "type": "ALL"
   }
}

{
   "id": "1234",
   //...
   "country_targeting": {
      "type": "INCLUDE",
      "value": [
         "US"
      ],
      "href": null
   },
   //...
   "city_targeting": {
      "type": "ALL",
      "value": [],
      "href": null
   }
   //...
}

Updating country targeting

Any change to country targeting will clear city targeting:

POST /backstage/api/1.0/demo-advertiser/campaigns/1234/

{
   "country_targeting": {
      "type": "INCLUDE",
      "value": [
         "CA"
      ]
   }
}

{
   "id": "1234",
   //...
   "country_targeting": {
      "type": "INCLUDE",
      "value": [
         "CA"
      ],
      "href": null
   },
   "sub_country_targeting": {
      "type": "ALL",
      "value": [],
      "href": null
   },
   "dma_country_targeting": {
      "type": "ALL",
      "value": [],
      "href": null
   },
   "region_country_targeting": {
      "type": "ALL",
      "value": [],
      "href": null
   },
   "city_targeting": {
      "type": "ALL",
      "value": [],
      "href": null
   }
   //...
}

Applying sub-country targeting:

Applying sub-country targeting will clear city targeting (even if the targeted cities happen to be in the targeted region).

First - apply city targeting:

POST /backstage/api/1.0/demo-advertiser/campaigns/1234/

{
   "city_targeting": {
      "type": "INCLUDE",
      "value": [
         "229",
         "301",
         "149"
      ]
   }
}

{
   "id": "1234",
   //...
   "country_targeting": {
      "type": "INCLUDE",
      "value": [
         "US"
      ],
      "href": null
   },
   "sub_country_targeting": {
      "type": "ALL",
      "value": [],
      "href": null
   },
   //...
   "city_targeting": {
      "type": "INCLUDE",
      "value": [
         "229",
         "301",
         "149"
      ],
      "href": null
   }
   //...
}

Then - apply region targeting. Notice how city targeting is cleared:

POST /backstage/api/1.0/demo-advertiser/campaigns/1234/

{
   "region_country_targeting": {
      "type": "INCLUDE",
      "value": [
         "AZ"
      ]
   }
}

{
   "id": "1234",
   //...
   "country_targeting": {
      "type": "INCLUDE",
      "value": [
         "US"
      ],
      "href": null
   },
   "sub_country_targeting": {
      "type": "ALL",
      "value": [],
      "href": null
   },
   "dma_country_targeting": {
      "type": "ALL",
      "value": [],
      "href": null
   },
   "region_country_targeting": {
      "type": "INCLUDE",
      "value": [
         "AZ"
      ]
   }
   "city_targeting": {
      "type": "ALL",
      "value": [],
      "href": null
   }
   //...
}