Ads Overview

This guide provides an overview of the various ad types and features available in the API, from the perspective of a typical use case.

Scenario

Let's say you're the proud proprietor of the Intergalactic Guitar Shop and you want to launch an advertising campaign to bring in new customers. The following sections describe the different ad types and features you could use to achieve this goal.

Where do you want your ads to appear?

AdWords ads can appear on two networks:

• The Search network, which includes Google search result pages, other Google sites like Maps and Shopping, and partnering search sites.
• The Display network, which includes Google sites like YouTube, Blogger, and Gmail, plus thousands of partnering websites across the internet.

Let's assume you want to advertise on both networks. However, you don't want to separately manage a Search campaign and a Display campaign, so you create a Search Network with Display Select campaign with a single ad group.

See the AddCampaigns code example in your client library's basic operations examples folder for details.

Java

Add campaigns

C#

Add campaigns

PHP

Add campaigns

Perl

Add campaigns

Python

Add campaigns

Ruby

Add campaigns

What type of ad do you want?

Now that you know where your ads will appear, it's time to choose the ad type that best meets your requirements. The AdWords API offers the following ad types:

Type	Search	Display	Description
ExpandedTextAd	Yes	Yes	New standard for AdWords text ads. Includes two headlines, a description of your product or service, navigational breadcrumbs, and a generated visible URL.
ProductAd	Yes	No	A product ad (called a shopping ad in the AdWords UI) is based on product data of a Shopping campaign's associated Merchant Center account.
DynamicSearchAd	Yes	No	Dynamically generated search ads based on the content of a web site.
ResponsiveDisplayAd	No	Yes	Contains a marketing image, a short and long headline, a description, and an optional advertiser name and logo.
GmailAd	No	Yes	An ad for a Gmail campaign.
CallOnlyAd	No	Yes	An ad for a Click to Call Only campaign.
ImageAd	Yes^1	Yes	An ad that includes a graphic to promote your business.
TemplateAd	Yes^2	Yes^2	An ad based on a predefined template.

¹ An ImageAd on the Search Network will appear only on websites of Google search partners, not on Google Search.

² See the list of TemplateAd templates and the template ads guide for more information, including which networks each template ID supports.

Note: Some AdWords ad types can't be created in the API. See the complete list of AdWords ad types for details.

For this scenario, let's assume you start with the most common type of ad, an ExpandedTextAd, and that you'll use the same ExpandedTextAd to advertise on both the Search and Display networks.

Expanded text ad setup

An ExpandedTextAd is a relatively simple object — you just need to specify the following attributes:

• HeadlinePart1 - First part of the headline.
• HeadlinePart2 - Second part of the headline.
• Description - The descriptive text of the ad.
• FinalUrls - The URLs of the page on your website that people reach when they click your ad.

Check out the AddExpandedTextAds example in your client library's basic operations examples folder for a complete example.

Java

Add expanded text ads

C#

Add expanded text ads

PHP

Add expanded text ads

Perl

Add expanded text ads

Python

Add expanded text ads

Ruby

Add expanded text ads

Note: Ad objects are immutable in AdWords. To modify an Ad, submit a REMOVE operation with the existing Ad and an ADD operation for a new Ad with the modified attributes. This creates a new Ad ID, so stats for the original Ad and the new Ad will appear under separate IDs in reports.

Gmail ad setup

A GmailAd can only be created in a campaign that has the advertisingChannelType set to DISPLAY and the advertisingChannelSubType set to DISPLAY_GMAIL_AD. There are a few things to keep in mind while creating a GmailAd:

• Either the marketingImage or the productVideoList must be populated.
• If you decide to use the productVideoList, then the videos need to already exist in the AdWords system. They can be uploaded either through the AdWords UI or through AdWords Scripts. The IDs can then be retrieved through the MediaService.

Check out the AddGmailAds example in your client library's advanced operations examples folder for a complete example.

Java

Add Gmail ads

C#

Add Gmail ads

PHP

Add Gmail ads

Perl

Add Gmail ads

Python

Add Gmail ads

Ruby

Add Gmail ads

Adding ad extensions

You can start with a basic ExpandedTextAd in your ad group, but you may have noticed other ads on the Search and Display networks that contain additional information, links, and action buttons.

This additional information comes from ad extensions. Most ad extensions are managed via feed services in the AdWords API. Using ad extensions, you can improve your ads with:

• Sitelinks that show additional links to specific pages on your website.
• Location extensions that show your business address, phone number, a map marker with your ad text, and on mobile, a link with directions to your business.
• App extensions that show a link to your mobile or tablet app.
• Callout extensions that show additional detailed information about your business, including products and services you offer.
• Review extensions that show a positive review, award, or third-party ranking in an additional line of text beneath your ad on Google Search.

Adding sitelink extensions

As the owner of the Intergalactic Guitar Shop, you want people to know that the shop:

• Offers repair services.
• Carries both acoustic and electric guitars.
• Provides guitar lessons.

This information is a great fit for sitelink extensions!

To set up sitelink extensions, see the instructions in the Extension Setting Services guide, which includes a link to a complete code example for each client library.

Adding location extensions

Your ad is up and showing links to various areas of your site, but you want users to find your store's location easily, especially if they're viewing your ad on a mobile device.

If you already entered this information in your Google My Business account, then you're in luck--all you need to do is link your Google My Business account to your AdWords accounts, and AdWords will display the location in your ads.

See the Location Extensions guide for step-by-step instructions and code examples.

More ad extensions

Now that you've set up sitelinks and location extensions for your campaign, adding other extensions such as app, callout, or review extensions is very similar. The only difference is the type of ExtensionFeedItem used with the extension setting services.

The Extension Setting Services guide includes examples for each extension type.

Ad rotation

If you have multiple ads within an ad group, your ads will rotate because no more than one ad from your account can show at a time. You can use ad rotation setting to specify how often you'd like the ads in your ad group to be served relative to one another.

There are two settings for ad rotation:

• Optimize: The optimize setting prioritizes ads that are expected to perform better than other ads within an ad group. This is the default setting.
• Rotate indefinitely: The rotate indefinitely setting delivers your ads more evenly into the ad auction, but does so for an indefinite amount of time and does not optimize.

Ad rotation settings are specified at the ad group level, using the ad group's adGroupAdRotationMode property. You can remove the ad rotation setting by passing an AdGroupAdRotationMode with the adRotationMode set to null.

Ad scheduling

Like many things in life, advertising is all about timing. A lot of businesses have special advertising needs during certain times of day, and they want to target customers at specific times. Incorporating ad scheduling in your campaigns causes your ads to display at the time they're most useful, resulting in more focused targeting and higher returns.

Ad scheduling allows you to decide programmatically when to run your ads, without requiring you to manually enable and disable them.

Scheduling works at the campaign level, so it applies to all active ad groups and ads inside it. This is handled by CampaignCriterionService and one of its criterion types, AdSchedule.

Each AdSchedule criterion allows you to define a number of properties such as day of week, start and end times, and a bid modifier (formerly handled through the bid_multiplier of the CampaignTargetService). With bid modifiers you can increase or decrease your bids at specified times.

Keep in mind that if a campaign doesn't have an AdSchedule, ads will run at all times. If you add an AdSchedule, ads will show only at the specified times. Thus, there are two ways to configure ads to run at all times:

1. Use no AdSchedule targets.
2. Use scheduled targets for all day, every day.

Keep these two options in mind when checking if a campaign is configured to run at all times.

To modify an ad schedule, you submit deltas that add or remove hours/days rather than a whole new set of times, as you may have done in the past.

Note: An AdSchedule can have no more than six intervals in a day.

Code examples

To make sure the ads run mostly during opening hours, set the start time for the ads to a bit before opening, and the end time a bit before closing:

Java

// Closed on Sunday, so don't configure an AdSchedule for Sunday.
List<DayOfWeek> mondayThroughSaturday =
    Arrays.asList(
        DayOfWeek.MONDAY,
        DayOfWeek.TUESDAY,
        DayOfWeek.WEDNESDAY,
        DayOfWeek.THURSDAY,
        DayOfWeek.FRIDAY,
        DayOfWeek.SATURDAY);

// Creates an operation to add an AdSchedule for each day of the week in the list.
List<CampaignCriterionOperation> operations = new ArrayList<>();
for (DayOfWeek dayOfWeek : mondayThroughSaturday) {
  AdSchedule schedule = new AdSchedule();
  schedule.setDayOfWeek(dayOfWeek);
  // Start at 8:45 am...
  schedule.setStartHour(8);
  schedule.setStartMinute(MinuteOfHour.FORTY_FIVE);
  // ... and end at 7:45 pm
  schedule.setEndHour(19);
  schedule.setEndMinute(MinuteOfHour.FORTY_FIVE);
  CampaignCriterionOperation operation = new CampaignCriterionOperation();
  CampaignCriterion campaignCriterion = new CampaignCriterion();

  campaignCriterion.setCampaignId(campaignId);
  campaignCriterion.setCriterion(schedule);
  // Run at normal bid rates
  campaignCriterion.setBidModifier(1.0);
  operation.setOperand(campaignCriterion);
  operation.setOperator(Operator.ADD);
  operations.add(operation);
}

CampaignCriterionReturnValue result =
    campaignCriterionService.mutate(
        operations.toArray(new CampaignCriterionOperation[operations.size()]));

CSharp

// Closed on Sunday, so don't configure an AdSchedule for Sunday.
List<DayOfWeek> mondayThroughSaturday = new List<DayOfWeek>() {
  DayOfWeek.MONDAY,
  DayOfWeek.TUESDAY,
  DayOfWeek.WEDNESDAY,
  DayOfWeek.THURSDAY,
  DayOfWeek.FRIDAY,
  DayOfWeek.SATURDAY
};

// Creates an operation to add an AdSchedule for each day of the week in the list.
List<CampaignCriterionOperation> operations = new List<CampaignCriterionOperation>();
foreach (DayOfWeek dayOfWeek in mondayThroughSaturday) {
  AdSchedule schedule = new AdSchedule();
  schedule.dayOfWeek = dayOfWeek;
  // Start at 8:45 am...
  schedule.startHour = 8;
  schedule.startMinute = MinuteOfHour.FORTY_FIVE;
  // ... and end at 7:45 pm
  schedule.endHour = 19;
  schedule.endMinute = MinuteOfHour.FORTY_FIVE;
  CampaignCriterionOperation operation = new CampaignCriterionOperation();
  CampaignCriterion campaignCriterion = new CampaignCriterion();

  campaignCriterion.campaignId = campaignId;
  campaignCriterion.criterion = schedule;
  // Run at normal bid rates
  campaignCriterion.bidModifier = 1.0;
  operation.operand = campaignCriterion;
  operation.@operator = Operator.ADD;
  operations.Add(operation);
}

CampaignCriterionReturnValue result =
    campaignCriterionService.mutate(operations.ToArray());

Python

# Closed on Sunday, so don't configure an AdSchedule for Sunday.
monday_through_saturday = [
    'MONDAY', 'TUESDAY', 'WEDNESDAY', 'THURSDAY', 'FRIDAY', 'SATURDAY'
]

# Creates an operation to add an AdSchedule for each day of the week in the
# list.
operations = [{
    'operator': 'ADD',
    'operand': {
        'campaignId': campaign_id,
        'criterion': {
            'xsi_type': 'AdSchedule',
            'dayOfWeek': day,
            # Start at 8:45 A.M.
            'startHour': 8,
            'startMinute': 'FORTY_FIVE',
            # End at 7:45 P.M.
            'endHour': 19,
            'endMinute': 'FORTY_FIVE',
        },
        # Run at normal bid rates.
        'bidModifier': 1.0
    }
} for day in monday_through_saturday]

result = campaign_criterion_service.mutate(operations)

PHP

// Closed on Sunday, so don't configure an AdSchedule for Sunday.
$mondayThroughSaturday = [
    DayOfWeek::MONDAY,
    DayOfWeek::TUESDAY,
    DayOfWeek::WEDNESDAY,
    DayOfWeek::THURSDAY,
    DayOfWeek::FRIDAY,
    DayOfWeek::SATURDAY
];

// Creates an operation to add an AdSchedule for each day of the week in the
// list.
$operations = [];
foreach ($mondayThroughSaturday as $dayOfWeek) {
    $schedule = new AdSchedule();
    $schedule->setDayOfWeek($dayOfWeek);
    // Start at 8:45 am...
    $schedule->setStartHour(8);
    $schedule->setStartMinute(MinuteOfHour::FORTY_FIVE);
    // ... and end at 7:45 pm
    $schedule->setEndHour(19);
    $schedule->setEndMinute(MinuteOfHour::FORTY_FIVE);

    $campaignCriterion = new CampaignCriterion();
    $campaignCriterion->setCampaignId($campaignId);
    $campaignCriterion->setCriterion($schedule);
    // Run at normal bid rates
    $campaignCriterion->setBidModifier(1.0);

    $operation = new CampaignCriterionOperation();
    $operation->setOperand($campaignCriterion);
    $operation->setOperator(Operator::ADD);
    $operations[] = $operation;
}

$result = $campaignCriterionService->mutate($operations);

Perl

# Closed on Sunday, so don't configure an AdSchedule for Sunday.
my @monday_through_saturday =
  ('MONDAY', 'TUESDAY', 'WEDNESDAY', 'THURSDAY', 'FRIDAY', 'SATURDAY');

# Creates an operation to add an AdSchedule for each day of the week in the list.
my @operations = ();
foreach my $day_of_week (@monday_through_saturday) {
  my $schedule = Google::Ads::AdWords::v201802::AdSchedule->new({
    dayOfWeek => $day_of_week,
    # Start at 8:45 am...
    startHour   => '8',
    startMinute => 'FORTY_FIVE',
    # ... and end at 7:45 pm
    endHour   => '19',
    endMinute => 'FORTY_FIVE'
  });

  my $campaign_criterion =
    Google::Ads::AdWords::v201802::CampaignCriterion->new({
      campaignId => $campaign_id,
      criterion  => $schedule,
      # Run at normal bid rates
      bidModifier => '1.0'
    });

  my $operation =
    Google::Ads::AdWords::v201802::CampaignCriterionOperation->new({
      operand  => $campaign_criterion,
      operator => 'ADD'
    });

  push @operations, $operation;
}

my $result =
  $client->CampaignCriterionService()->mutate({operations => \@operations});

Ruby

# Closed on Sunday, so don't configure an AdSchedule for Sunday.
monday_through_saturday = [
  'MONDAY',
  'TUESDAY',
  'WEDNESDAY',
  'THURSDAY',
  'FRIDAY',
  'SATURDAY'
]

# Creates an operation to add an AdSchedule for each day of the week in the
# list.
operations = monday_through_saturday.map do |day_of_week|
  schedule = {
    :xsi_type => 'AdSchedule',
    :day_of_week => day_of_week,
    # Start at 8:45 AM...
    :start_hour => 8,
    :start_minute => 'FORTY_FIVE',
    # ...and end at 7:45 PM.
    :end_hour => 19,
    :end_minute => 'FORTY_FIVE'
  }

  campaign_criterion = {
    :campaign_id => campaign_id,
    :criterion => schedule,
    :bid_modifier => 1.0
  }

  operation = {
    :operand => campaign_criterion,
    :operator => 'ADD'
  }

  next operation
end

result = campaign_criterion_srv.mutate(operations)

VB.NET

' Closed on Sunday, so don't configure an AdSchedule for Sunday.
Dim mondayThroughSaturday As DayOfWeek() = {
  DayOfWeek.MONDAY,
  DayOfWeek.TUESDAY,
  DayOfWeek.WEDNESDAY,
  DayOfWeek.THURSDAY,
  DayOfWeek.FRIDAY,
  DayOfWeek.SATURDAY
}

' Creates an operation to add an AdSchedule for each day of the week in the list.
Dim operations As New List(Of CampaignCriterionOperation)()
For Each dayOfWeek As DayOfWeek In mondayThroughSaturday
  Dim schedule As New AdSchedule()
  schedule.dayOfWeek = dayOfWeek
  ' Start at 8:45 am...
  schedule.startHour = 8
  schedule.startMinute = MinuteOfHour.FORTY_FIVE
  ' ... And end at 7:45 pm
  schedule.endHour = 19
  schedule.endMinute = MinuteOfHour.FORTY_FIVE
  Dim operation As New CampaignCriterionOperation()
  Dim campaignCriterion As New CampaignCriterion()

  campaignCriterion.campaignId = campaignId
  campaignCriterion.criterion = schedule
  ' Run at normal bid rates
  campaignCriterion.bidModifier = 1.0
  operation.operand = campaignCriterion
  operation.operator = [Operator].ADD
  operations.Add(operation)
Next

Dim result As CampaignCriterionReturnValue =
    campaignCriterionService.mutate(operations.ToArray())

To give customers fair warning about a special lunchtime deal on Mondays, start advertising early in the morning and increase significantly during the promotion hours:

Java

List<CampaignCriterionOperation> operations = new ArrayList<>();

// Create operations to remove any existing ad schedules for Monday. Ad schedules cannot
// overlap.
for (Long existingCriterionId : existingCriteriaIds) {
  CampaignCriterion campaignCriterion = new CampaignCriterion();
  campaignCriterion.setCampaignId(campaignId);
  AdSchedule adSchedule = new AdSchedule();
  adSchedule.setId(existingCriterionId);
  campaignCriterion.setCriterion(adSchedule);

  CampaignCriterionOperation removeOperation = new CampaignCriterionOperation();
  removeOperation.setOperand(campaignCriterion);
  removeOperation.setOperator(Operator.REMOVE);

  operations.add(removeOperation);
}

// Create a schedule for 8:00 AM to 12:00 PM (noon) with no change to bids.
AdSchedule early = new AdSchedule();
early.setDayOfWeek(DayOfWeek.MONDAY);
early.setStartHour(8);
early.setStartMinute(MinuteOfHour.ZERO);
early.setEndHour(12);
early.setEndMinute(MinuteOfHour.ZERO);

CampaignCriterion campaignCriterionEarly = new CampaignCriterion();
// Run at normal bid rates.
campaignCriterionEarly.setBidModifier(1.0);
campaignCriterionEarly.setCampaignId(campaignId);
campaignCriterionEarly.setCriterion(early);

// Create a schedule for 12:00 PM (noon) to 2:00 PM with bids doubled.
AdSchedule peak = new AdSchedule();
peak.setDayOfWeek(DayOfWeek.MONDAY);
peak.setStartHour(12);
peak.setStartMinute(MinuteOfHour.ZERO);
peak.setEndHour(14);
peak.setEndMinute(MinuteOfHour.ZERO);

CampaignCriterion campaignCriterionPeak = new CampaignCriterion();
// Double the bid.
campaignCriterionPeak.setBidModifier(2.0);
campaignCriterionPeak.setCampaignId(campaignId);
campaignCriterionPeak.setCriterion(peak);

// Create operations to add the new schedules.
CampaignCriterionOperation operationEarly = new CampaignCriterionOperation();
operationEarly.setOperand(campaignCriterionEarly);
operationEarly.setOperator(Operator.ADD);
operations.add(operationEarly);

CampaignCriterionOperation operationPeak = new CampaignCriterionOperation();
operationPeak.setOperand(campaignCriterionPeak);
operationPeak.setOperator(Operator.ADD);
operations.add(operationPeak);

campaignCriterionService.mutate(
    operations.toArray(new CampaignCriterionOperation[operations.size()]));

CSharp

List<CampaignCriterionOperation> operations = new List<CampaignCriterionOperation>();

// Create operations to remove any existing ad schedules for Monday. Ad schedules cannot
// overlap.
foreach (long existingCriterionId in existingCriteriaIds) {
  CampaignCriterion campaignCriterion = new CampaignCriterion();
  campaignCriterion.campaignId = campaignId;
  AdSchedule adSchedule = new AdSchedule();
  adSchedule.id = existingCriterionId;
  campaignCriterion.criterion = adSchedule;

  CampaignCriterionOperation removeOperation = new CampaignCriterionOperation();
  removeOperation.operand = campaignCriterion;
  removeOperation.@operator = Operator.REMOVE;

  operations.Add(removeOperation);
}

// Create a schedule for 8:00 AM to 12:00 PM (noon) with no change to bids.
AdSchedule early = new AdSchedule();
early.dayOfWeek = DayOfWeek.MONDAY;
early.startHour = 8;
early.startMinute = MinuteOfHour.ZERO;
early.endHour = 12;
early.endMinute = MinuteOfHour.ZERO;

CampaignCriterion campaignCriterionEarly = new CampaignCriterion();
// Run at normal bid rates.
campaignCriterionEarly.bidModifier = 1.0;
campaignCriterionEarly.campaignId = campaignId;
campaignCriterionEarly.criterion = early;

// Create a schedule for 12:00 PM (noon) to 2:00 PM with bids doubled.
AdSchedule peak = new AdSchedule();
peak.dayOfWeek = DayOfWeek.MONDAY;
peak.startHour = 12;
peak.startMinute = MinuteOfHour.ZERO;
peak.endHour = 14;
peak.endMinute = MinuteOfHour.ZERO;

CampaignCriterion campaignCriterionPeak = new CampaignCriterion();
// Double the bid.
campaignCriterionPeak.bidModifier = 2.0;
campaignCriterionPeak.campaignId = campaignId;
campaignCriterionPeak.criterion = peak;

// Create operations to add the new schedules.
CampaignCriterionOperation operationEarly = new CampaignCriterionOperation();
operationEarly.operand = campaignCriterionEarly;
operationEarly.@operator = Operator.ADD;
operations.Add(operationEarly);

CampaignCriterionOperation operationPeak = new CampaignCriterionOperation();
operationPeak.operand = campaignCriterionPeak;
operationPeak.@operator = Operator.ADD;
operations.Add(operationPeak);

campaignCriterionService.mutate(operations.ToArray());

Python

# Create operations to remove existing ad schedules for Monday. Ad schedules
# can't overlap.
operations = [{
    'operator': 'REMOVE',
    'operand': {
        'campaignId': campaign_id,
        'criterion': {
            'id': criteria_id
        }
    }
} for criteria_id in existing_criteria_ids]

# Create a schedule for 8:00 A.M. to 12:00 P.M. (noon) with no change to bids.
operations.append({
    'operator': 'ADD',
    'operand': {
        'campaignId': campaign_id,
        'criterion': {
            'xsi_type': 'AdSchedule',
            'dayOfWeek': 'MONDAY',
            'startHour': 8,
            'startMinute': 'ZERO',
            'endHour': 12,
            'endMinute': 'ZERO'
        },
        # Run at normal bid rates.
        'bidModifier': 1.0
    }
})

# Create a schedule for 12:00 P.M. (noon) to 2 P.M. with bids doubled.
operations.append({
    'operator': 'ADD',
    'operand': {
        'campaignId': campaign_id,
        'criterion': {
            'xsi_type': 'AdSchedule',
            'dayOfWeek': 'MONDAY',
            'startHour': 12,
            'startMinute': 'ZERO',
            'endHour': 14,
            'endMinute': 'ZERO'
        },
        # Double the bid.
        'bidModifier': 2.0
    }
})

campaign_criterion_service.mutate(operations)

PHP

$operations = [];

// Create operations to remove any existing ad schedules for Monday. Ad
// schedules cannot overlap.
foreach ($existingCriteriaIds as $existingCriterionId) {
    $campaignCriterion = new CampaignCriterion();
    $campaignCriterion->setCampaignId($campaignId);
    $adSchedule = new AdSchedule();
    $adSchedule->setId($existingCriterionId);
    $campaignCriterion->setCriterion($adSchedule);

    $removeOperation = new CampaignCriterionOperation();
    $removeOperation->setOperand($campaignCriterion);
    $removeOperation->setOperator(Operator::REMOVE);

    $operations[] = $removeOperation;
}

// Create a schedule for 8:00 AM to 12:00 PM (noon) with no change to bids.
$early = new AdSchedule();
$early->setDayOfWeek(DayOfWeek::MONDAY);
$early->setStartHour(8);
$early->setStartMinute(MinuteOfHour::ZERO);
$early->setEndHour(12);
$early->setEndMinute(MinuteOfHour::ZERO);

$campaignCriterionEarly = new CampaignCriterion();
// Run at normal bid rates.
$campaignCriterionEarly->setBidModifier(1.0);
$campaignCriterionEarly->setCampaignId($campaignId);
$campaignCriterionEarly->setCriterion($early);

// Create a schedule for 12:00 PM (noon) to 2:00 PM with bids doubled.
$peak = new AdSchedule();
$peak->setDayOfWeek(DayOfWeek::MONDAY);
$peak->setStartHour(12);
$peak->setStartMinute(MinuteOfHour::ZERO);
$peak->setEndHour(14);
$peak->setEndMinute(MinuteOfHour::ZERO);

$campaignCriterionPeak = new CampaignCriterion();
// Double the bid.
$campaignCriterionPeak->setBidModifier(2.0);
$campaignCriterionPeak->setCampaignId($campaignId);
$campaignCriterionPeak->setCriterion($peak);

// Create operations to add the new schedules.
$operationEarly = new CampaignCriterionOperation();
$operationEarly->setOperand($campaignCriterionEarly);
$operationEarly->setOperator(Operator::ADD);
$operations[] = $operationEarly;

$operationPeak = new CampaignCriterionOperation();
$operationPeak->setOperand($campaignCriterionPeak);
$operationPeak->setOperator(Operator::ADD);
$operations[] = $operationPeak;

$campaignCriterionService->mutate($operations);

Perl

my @operations = ();

# Create operations to remove any existing ad schedules for Monday. Ad
# schedules cannot overlap.
for my $existing_criterion_id (@{$existing_criterion_ids}) {
  my $campaign_criterion =
    Google::Ads::AdWords::v201802::CampaignCriterion->new({
      campaignId => $campaign_id,
      criterion  => Google::Ads::AdWords::v201802::AdSchedule->new({
          id => $existing_criterion_id
        })});

  my $remove_operation =
    Google::Ads::AdWords::v201802::CampaignCriterionOperation->new({
      operand  => $campaign_criterion,
      operator => 'REMOVE'
    });

  push @operations, $remove_operation;
}

# Create a schedule for 8:00 AM to 12:00 PM (noon) with no change to bids.
my $early = Google::Ads::AdWords::v201802::AdSchedule->new({
  dayOfWeek   => 'MONDAY',
  startHour   => '8',
  startMinute => 'ZERO',
  endHour     => '12',
  endMinute   => 'ZERO'
});

my $campaign_criterion_early =
  Google::Ads::AdWords::v201802::CampaignCriterion->new({
    campaignId => $campaign_id,
    criterion  => $early,
    # Run at normal bid rates
    bidModifier => '1.0'
  });

# Create a schedule for 12:00 PM (noon) to 2:00 PM with bids doubled.
my $peak = Google::Ads::AdWords::v201802::AdSchedule->new({
  dayOfWeek   => 'MONDAY',
  startHour   => '12',
  startMinute => 'ZERO',
  endHour     => '14',
  endMinute   => 'ZERO'
});

my $campaign_criterion_peak =
  Google::Ads::AdWords::v201802::CampaignCriterion->new({
    campaignId => $campaign_id,
    criterion  => $peak,
    # Double the bid.
    bidModifier => '2.0'
  });

# Create operations to add the new schedules.
my $operation_early =
  Google::Ads::AdWords::v201802::CampaignCriterionOperation->new({
    operand  => $campaign_criterion_early,
    operator => 'ADD'
  });
push @operations, $operation_early;

my $operation_peak =
  Google::Ads::AdWords::v201802::CampaignCriterionOperation->new({
    operand  => $campaign_criterion_peak,
    operator => 'ADD'
  });
push @operations, $operation_peak;

$client->CampaignCriterionService()->mutate({operations => \@operations});

Ruby

operations = []

# Create operations to remove any existing ad schedules for Monday. Ad
# schedules cannot overlap.
existing_criteria_ids.each do |existing_criterion_id|
  operations << {
    :operator => 'REMOVE',
    :operand => {
      :campaign_id => campaign_id,
      :criterion => {
        :id => existing_criterion_id
      }
    }
  }
end

# Create a schedule for 8:00 AM to 12:00 PM (noon) with no change to bids.
early = {
  :xsi_type => 'AdSchedule',
  :day_of_week => 'MONDAY',
  :start_hour => 8,
  :start_minute => 'ZERO',
  :end_hour => 12,
  :end_minute => 'ZERO'
}

campaign_criterion_early = {
  :bid_modifier => 1.0,
  :campaign_id => campaign_id,
  :criterion => early
}

operations << {
  :operator => 'ADD',
  :operand => campaign_criterion_early
}

# Create a schedule from 12:00 PM (noon) to 2:00 PM with bids doubled.
peak = {
  :xsi_type => 'AdSchedule',
  :day_of_week => 'MONDAY',
  :start_hour => 12,
  :start_minute => 'ZERO',
  :end_hour => 14,
  :end_minute => 'ZERO'
}

campaign_criterion_peak = {
  # Double the bid.
  :bid_modifier => 2.0,
  :campaign_id => campaign_id,
  :criterion => peak
}

operations << {
  :operator => 'ADD',
  :operand => campaign_criterion_peak
}

campaign_criterion_srv.mutate(operations)

VB.NET

Dim operations As New List(Of CampaignCriterionOperation)()

' Create operations to remove any existing ad schedules for Monday. Ad schedules cannot
' overlap.
For Each existingCriterionId As Long In existingCriteriaIds
  Dim campaignCriterion As New CampaignCriterion()
  campaignCriterion.campaignId = campaignId
  Dim adSchedule As New AdSchedule()
  adSchedule.id = existingCriterionId
  campaignCriterion.criterion = adSchedule

  Dim removeOperation As New CampaignCriterionOperation()
  removeOperation.operand = campaignCriterion
  removeOperation.operator = [Operator].REMOVE

  operations.Add(removeOperation)
Next

' Create a schedule for 800 AM to 1200 PM (noon) with no change to bids.
Dim early As New AdSchedule()
early.dayOfWeek = DayOfWeek.MONDAY
early.startHour = 8
early.startMinute = MinuteOfHour.ZERO
early.endHour = 12
early.endMinute = MinuteOfHour.ZERO

Dim campaignCriterionEarly As New CampaignCriterion()
' Run at normal bid rates.
campaignCriterionEarly.bidModifier = 1.0
campaignCriterionEarly.campaignId = campaignId
campaignCriterionEarly.criterion = early

' Create a schedule for 1200 PM (noon) to 200 PM with bids doubled.
Dim peak As New AdSchedule()
peak.dayOfWeek = DayOfWeek.MONDAY
peak.startHour = 12
peak.startMinute = MinuteOfHour.ZERO
peak.endHour = 14
peak.endMinute = MinuteOfHour.ZERO

Dim campaignCriterionPeak As New CampaignCriterion()
' Double the bid.
campaignCriterionPeak.bidModifier = 2.0
campaignCriterionPeak.campaignId = campaignId
campaignCriterionPeak.criterion = peak

' Create operations to add the New schedules.
Dim operationEarly As New CampaignCriterionOperation()
operationEarly.operand = campaignCriterionEarly
operationEarly.operator = [Operator].ADD
operations.Add(operationEarly)

Dim operationPeak As New CampaignCriterionOperation()
operationPeak.operand = campaignCriterionPeak
operationPeak.operator = [Operator].ADD
operations.Add(operationPeak)

campaignCriterionService.mutate(operations.ToArray())

To stop ads from showing during specific times, remove the AdSchedule criteria using its id and the campaign's id.

Key Point: Use caution when removing an AdSchedule criterion when the goal is to prevent ads from serving during the day and time of the criterion. If the criterion is the only AdSchedule for the campaign and you remove it, then ads for the campaign will be eligible to run all day, every day, including the day and time of the criterion you removed.

Java

List<CampaignCriterionOperation> removeOperations = new ArrayList<>();

for (Long criterionId : criteriaIds) {
  // Remove the schedule with the specified criterion ID.
  AdSchedule scheduleToRemove = new AdSchedule();
  scheduleToRemove.setId(criterionId);

  CampaignCriterion campaignCriterion = new CampaignCriterion();

  campaignCriterion.setCampaignId(campaignId);
  campaignCriterion.setCriterion(scheduleToRemove);

  CampaignCriterionOperation operation = new CampaignCriterionOperation();
  operation.setOperand(campaignCriterion);
  operation.setOperator(Operator.REMOVE);
  removeOperations.add(operation);
}

campaignCriterionService.mutate(
    removeOperations.toArray(new CampaignCriterionOperation[removeOperations.size()]));

CSharp

List<CampaignCriterionOperation> removeOperations = new List<CampaignCriterionOperation>();

foreach (long criterionId in criteriaIds) {
  // Remove the schedule with the specified criterion ID.
  AdSchedule scheduleToRemove = new AdSchedule();
  scheduleToRemove.id = criterionId;

  CampaignCriterion campaignCriterion = new CampaignCriterion();

  campaignCriterion.campaignId = campaignId;
  campaignCriterion.criterion = scheduleToRemove;

  CampaignCriterionOperation operation = new CampaignCriterionOperation();
  operation.operand = campaignCriterion;
  operation.@operator = Operator.REMOVE;
  removeOperations.Add(operation);
}

campaignCriterionService.mutate(removeOperations.ToArray());

Python

operations = [{
    'operator': 'REMOVE',
    'operand': {
        'campaignId': campaign_id,
        'criterion': {
            'id': criteria_id
        }
    }
} for criteria_id in criteria_ids]

if operations:
  campaign_criterion_service.mutate(operations)

PHP

$removeOperations = [];

foreach ($criteriaIds as $criterionId) {
    // Remove the schedule with the specified criterion ID.
    $scheduleToRemove = new AdSchedule();
    $scheduleToRemove->setId($criterionId);

    $campaignCriterion = new CampaignCriterion();

    $campaignCriterion->setCampaignId($campaignId);
    $campaignCriterion->setCriterion($scheduleToRemove);

    $operation = new CampaignCriterionOperation();
    $operation->setOperand($campaignCriterion);
    $operation->setOperator(Operator::REMOVE);
    $removeOperations[] = $operation;
}

if (!empty($removeOperations)) {
    $campaignCriterionService->mutate($removeOperations);
}

Perl

my @remove_operations = ();

foreach my $criterion_id (@{$criteria_ids}) {
  # Remove the schedule with the specified criterion ID.
  my $schedule_to_remove = Google::Ads::AdWords::v201802::AdSchedule->new({
    id => $criterion_id
  });

  my $campaign_criterion =
    Google::Ads::AdWords::v201802::CampaignCriterion->new({
      campaignId => $campaign_id,
      criterion  => $schedule_to_remove
    });

  my $operation =
    Google::Ads::AdWords::v201802::CampaignCriterionOperation->new({
      operand  => $campaign_criterion,
      operator => 'REMOVE'
    });
  push @remove_operations, $operation;
}

$client->CampaignCriterionService()
  ->mutate({operations => \@remove_operations});

Ruby

operations = criteria_ids.map do |criterion_id|
  {
    :operator => 'REMOVE',
    :operand => {
      :campaign_id => campaign_id,
      :criterion => {
        :id => criterion_id
      }
    }
  }
end

campaign_criterion_srv.mutate(operations) unless operations.empty?

VB.NET

Dim removeOperations As New List(Of CampaignCriterionOperation)()

For Each criterionId As Long In criteriaIds
  ' Remove the schedule with the specified criterion ID.
  Dim scheduleToRemove As New AdSchedule()
  scheduleToRemove.id = criterionId

  Dim campaignCriterion As New CampaignCriterion()

  campaignCriterion.campaignId = campaignId
  campaignCriterion.criterion = scheduleToRemove

  Dim operation As New CampaignCriterionOperation()
  operation.operand = campaignCriterion
  operation.operator = [Operator].REMOVE
  removeOperations.Add(operation)
Next

campaignCriterionService.mutate(removeOperations.ToArray())

This example shows how to change the time ads are showing. You need to remove the existing AdSchedule first, then add the new one.

Java

List<CampaignCriterionOperation> operations = new ArrayList<>();

// Create an operation that will remove the existing schedule for Friday.
AdSchedule existingScheduleForFriday = new AdSchedule();
existingScheduleForFriday.setId(criterionIdForFriday);

CampaignCriterion existingCampaignCriterionForFriday = new CampaignCriterion();
existingCampaignCriterionForFriday.setCampaignId(campaignId);
existingCampaignCriterionForFriday.setCriterion(existingScheduleForFriday);

CampaignCriterionOperation removeOperation = new CampaignCriterionOperation();
removeOperation.setOperand(existingCampaignCriterionForFriday);
removeOperation.setOperator(Operator.REMOVE);
operations.add(removeOperation);

// Create an operation to add the new schedule for Friday.
AdSchedule newScheduleForFriday = new AdSchedule();
newScheduleForFriday.setDayOfWeek(DayOfWeek.FRIDAY);
// Start at 3:00 pm...
newScheduleForFriday.setStartHour(15);
newScheduleForFriday.setStartMinute(MinuteOfHour.ZERO);
// ... and end at 7:45 pm
newScheduleForFriday.setEndHour(19);
newScheduleForFriday.setEndMinute(MinuteOfHour.FORTY_FIVE);

CampaignCriterion newCampaignCriterionForFriday = new CampaignCriterion();
newCampaignCriterionForFriday.setCampaignId(campaignId);
newCampaignCriterionForFriday.setCriterion(newScheduleForFriday);
// Run at normal bid rates
newCampaignCriterionForFriday.setBidModifier(1.0);

CampaignCriterionOperation addOperation = new CampaignCriterionOperation();
addOperation.setOperand(newCampaignCriterionForFriday);
addOperation.setOperator(Operator.ADD);
operations.add(addOperation);

campaignCriterionService.mutate(
    operations.toArray(new CampaignCriterionOperation[operations.size()]));

CSharp

List<CampaignCriterionOperation> operations = new List<CampaignCriterionOperation>();

// Create an operation that will remove the existing schedule for Friday.
AdSchedule existingScheduleForFriday = new AdSchedule();
existingScheduleForFriday.id = criterionIdForFriday;

CampaignCriterion existingCampaignCriterionForFriday = new CampaignCriterion();
existingCampaignCriterionForFriday.campaignId = campaignId;
existingCampaignCriterionForFriday.criterion = existingScheduleForFriday;

CampaignCriterionOperation removeOperation = new CampaignCriterionOperation();
removeOperation.operand = existingCampaignCriterionForFriday;
removeOperation.@operator = Operator.REMOVE;
operations.Add(removeOperation);

// Create an operation to add the new schedule for Friday.
AdSchedule newScheduleForFriday = new AdSchedule();
newScheduleForFriday.dayOfWeek = DayOfWeek.FRIDAY;
// Start at 3:00 pm...
newScheduleForFriday.startHour = 15;
newScheduleForFriday.startMinute = MinuteOfHour.ZERO;
// ... and end at 7:45 pm
newScheduleForFriday.endHour = 19;
newScheduleForFriday.endMinute = MinuteOfHour.FORTY_FIVE;

CampaignCriterion newCampaignCriterionForFriday = new CampaignCriterion();
newCampaignCriterionForFriday.campaignId = campaignId;
newCampaignCriterionForFriday.criterion = newScheduleForFriday;
// Run at normal bid rates
newCampaignCriterionForFriday.bidModifier = 1.0;

CampaignCriterionOperation addOperation = new CampaignCriterionOperation();
addOperation.operand = newCampaignCriterionForFriday;
addOperation.@operator = Operator.ADD;
operations.Add(addOperation);

campaignCriterionService.mutate(operations.ToArray());

Python

operations = [
    # Create an operation that will remove the existing schedule for Friday.
    {
        'operator': 'REMOVE',
        'operand': {
            'campaignId': campaign_id,
            'criterion': {
                'id': friday_criterion_id
            }
        }
    },
    # Create an operation to add the new schedule for Friday.
    {
        'operator': 'ADD',
        'operand': {
            'campaignId': campaign_id,
            'criterion': {
                'xsi_type': 'AdSchedule',
                'dayOfWeek': 'FRIDAY',
                'startHour': 15,
                'startMinute': 'ZERO',
                'endHour': 19,
                'endMinute': 'FORTY_FIVE'
            },
            # Run at normal bid rates.
            'bidModifier': 1.0
        }
    }
]

campaign_criterion_service.mutate(operations)

PHP

$operations = [];

// Create an operation that will remove the existing schedule for Friday.
$existingScheduleForFriday = new AdSchedule();
$existingScheduleForFriday->setId($criterionIdForFriday);

$existingCampaignCriterionForFriday = new CampaignCriterion();
$existingCampaignCriterionForFriday->setCampaignId($campaignId);
$existingCampaignCriterionForFriday->setCriterion(
    $existingScheduleForFriday
);

$removeOperation = new CampaignCriterionOperation();
$removeOperation->setOperand($existingCampaignCriterionForFriday);
$removeOperation->setOperator(Operator::REMOVE);
$operations[] = $removeOperation;

// Create an operation to add the new schedule for Friday.
$newScheduleForFriday = new AdSchedule();
$newScheduleForFriday->setDayOfWeek(DayOfWeek::FRIDAY);
// Start at 3:00 pm...
$newScheduleForFriday->setStartHour(15);
$newScheduleForFriday->setStartMinute(MinuteOfHour::ZERO);
// ... and end at 7:45 pm
$newScheduleForFriday->setEndHour(19);
$newScheduleForFriday->setEndMinute(MinuteOfHour::FORTY_FIVE);

$newCampaignCriterionForFriday = new CampaignCriterion();
$newCampaignCriterionForFriday->setCampaignId($campaignId);
$newCampaignCriterionForFriday->setCriterion($newScheduleForFriday);
// Run at normal bid rates
$newCampaignCriterionForFriday->setBidModifier(1.0);

$addOperation = new CampaignCriterionOperation();
$addOperation->setOperand($newCampaignCriterionForFriday);
$addOperation->setOperator(Operator::ADD);
$operations[] = $addOperation;

$campaignCriterionService->mutate($operations);

Perl

my @operations = ();

# Create an operation that will remove the existing schedule for Friday.
my $existing_campaign_criterion_for_friday =
  Google::Ads::AdWords::v201802::CampaignCriterion->new({
    campaignId => $campaign_id,
    criterion  => Google::Ads::AdWords::v201802::AdSchedule->new({
        id => $criterion_id_for_friday
      })});

my $remove_operation =
  Google::Ads::AdWords::v201802::CampaignCriterionOperation->new({
    operand  => $existing_campaign_criterion_for_friday,
    operator => 'REMOVE'
  });

push @operations, $remove_operation;

# Create an operation to add the new schedule for Friday.
my $new_schedule_for_friday = Google::Ads::AdWords::v201802::AdSchedule->new({
  dayOfWeek => 'FRIDAY',
  # Start at 3:00 pm...
  startHour   => '15',
  startMinute => 'ZERO',
  # ... and end at 7:45 pm
  endHour   => '19',
  endMinute => 'FORTY_FIVE'
});

my $new_campaign_criterion_for_friday =
  Google::Ads::AdWords::v201802::CampaignCriterion->new({
    campaignId => $campaign_id,
    criterion  => $new_schedule_for_friday,
    # Run at normal bid rates
    bidModifier => '1.0'
  });

my $add_operation =
  Google::Ads::AdWords::v201802::CampaignCriterionOperation->new({
    operand  => $new_campaign_criterion_for_friday,
    operator => 'ADD'
  });
push @operations, $add_operation;

$client->CampaignCriterionService()->mutate({operations => \@operations});

Ruby

operations = []

# Create an operation that will remove the existing schedule for Friday.
operations << {
  :operator => 'REMOVE',
  :operand => {
    :campaign_id => campaign_id,
    :criterion => {
      :id => criterion_id_for_friday
    }
  }
}

# Create an operation to add the new schedule for Friday.
operations << {
  :operator => 'ADD',
  :operand => {
    :campaign_id => campaign_id,
    # Run at normal bid rades.
    :bid_modifier => 1.0,
    :criterion => {
      :xsi_type => 'AdSchedule',
      :day_of_week => 'FRIDAY',
      # Start at 3:00 PM...
      :start_hour => 15,
      :start_minute => 'ZERO',
      # ...and end at 7:45 PM.
      :end_hour => 19,
      :end_minute => 'FORTY_FIVE'
    }
  }
}

campaign_criterion_srv.mutate(operations)

VB.NET

Dim operations As New List(Of CampaignCriterionOperation)()

' Create an operation that will remove the existing schedule for Friday.
Dim existingScheduleForFriday As New AdSchedule()
existingScheduleForFriday.id = criterionIdForFriday

Dim existingCampaignCriterionForFriday As New CampaignCriterion()
existingCampaignCriterionForFriday.campaignId = campaignId
existingCampaignCriterionForFriday.criterion = existingScheduleForFriday

Dim removeOperation As New CampaignCriterionOperation()
removeOperation.operand = existingCampaignCriterionForFriday
removeOperation.operator = [Operator].REMOVE
operations.Add(removeOperation)

' Create an operation to add the New schedule for Friday.
Dim newScheduleForFriday As New AdSchedule()
newScheduleForFriday.dayOfWeek = DayOfWeek.FRIDAY
' Start at 3:00 pm...
newScheduleForFriday.startHour = 15
newScheduleForFriday.startMinute = MinuteOfHour.ZERO
' ... And end at 7:45 pm
newScheduleForFriday.endHour = 19
newScheduleForFriday.endMinute = MinuteOfHour.FORTY_FIVE

Dim newCampaignCriterionForFriday As New CampaignCriterion()
newCampaignCriterionForFriday.campaignId = campaignId
newCampaignCriterionForFriday.criterion = newScheduleForFriday
' Run at normal bid rates
newCampaignCriterionForFriday.bidModifier = 1.0

Dim addOperation As New CampaignCriterionOperation()
addOperation.operand = newCampaignCriterionForFriday
addOperation.operator = [Operator].ADD
operations.Add(addOperation)

campaignCriterionService.mutate(operations.ToArray())

Check out these code examples to see how to use the CampaignCriterionService to add a target to an existing campaign:

Java

AddCampaignTargetingCriteria

C#

AddCampaignTargetingCriteria

PHP

AddCampaignTargetingCriteria

Perl

AddCampaignTargetingCriteria

Python

AddCampaignTargetingCriteria

Ruby

AddCampaignTargetingCriteria

Measuring ad performance

You've set up a campaign, an ad group, a text ad, and multiple ad extensions: Now you want to find out how your campaign, ads, and extensions are performing. This is where reporting comes in.

You can look at your campaign's performance from different perspectives to answer key questions. Expand each use case below to see relevant reports and fields, and a sample AWQL report request.

How is my campaign performing on Search vs. Display?

Reports:

• CAMPAIGN_PERFORMANCE_REPORT
• ADGROUP_PERFORMANCE_REPORT
• AD_PERFORMANCE_REPORT

Key fields:

• AdNetworkType1
• Ctr

Sample AWQL request

SELECT CampaignId, CampaignName, AdNetworkType1,
  Impressions, Clicks, Cost, Ctr
FROM CAMPAIGN_PERFORMANCE_REPORT
DURING THIS_MONTH

Which ads result in the most clicks?

Reports:

• AD_PERFORMANCE_REPORT

Key fields:

• Id
• Clicks
• Impressions
• Ctr

Sample AWQL request

SELECT CampaignId, AdGroupId, AdType,
  PromotionLine, Id, Clicks, Impressions, Ctr,
  Cost
FROM AD_PERFORMANCE_REPORT
DURING THIS_MONTH

Which ad extensions are users clicking?

Reports:

• PLACEHOLDER_REPORT

Key fields:

• ClickType
• Ctr

Sample AWQL request

SELECT CampaignId, AdGroupId, ClickType,
  Clicks, Impressions, Ctr
FROM PLACEHOLDER_REPORT
DURING THIS_MONTH

Which sitelinks are users clicking?

Reports:

• PLACEHOLDER_FEED_ITEM_REPORT

Key fields:

• IsSelfAction
• PlaceholderType
• FeedId
• FeedItemId
• Ctr

Sample AWQL request

SELECT CampaignId, AdGroupId, FeedId,
  FeedItemId, Clicks, Impressions, Ctr
FROM PLACEHOLDER_FEED_ITEM_REPORT
WHERE PlaceholderType = 1
  AND IsSelfAction = 'true'
DURING THIS_MONTH

Which ads are getting the most clicks from mobile users?

Reports:

• AD_PERFORMANCE_REPORT

Key fields:

• Device
• Clicks
• Ctr

Sample AWQL request

SELECT CampaignId, AdGroupId, AdType, Id,
  Device, Clicks, Impressions, Ctr, Cost
FROM AD_PERFORMANCE_REPORT
WHERE Device IN ["TABLET", "HIGH_END_MOBILE"]
DURING THIS_MONTH

Which Display Network sites have shown my ads, and how many clicks did they generate?

Reports:

• AUTOMATIC_PLACEMENTS_PERFORMANCE_REPORT

Key fields:

• Domain
• Clicks

Sample AWQL request

SELECT CampaignId, AdGroupId, Domain, Clicks,
  Impressions, Ctr, Cost
FROM AUTOMATIC_PLACEMENTS_PERFORMANCE_REPORT
WHERE AdNetworkType1 = 'CONTENT'
DURING THIS_MONTH

The questions above focus on some common use cases and features. For even more options, check out the complete list of report types.

Next steps

After analyzing your reports you may want to:

• Add or modify ad extensions using the extension setting services.
• Customize your ads with dynamic information like prices or sales.
• Get new targeting ideas.
• Make changes to your bidding strategy.
• Set a bid modifier for ads on mobile devices.
• Create Dynamic Search Ads automatically based on the contents of your site.
• Start tracking conversions.