AdWords API
Hide

Dynamic Search Ads

Dynamic Search Ads (DSAs) are a way to target entire web sites—or portions of them—without having to create keywords and ad copy for all the possible matches. Instead, whenever a relevant user search occurs, Google dynamically generates an ad with a headline based on the query, and the text based on your most relevant landing page. The ad enters the auction and competes normally. So you get better results from broader exposure for more of your in-stock inventory, without making any changes to your existing keyword campaigns.

In addition to giving you the option of broadly targeting an entire website or domain, DSAs can also serve as a nice "catch-all" or back up option for your existing campaigns and keywords. You can set up keywords, ad groups, and ad copy as today, and then add a Dynamic Search Ad to catch as many queries as possible that don't match your existing campaign setup.

In this guide, we will walk you through the steps of creating and using Dynamic Search Ads with the AdWords API. All examples are in Java, but translate pretty transparently to other languages and client libraries.

Creating Dynamic Search Ads

There are three basic steps required to use Dynamic Search Ads in the AdWords API:

  1. Set up your campaign and specify its domain.
  2. Create one or more dynamic search ads.
  3. Specify one or more criteria for showing the DSAs in the campaign.

Let's walk through these individually now.

Specifying the domain

To tell AdWords that you're going to be using DSAs with your campaign, you first specify a domain on which the Dynamic Search Ads will operate. This is done by setting a DynamicSearchAdsSetting object on the settings property of the Campaign object. As an example, here we are creating a campaign that has GeoTargetTypeSetting, KeywordMatchSetting, and DynamicSearchAdsSetting values:

// Create campaign.
Campaign campaign = new Campaign();

// ... Set up general campaign parameters ...

// Set up DynamicSearchAdsSetting object.
DynamicSearchAdsSetting dsas = new DynamicSearchAdsSetting();
dsas.domainName = "example.org";
dsas.languageCode = "en";

// Set geo and keyword match options.
GeoTargetTypeSetting geoTarget = new GeoTargetTypeSetting();
geoTarget.setPositiveGeoTargetType(GeoTargetTypeSettingPositiveGeoTargetType.DONT_CARE);
KeywordMatchSetting keywordMatch = new KeywordMatchSetting();
keywordMatch.setOptIn(Boolean.FALSE);

// Add these to the campaign.
campaign.setSettings(new Setting[] { geoTarget, keywordMatch, dsas });

// Create operation.
CampaignOperation operation = new CampaignOperation();
operation.setOperand(campaign);
operation.setOperator(Operator.ADD);
CampaignOperation[] operations = new CampaignOperation[] { operation };

// Add campaigns.
CampaignReturnValue result = campaignService.mutate(operations);

Disabling Dynamic Search Ads on your campaign

You can turn off DSAs at the campaign level without having to pause your entire campaign; just update your DynamicSearchAdsSetting values and set the domainName to "-". You still need to specify a language code.

// Turn off DSAs for campaign with id = campaignId.
Campaign campaign = new Campaign();
campaign.setId(campaignId);

// Disable DSAs.
DynamicSearchAdsSetting dsas = new DynamicSearchAdsSetting();
dsas.domainName = "-";
dsas.languageCode = "en";

// Create operation.
CampaignOperation operation = new CampaignOperation();
operation.setOperand(campaign);
operation.setOperator(Operator.SET);
CampaignOperation[] operations = new CampaignOperation[] { operation };

// Update campaign.
CampaignReturnValue result = campaignService.mutate(operations);

Creating a Dynamic Search Ad

The next step is to create a DynamicSearchAd object. Google will provide the title for you based on any given user's search query, but you are still required to fill in the description1, description2, and displayUrl fields.

// Create DSA. somewhere above we got adGroupId for our ad group.
DynamicSearchAd dsa = new DynamicSearchAd();
dsa.setDescription1("Visit the Red Planet in style.");
dsa.setDescription2("Low-gravity fun for everyone!");
dsa.setDisplayUrl("www.example.org/marscruise");

// Create ad group ad.
AdGroupAd adGroupAd = new AdGroupAd();
adGroupAd.setAdGroupId(adGroupId);
adGroupAd.setAd(dsa);
adGroupAd.setStatus(AdGroupAdStatus.PAUSED);

// Create operation.
AdGroupAdOperation adGroupAdOperation = new AdGroupAdOperation();
adGroupAdOperation.setOperand(adGroupAd);
adGroupAdOperation.setOperator(Operator.ADD);
AdGroupAdOperation[] operations = new AdGroupAdOperation[] { adGroupAdOperation };

// Add the ad.
AdGroupAdReturnValue result = adGroupAdService.mutate(operations);

In Dynamic Search Ads, the finalUrls field is computed by the AdWords system when it creates the DSA. As a result, you are not allowed to set this field when creating DSAs. To use URL tracking software, you can specify what additional tracking parameters or redirects are needed using the trackingUrlTemplate field. When specifying this field, you must include one of the following parameters to allow the AdWords system to put in the resulting matched final URL:

Parameter Explanation
{unescapedlpurl}

Unescaped landing page URL—if you want to add something to the end, e.g.:

{unescapedlpurl}?dsa=true
{escapedlpurl}

Escaped (URL encoded) landing page URL—if you want to redirect to a tracker, e.g.:

http://tracking.com/lp={escapedurl}
{lpurlpath}

Only the path and query params from the computed URL, e.g.:

http://tracking.com.com/track/{lpurlpath}
{lpurl}

Encodes ? and = of landing page URL, ends with search query. If found at the very beginning of the `trackingUrlTemplate` field, it will actually be replaced by the {unescapedurl} value, e.g.:

http://tracking.com/redir.php?tracking=xyz&url;={lpurl}

For example:

DynamicSearchAd dsa = new DynamicSearchAd();
dsa.setDescription1("Visit the Red Planet in style.");
dsa.setDescription2("Low-gravity fun for everyone!");
dsa.setDisplayUrl("[www.example.org/marscruise](http://www.example.org/marscruise)");
dsa.setTrackingUrlTemplate("http://example.org/traveltracker/{escapedlpurl}");

Specifying criteria for the DSA

Finally, you'll want to set up some criteria to actually trigger serving of the Dynamic Search Ads. This will be done via the Webpage criterion object.

To the Webpage criterion, you'll add a WebpageParameter object, which contains between 1 and 3 WebpageConditions. These objects let you specify exactly what to filter or search on within the domain specified in the campaign settings previously.

There are four different kinds of things you can filter on within a domain:

WebPageConditionOperand Description
URL A string matching a partial URL of a page.
CATEGORY A string with a category to match against precisely.
PAGE_TITLE A string matching a partial page title.
PAGE_CONTENT A string matching some content within any given indexed page.

As an example, let's create a webpage condition that searches for anything the /children branch of our Mars vacation site, but only those pages with "Special Offer" in the title:

// Assumes the existence of adGroupId.
WebpageCondition cond1 = new WebpageCondition();
WebpageCondition cond2 = new WebpageCondition();

cond1.operand = WebpageCondition.URL;
cond1.argument = "/marscruise/children";
cond2.operand = WebpageCondition.PAGE_TITLE;
cond2.argument = "Special Offer";

WebpageParameter param = new WebpageParameter();
param.criterionName = "Special offers for children";
param.conditions = new WebpageCondition[] { cond1, cond2 };

Webpage webpage = new Webpage();
webpage.parameter = param;

// Create biddable ad group criterion.
BiddableAdGroupCriterion bagc = new BiddableAdGroupCriterion();
bagc.setAdGroupId(adGroupId);
bagc.setCriterion(webpage);
bagc.setUserStatus(UserStatus.PAUSED);
BiddingStrategyConfiguration bsc = new BiddingStrategyConfiguration();
CpcBid bid = new CpcBid();
bid.setBid(new Money(null, 10000000L));
bsc.setBids(new Bids[] { bid });
bagc.setBiddingStrategyConfiguration(bsc);

// Create operations.
AdGroupCriterionOperation operation = new AdGroupCriterionOperation();
operation.setOperator(Operator.ADD);
operation.setOperand(bagc);
AdGroupCriterionOperation[] operations = new AdGroupCriterionOperation[] { operation };

AdGroupCriterionReturnValue result = AdGroupCriterionService.mutate(operations);

Discovering your site's categories

You can use DataService to fetch a list of categories that Google thinks applies to your site. You can filter on domains or campaigns. As an example, let's fetch the list of categories for our site, within a specific campaign:

DataServiceInterface dataService = adWordsServices.get(session, DataServiceInterface.class);

// Create selector.
SelectorBuilder builder = new SelectorBuilder();
Selector selector = builder
    .fields("DomainName", "Category", "IsoLanguage")
    .equals("DomainName", "example.org")
    .equals("CampaignId", campaignId)
    .limit(PAGE_SIZE)
    .build();

DomainCategoryPage page = dataService.getDomainCategory(selector);

Excluding parts of your site

It is also possible to use the AdGroupCriterionService to set up negative Webpage criteria. You could use this, for example, to exclude pages with a particular title that you wished to manage via another campaign or adgroup.

// Assumes the existence of adGroupId.
WebpageCondition cond = new WebpageCondition();
cond.operand = WebpageCondition.PAGE_TITLE;
cond.argument = "Limited Time";

WebpageParameter param = new WebpageParameter();
param.criterionName = "Exclude Limited time pages";
param.conditions = new WebpageCondition[] { cond };

Webpage webpage = new Webpage();
webpage.parameter = param;

// Create biddable ad group criterion.
NegativeAdGroupCriterion nagc = new NegativeAdGroupCriterion();
nagc.setAdGroupId(adGroupId);
nagc.setCriterion(webpage);

// Create operations.
AdGroupCriterionOperation operation = new AdGroupCriterionOperation();
operation.setOperator(Operator.ADD);
operation.setOperand(nagc);
AdGroupCriterionOperation[] operations = new AdGroupCriterionOperation[] { operation };

AdGroupCriterionReturnValue result = AdGroupCriterionService.mutate(operations);

Other criteria

Dynamic Search Ads campaigns and ad groups are not restricted to only Webpage criteria; you are welcome to continue to use other criterion types to further refine and improve the quality of your advertisements. You should be judicious in your use of additional criteria, however, as adding too many can diminish the effectiveness of your auto targeting via DSAs.

Reporting

You can use the AdWords API to download three different reports pertinent to Dynamic Search Ads.

Criteria Performance Report

The Parameter or Dynamic ad target field in this report includes the name of the WebpageParameter associated with this object, for those cases where the criterion object was of type WebpageCriterion. Note that this is an "attribute" type field, which means that it contains fixed data—in this case the WebpageParameter associated with the performance data.

Keywordless Category Report

The Keywordless Category Performance report includes keywordless ads for Dynamic Search Ads statistics aggregated by category. This report does not return zero impression rows. The Category0, Category1, and Category2 fields will contain the category and sub-category information related to the results.

Top level categories First level sub-categories Second level sub-categories Clicks Impressions Day Cost
Tourism & Travel Extraterrestrial Mars 1 71 6/20/2014 0.05
Tourism & Travel Adventure Travel 0 279 6/21/2014 0

Keywordless Query Report

The Keywordless Query Performance report includes keywordless ads for Dynamic Search Ads statistics based on search terms. This report does not return zero impression rows. The Query field contains any matching queries that generated results.

Search term Clicks Impressions Day Cost URL
mars luxury 0 20 6/20/2014 0 http://example.org/LuxuryMarsCruises
mars luxury 0 14 6/21/2014 0 http://example.org/LuxuryMarsCruises
low cost mars 0 24 6/20/2014 0 http://example.org/MarsOnABudget
low cost mars 0 18 6/21/2014 0 http://example.org/MarsOnABudget
mars landmarks 0 130 6/21/2014 0 http://example.org/MajorTouristSpots
mars funny face 0 44 6/21/2014 0 http://example.org/MajorTouristSpots
space travel safety 1 3 6/20/2014 0.05 http://example.org/ButIsItSafe
mars departure points 0 11 6/21/2014 0 http://example.org/HowToGetToMars
mars beaches 0 24 6/20/2014 0 http://example.org/MarsBeachVacations
mars beaches 0 39 6/21/2014 0 http://example.org/MarsBeachVacations
mars canyoning 0 23 6/21/2014 0 http://example.org/DayTripsAndActivities
Total 1 350 -- 0.05 --

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies.

Send feedback about...

This page
Documentation feedback
AdWords API
Product feedback