Campaign Targeting

Google Ads scripts lets you 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 shows how to work with campaign targets.

Ad schedules

Ad schedules let you control when your ads should run.

Retrieve

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:

const campaign = AdsApp.campaigns()
    .withCondition("campaign.name = 'My campaign'")
    .get()
    .next();

const adSchedules = campaign.targeting().adSchedules().get();
for (const adSchedule of adSchedules) {
  // 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.

Update

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);

Create

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 7 AM to 11 AM 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 six ad schedules for each day of the week, for instance, splitting up each day into six 4-hour periods is supported, but splitting up each day into 24 1-hour periods is not.

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

Remove

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:

const adSchedules = campaign.adSchedules().get();
for (const adSchedule of adSchedules) {
  adSchedule.remove();
}

Locations

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

Retrieve

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

const locations = AdsApp.targeting()
  .targetedLocations()
  .withCondition("metrics.impressions > 100")
  .forDateRange("LAST_MONTH")
  .orderBy("metrics.clicks DESC")
  .get();

for (const location of locations) {
 // Process the campaign target here.
 ...
}

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

Update

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

location.setBidModifier(1.1);

Create

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 Google Ads 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 search on location_view Report resource.

Remove

You can remove a location target using the remove method.

Proximities

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

Retrieve

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.

const proximities = AdsApp.targeting()
    .targetedProximities()
    .withCondition("metrics.impressions > 100")
    .forDateRange("LAST_MONTH")
    .orderBy("metrics.clicks DESC")
    .get();

for (const proximity of proximities) {
  ...
}

Create

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 coordinates (37.423021, -122.083739).

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

You can 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.

Remove

You can remove a proximity target using its remove method.

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:

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

Platform IDs are shared across campaigns and have predefined values as specified in the Google Ads API platforms appendix. These IDs can be useful when parsing reports. When selecting criteria directly, you can use the helper methods provided by PlatformSelector.