Campaign Targeting

Google Ads scripts allow you to work with campaign level targeting settings in your accounts. Support is available for ad schedules, targeted and excluded locations, targeted proximities, and platforms. This guide summarizes how to work with campaign targets.

Ad Schedules

Ad Schedules allow you to customize when your ads should run.

Retrieving and updating ad schedules

You can retrieve a campaign's ad schedules using the adSchedules method of the campaign's targets. The following code snippet shows how to retrieve the list of all AdSchedule criteria for a campaign:

var campaign = AdsApp.campaigns()
    .withCondition("CampaignName = 'My campaign'")
    .get()
    .next();

var adSchedules = campaign.targeting().adSchedules().get();
while (adSchedules.hasNext()) {
  var adSchedule = adSchedules.next();

  // Process your ad schedule.
  …
}

By default, a campaign serves at all times, so you won't get any ad schedules back if you haven't set a custom ad schedule for your campaign.

Once you retrieve an ad schedule, you can modify its properties directly; for example, you could update an ad schedule's bid modifier as follows:

adSchedule.setBidModifier(1.1);

Creating ad schedules

To create a new ad schedule, you can use the addAdSchedule method of Campaign. The following code snippet creates a custom ad schedule for the campaign from 7AM to 11AM in the account's timezone, on every Saturday, with a bid modifier of 1.1.

campaign.addAdSchedule({
   dayOfWeek: "SATURDAY",
   startHour: 7,
   startMinute: 0,
   endHour: 11,
   endMinute: 0,
   bidModifier: 1.1
 });

Note: There is a limit of 6 ad schedules for each day of the week — for instance, splitting up each day into 6 4-hour-long periods is supported, but splitting up each day into 24 1-hour-long periods is not.

You can refer to our documentation for more details on what values are allowed for each parameter, and additional restrictions to keep in mind when creating ad schedules.

Removing ad schedules

You can remove an ad schedule using its remove method. To reset a campaign's custom ad scheduling, you can delete all its custom ad schedules as follows:

var adSchedules = campaign.adSchedules().get();
while (adSchedules.hasNext()) {
  var adSchedule = adSchedules.next();
  adSchedule.remove();
}

Locations

You can either target or exclude locations for your campaign using Google Ads scripts.

Retrieving and updating targeted locations

You can retrieve the list of targeted locations using the targetedLocations method of the campaign's targets. Excluded locations may be retrieved using the excludedLocations method. The following code snippet selects all targeted locations that received more than 100 impressions last month.

var locationSelector = AdsApp.targeting()
    .locations()
    .withCondition("Impressions > 100")
    .forDateRange("LAST_MONTH")
    .orderBy("Clicks DESC");

 var locationIterator = locationSelector.get();
 while (locationIterator.hasNext()) {
   var location = locationIterator.next();

   // Process the campaign target here.
   ...
 }

If you have set your campaign to serve in all countries and regions, then you will get an empty list of locations.

Once you retrieve a location, you can modify its properties directly. E.g. you could update a location's bid modifier as follows:

location.setBidModifier(1.1);

You can remove a location target using the remove method.

Creating location targets

You can create location targets on a campaign using its addLocation method. Similarly, you can exclude a location using the excludeLocation method. The following code snippet targets a campaign for the U.S. with a bid modifier of 1.15, while excluding New York City.

campaign.addLocation(2840, 1.15);     // United States
campaign.excludeLocation(1023191);    // New York city

You can refer to the AdWords API Geographical Targeting documentation for the list of IDs to use when adding location targeting. To track the performance of your location targets, you can run the Campaign Location Target Report.

Proximities

You can target a campaign to a radius (proximity) around a location using Google Ads scripts.

Retrieving and updating proximities

You can retrieve the list of targeted proximities using the targetedProximities method on the campaign's targets. The following code snippet selects all the targeted proximities that received more than 100 impressions last month.

var proximitySelector = AdsApp.targeting()
    .targetedProximities()
    .withCondition("Impressions > 100")
    .forDateRange("LAST_MONTH")
    .orderBy("Clicks DESC");

var proximityIterator = proximitySelector.get();
while (proximityIterator.hasNext()) {
  var proximity = proximityIterator.next();
  …
}

You may remove a proximity target using its remove method.

Creating proximity targets

You can create a proximity target for a campaign using its addProximity method. The following code snippet targets a campaign to 20 kilometers around the geo location (37.423021, -122.083739).

campaign.addProximity(37.423021, -122.083739, 20, "KILOMETERS");

You may also use this method to create the same proximity target with a bid modifier and address:

campaign.addProximity(37.423021, -122.083739, 20, "KILOMETERS", {
  bidModifier: 1.15,
  address: {
    streetAddress: "1600 Amphitheatre Parkway",
    cityName: "Mountain View",
    provinceName: "California",
    provinceCode: "CA",
    postalCode: "94043",
    countryCode: "US"
  }
});

Keep in mind that there is no validation to check that the address actually belongs to the given latitude and longitude. The address serves no purpose other than changing what shows up in the Campaign Management interface.

Platforms

You can retrieve the list of platforms that a campaign targets using the platforms method of the campaign's targets. Since Google Ads campaigns target all platforms (desktop, mobile, and tablet), you cannot add or remove a Platform criterion. The most common use for this targeting criterion is to set your campaign's device bid adjustment, as shown below:

campaign.targeting()
    .platforms()
    .mobile()
    .get()
    .next().
    setBidModifier(1.2);

Platform IDs are shared across campaigns and have predefined values as specified on the AdWords API Platforms appendix. These IDs may come in handy when parsing reports. When selecting criteria directly, you can use the helper methods provided by PlatformSelector.