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?
Google 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
C#
PHP
Perl
Python
Ruby
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 Google 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 Google Ads 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
|
Yes | No | An ad for a Click to Call Only campaign. |
ImageAd
|
Yes1 | Yes | An ad that includes a graphic to promote your business. |
TemplateAd
|
Yes2 | Yes2 | An ad based on a predefined template. |
MultiAssetResponsiveDisplayAd
|
Yes | Yes | An enhanced form of ResponsiveDisplayAd ,
that supports multiple assets for text and image fields. Google Ads uses serving-time optimization
to select the best asset and rendering combinations for each request.
|
ResponsiveSearchAd
|
Yes | Yes | An ad format that supports multiple assets for text fields. Google Ads uses serving-time optimization to select the best asset and rendering combinations for each request. |
1 An ImageAd
on the Search Network will appear only on websites of Google search partners,
not on Google Search.
2 See the list of TemplateAd
templates
and the template ads guide for more information,
including which networks each template ID supports.
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
C#
PHP
Perl
Python
Ruby
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 theproductVideoList
must be populated. - If you decide to use the
productVideoList
, then the videos need to already exist in the Google Ads system. They can be uploaded either through the Google Ads UI or through Google Ads scripts. The IDs can then be retrieved through theMediaService
.
Check out the AddGmailAds example in your client library's advanced operations examples folder for a complete example.
Java
C#
PHP
Perl
Python
Ruby
Mutating ads
You can mutate your ads without losing their performance data using AdService. To do so, follow these steps:
- Create an
Ad
object. - Set its
id
to the ID of the ad you want to mutate. Supply any required attributes (
headlinePart1
,headlinePart2
,description
).C#
// Create an expanded text ad using the provided ad ID. ExpandedTextAd expandedTextAd = new ExpandedTextAd { id = adId, // Update some properties of the expanded text ad. headlinePart1 = "Cruise to Pluto #" + ExampleUtilities.GetShortRandomString(), headlinePart2 = "Tickets on sale now", description = "Best space cruise ever.", finalUrls = new string[] { "http://www.example.com/" }, finalMobileUrls = new string[] { "http://www.example.com/mobile" } };
Java
// Creates an expanded text ad using the provided ad ID. ExpandedTextAd expandedTextAd = new ExpandedTextAd(); expandedTextAd.setId(adId); // Updates some properties of the expanded text ad. expandedTextAd.setHeadlinePart1("Cruise to Pluto #" + System.currentTimeMillis()); expandedTextAd.setHeadlinePart2("Tickets on sale now"); expandedTextAd.setDescription("Best space cruise ever."); expandedTextAd.setFinalUrls(new String[] {"http://www.example.com/"}); expandedTextAd.setFinalMobileUrls(new String[] {"http://www.example.com/mobile"});
Python
# Create an expanded text ad using the provided ad ID. expanded_text_ad = { 'xsi_type': 'ExpandedTextAd', 'id': ad_id, 'headlinePart1': 'Cruise to Pluto #' + str(uuid.uuid4())[:8], 'headlinePart2': 'Tickets on sale now', 'description': 'Best space cruise ever.', 'finalUrls': ['http://www.example.com'], 'finalMobileUrls': ['http://www.example.com/mobile'] }
PHP
// Creates an expanded text ad using the provided ad ID. $expandedTextAd = new ExpandedTextAd(); $expandedTextAd->setId($adId); // Updates some properties of the expanded text ad. $expandedTextAd->setHeadlinePart1('Cruise to Pluto #' . uniqid()); $expandedTextAd->setHeadlinePart2('Tickets on sale now'); $expandedTextAd->setDescription('Best space cruise ever.'); $expandedTextAd->setFinalUrls(['http://www.example.com/']); $expandedTextAd->setFinalMobileUrls(['http://www.example.com/mobile']);
Perl
# Creates an expanded text ad using the provided ad ID. my $expanded_text_ad = Google::Ads::AdWords::v201809::ExpandedTextAd->new({ id => $ad_id, headlinePart1 => "Cruise to Pluto #" . substr(uniqid(), 0, 8), headlinePart2 => "Tickets on sale now", description => "Best space cruise ever.", finalUrls => [ "http://www.example.com/" ], finalMobileUrls => [ "http://www.example.com/mobile" ] });
Ruby
trip_number = (Time.new.to_f * 1000).to_i # Creates an expanded text ad using the provided ad ID and updates some # properties of the expanded text ad. expanded_text_ad = { :id => ad_id, :xsi_type => 'ExpandedTextAd', :headline_part1 => 'Cruise to Mars #%d' % trip_number, :headline_part2 => 'Best Space Cruise Line', :description => 'Buy your tickets now!', :final_urls => ['http://www.example.com/%d' % trip_number], :final_mobile_urls => ['http://www.example.com/mobile/%d' % trip_number] }
Then, create an
AdOperation
with the operator set toSET
and send the API request to the server:C#
AdOperation operation = new AdOperation { operand = expandedTextAd, @operator = Operator.SET }; try { // Update the ad on the server. AdReturnValue result = adService.mutate(new AdOperation[] { operation }); ExpandedTextAd updatedAd = (ExpandedTextAd) result.value[0];
Java
AdOperation operation = new AdOperation(); operation.setOperator(Operator.SET); operation.setOperand(expandedTextAd); // Updates the ad on the server. ExpandedTextAd updatedAd = (ExpandedTextAd) adService.mutate(new AdOperation[] {operation}).getValue(0);
Python
operations = [{ 'operator': 'SET', 'operand': expanded_text_ad }] # Updates the ad on ther server. result = ad_service.mutate(operations) updated_ad = result['value'][0]
PHP
$operation = new AdOperation(); $operation->setOperand($expandedTextAd); $operation->setOperator(Operator::SET); $operations[] = $operation; // Updates the ad on the server. $result = $adService->mutate($operations); $updatedAd = $result->getValue()[0];
Perl
my $operation = Google::Ads::AdWords::v201809::AdOperation->new({ operator => "SET", operand => $expanded_text_ad }); push @operations, $operation; # Updates the ad on the server. my $result = $client->AdService()->mutate({ operations => \@operations }); my $updated_ad = $result->get_value()->[0];
Ruby
operation = { :operator => 'SET', :operand => expanded_text_ad } # Updates the ad on the server. response = ad_srv.mutate([operation])
Ad types that support mutability
Only the following ad types are mutable via AdService:
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.
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 Google Ads accounts, and Google 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 or callout 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.
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()]));
C#
// 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::v201809::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::v201809::CampaignCriterion->new({ campaignId => $campaign_id, criterion => $schedule, # Run at normal bid rates bidModifier => '1.0' }); my $operation = Google::Ads::AdWords::v201809::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()]));
C#
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::v201809::CampaignCriterion->new({ campaignId => $campaign_id, criterion => Google::Ads::AdWords::v201809::AdSchedule->new({ id => $existing_criterion_id })}); my $remove_operation = Google::Ads::AdWords::v201809::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::v201809::AdSchedule->new({ dayOfWeek => 'MONDAY', startHour => '8', startMinute => 'ZERO', endHour => '12', endMinute => 'ZERO' }); my $campaign_criterion_early = Google::Ads::AdWords::v201809::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::v201809::AdSchedule->new({ dayOfWeek => 'MONDAY', startHour => '12', startMinute => 'ZERO', endHour => '14', endMinute => 'ZERO' }); my $campaign_criterion_peak = Google::Ads::AdWords::v201809::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::v201809::CampaignCriterionOperation->new({ operand => $campaign_criterion_early, operator => 'ADD' }); push @operations, $operation_early; my $operation_peak = Google::Ads::AdWords::v201809::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
.
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()]));
C#
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::v201809::AdSchedule->new({ id => $criterion_id }); my $campaign_criterion = Google::Ads::AdWords::v201809::CampaignCriterion->new({ campaignId => $campaign_id, criterion => $schedule_to_remove }); my $operation = Google::Ads::AdWords::v201809::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()]));
C#
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::v201809::CampaignCriterion->new({ campaignId => $campaign_id, criterion => Google::Ads::AdWords::v201809::AdSchedule->new({ id => $criterion_id_for_friday })}); my $remove_operation = Google::Ads::AdWords::v201809::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::v201809::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::v201809::CampaignCriterion->new({ campaignId => $campaign_id, criterion => $new_schedule_for_friday, # Run at normal bid rates bidModifier => '1.0' }); my $add_operation = Google::Ads::AdWords::v201809::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
C#
PHP
Perl
Python
Ruby
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.
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.