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.
TextAd	Yes	Yes	Standard AdWords text ads. Includes a link to your website and a description or promotion of your product or service. These will be replaced by Expanded Text Ads.
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.
CallOnlyAd	Yes	Yes	An ad for a Click to Call Only campaign.
ImageAd	Yes^1	Yes	An ad that includes a graphic to promote your business.
ResponsiveDisplayAd	No	Yes	Contains a marketing image, a short and long headline, a description, and an optional advertiser name and logo.
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.

ExpandedTextAd code for a guitar shop would look something like this:

ExpandedTextAd textAd = new ExpandedTextAd();
textAd.setHeadlinePart1("Intergalactic Guitar Shop");
textAd.setHeadlinePart2("Large selection of guitars");
textAd.setDescription("Weekly specials on accessories");
textAd.setFinalUrls(new String[]{
    "http://www.example.com/intergalacticguitars/products"});

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.

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.

Note: Prior to v201710, ad rotation settings were specified at the campaign level. This setting is read-only in v201710. If you're on an earlier API version, ad groups inherit from their campaign unless this setting was specifically set for the ad group using the AdWords UI. In addition, all the old settings other than ROTATE_INDEFINITELY map to the new OPTIMIZE setting.

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 programatically 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 AdScheduleCriterion 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:

// Obtain a campaignId you want to configure
Long campaignId =  Long.valueOf("INSERT_CAMPAIGN_ID_HERE");

// Closed on Sunday, so we don't configure an AdSchedule for Sunday.
DayOfWeek[] days = new DayOfWeek[] {DayOfWeek.MONDAY,
    DayOfWeek.TUESDAY,
    DayOfWeek.WEDNESDAY,
    DayOfWeek.THURSDAY,
    DayOfWeek.FRIDAY,
    DayOfWeek.SATURDAY};

List operations = new ArrayList();
for (int i = 0; i < 6; i++) {
  AdSchedule schedule = new AdSchedule();
  schedule.setDayOfWeek(days[i]);
  // 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()]));

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

// Obtain a campaignId you want to configure
Long campaignId = Long.valueOf("INSERT_CAMPAIGN_ID_HERE");

List operations = new ArrayList();
AdSchedule early = new AdSchedule();
AdSchedule peak = new AdSchedule();
CampaignCriterionOperation operationEarly = new CampaignCriterionOperation();
CampaignCriterion campaignCriterionEarly = new CampaignCriterion();
CampaignCriterionOperation operationPeak = new CampaignCriterionOperation();
CampaignCriterion campaignCriterionPeak = new CampaignCriterion();

// Sample schedule for Monday
early.setDayOfWeek(DayOfWeek.MONDAY);
peak.setDayOfWeek(DayOfWeek.MONDAY);
// Start at 8:00 am...
early.setStartHour(8);
early.setStartMinute(MinuteOfHour.ZERO);
// ... and run until promotion starts
early.setEndHour(12);
early.setEndMinute(MinuteOfHour.ZERO);
// Run at normal bid rates
campaignCriterionEarly.setBidModifier(1.0);

// Start higher bidding at noon...
peak.setStartHour(12);
peak.setStartMinute(MinuteOfHour.ZERO);
// ... and run until promotion ends...
peak.setEndHour(14);
peak.setEndMinute(MinuteOfHour.ZERO);
// ... at double the bid!
campaignCriterionPeak.setBidModifier(2.0);

campaignCriterionEarly.setCampaignId(campaignId);
campaignCriterionEarly.setCriterion(early);
campaignCriterionPeak.setCampaignId(campaignId);
campaignCriterionPeak.setCriterion(peak);

operationEarly.setOperand(campaignCriterionEarly);
operationEarly.setOperator(Operator.ADD);
operationPeak.setOperand(campaignCriterionPeak);
operationPeak.setOperator(Operator.ADD);
operations.add(operationEarly);
operations.add(operationPeak);

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

This example shows how to stop ads from showing on a specified day. You need to send an AdSchedule with the same Id as the existing AdSchedule.

// Suppose you already have a schedule of 8:45 am to 7:45 pm for Monday to Saturday

// Obtain the campaignId and criterionId you want to configure
Long campaignId = Long.valueOf("INSERT_CAMPAIGN_ID_HERE");
Long criterionIdForSaturday = Long.valueOf("INSERT_CRITERION_ID_HERE");

List removeOperations = new ArrayList();

// Remove a schedule for Saturday
AdSchedule removeScheduleForSaturday = new AdSchedule();
removeScheduleForSaturday.setId(criterionIdForSaturday);

CampaignCriterionOperation removeOperation = new CampaignCriterionOperation();
CampaignCriterion removeCampaignCriterion = new CampaignCriterion();

removeCampaignCriterion.setCampaignId(campaignId);
removeCampaignCriterion.setCriterion(removeScheduleForSaturday);

removeOperation.setOperand(removeCampaignCriterion);
removeOperation.setOperator(Operator.REMOVE);
removeOperations.add(removeOperation);

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

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

// Suppose you already have a schedule of 8:45 am to 7:45 pm for Monday to Saturday
// Obtain the campaignId and criterionId you want to configure
Long campaignId = Long.valueOf("INSERT_CAMPAIGN_ID_HERE");
Long criterionIdForFriday = Long.valueOf("INSERT_CRITERION_ID_HERE");

List operations = new ArrayList();

// Remove a schedule for Friday first
AdSchedule removeScheduleForFriday = new AdSchedule();
removeScheduleForFriday.setId(criterionIdForFriday);

CampaignCriterionOperation removeOperationForFriday = new CampaignCriterionOperation();
CampaignCriterion removeCampaignCriterionForFriday = new CampaignCriterion();

removeCampaignCriterionForFriday.setCampaignId(campaignId);
removeCampaignCriterionForFriday.setCriterion(removeScheduleForFriday);

removeOperationForFriday.setOperand(removeCampaignCriterionForFriday);
removeOperationForFriday.setOperator(Operator.REMOVE);
operations.add(removeOperationForFriday);

// Create a new schedule for Friday
AdSchedule addScheduleForFriday = new AdSchedule();
addScheduleForFriday.setDayOfWeek(DayOfWeek.FRIDAY);
// Start at 3:00 pm...
addScheduleForFriday.setStartHour(15);
addScheduleForFriday.setStartMinute(MinuteOfHour.ZERO);
// ... and end at 7:45 pm
addScheduleForFriday.setEndHour(19);
addScheduleForFriday.setEndMinute(MinuteOfHour.FORTY_FIVE);
CampaignCriterionOperation addOperationForFriday = new CampaignCriterionOperation();
CampaignCriterion campaignAddCriterionForFriday = new CampaignCriterion();

campaignAddCriterionForFriday.setCampaignId(campaignId);
campaignAddCriterionForFriday.setCriterion(addScheduleForFriday);
// Run at normal bid rates
campaignAddCriterionForFriday.setBidModifier(1.0);
addOperationForFriday.setOperand(campaignAddCriterionForFriday);
addOperationForFriday.setOperator(Operator.ADD);
operations.add(addOperationForFriday);

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

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.