More features added to version v201008

Wednesday, September 29, 2010

Last week, we announced version v201008 of the AdWords API. Today, we’re releasing more new features as part of this version that we think you’ll be excited to start using.

Here’s what we’ve added:

  • Remarketing: Reach customers who have shown an interest in your product or service by visiting your site, and show them relevant ads across the Google Display Network.  Note that with this release, you can create new remarketing lists only by generating new remarketing tags.  We’ll add support for creating lists with existing remarketing and conversion tags in the next version of the API. Learn more about remarketing
  • My Client Center (MCC) features: Retrieve your MCC account hierarchy with the new ServicedAccountService
  • AlertService: Retrieve alerts for the AdWords accounts under your MCC account
  • Change History (beta): Use the new CustomerSyncService beta to get a list of entities that have changed over a specific period of time
You might have noticed that we’re adding support for new features faster than in the past. The new AdWords API architecture -- starting with version v200909 -- enables us to add features much more quickly. As we transition the remaining functionality of the old architecture (v13) to the new architecture, you can expect to see more frequent releases, and features available in the AdWords interface will be available in the API much sooner.

Please check out these new features and as always, share your feedback on the developer forum.

Posted by Jason Shafton, Product Marketing Manager

Discover v201008: ExperimentService

Tuesday, September 28, 2010

Access to manage AdWords Campaign Experiments (ACE) has been introduced through the ExperimentService as part of the v201008 version of the AdWords API. Now you are able to configure split test experiments for a campaign through the API. A split test experiment lets you more precisely measure the impact of changes to keywords, bids, ad groups, and placements before you apply them to all auctions. This reduces guesswork and lowers the potential risk. For common usage scenarios and more details, check out this blog post and the AdWords Help Center.

Lets get hands on with the code and see how to use ACE via the AdWords API. The following code snippets are available as part of the Perl client library.

Creating your experiment

You start by defining your experiment, which includes creating the experiment, attaching it to a campaign, setting its start time, end time, and percentage split. You then send an add operation through a service mutate call.

# Create experiment.
my $experiment = Google::Ads::AdWords::v201008::Experiment->new({
  campaignId => $campaign_id,
  name => "Interplanetary Experiment #" . POSIX::strftime("%s", localtime),
  queryPercentage => 10,
  startDateTime => POSIX::strftime("%Y%m%d %H%M%S", localtime)

# Create operation.
my $experiment_operation =
      operator => "ADD",
      operand => $experiment

# Add experiment.
my $result = $client->ExperimentService()->mutate({
  operations => [$experiment_operation]

# Valuable for ValueTrack usage
my $experiment_id = $experiments->get_entries()->[0]->get_id();
my $control_id = $experiments->get_entries()->[0]->get_controlId();

In the last few lines of code, experiment id and control id are extracted from the just-created experiment. These values are important for use with the ValueTrack tag used for campaign tracking and analytics since they uniquely identify which split each click is coming from. For details on using the ValueTrack tag with ACE please consult the AdWords Help Center.

Defining your experimental changes

Now lets apply some bid changes to an existing ad group and assign it to both the experimental and the control splits by using the flag named experimentDeltaStatus. Applying changes to other parts of your campaign are very similar to the following example, refer to the AdGroupExperimentData and the BiddableAdGroupCriterionExperimentData objects in documentation for more information about the experimental changes that can be applied to ad groups and criteria respectively. It is also worth to mention that new ad groups and new criteria can be added to your campaign experiment executing add operations and setting the experimentData to your new objects. You can also check a variety of experiment examples which we included in client libraries.

# Set ad group for the experiment.
my $ad_group = Google::Ads::AdWords::v201008::AdGroup->new({
  id => $ad_group_id

# Create experiment bid multiplier rule that will modify ad group bid for the
# experiment.
my $bid_multiplier = 
          maxCpcMultiplier => Google::Ads::AdWords::v201008::BidMultiplier->
                multiplier => 1.5

# Set experiment data to the ad group.
my $experiment_data =
      experimentId => $experiment_id,
      experimentDeltaStatus => "MODIFIED",
      experimentBidMultipliers => $bid_multiplier

# Create operation.
my $operation = Google::Ads::AdWords::v201008::AdGroupOperation->new({
  operand => $ad_group,
  operator => "SET"

# Update ad group.
$experiments = $client->AdGroupService()->mutate({
  operations => [$operation]

Deciding to promote or discard your experiment

After you’ve assessed the performance impact of the experimental changes, you can promote or delete the experiment. The following example shows you how to promote your experiment, effectively applying all experimental changes to 100% of your campaign traffic.

# Set experiment's status to PROMOTED.
my $experiment = Google::Ads::AdWords::v201008::Experiment->new({
  id => $experiment_id,
  status => "PROMOTED"

# Create operation.
my $experiment_operation =
      operator => "SET",
      operand => $experiment

# Update experiment.
my $result = $client->ExperimentService()->mutate({
  operations => [$experiment_operation]

Promoting an experiment applies all changes in the experimental split to your campaign. All control only elements become paused. Everything else running in both control and experiment splits continues running as normal.

If you don’t like the performance impact you see with the experiment, you can delete it by sending a mutate operation with the experiment status set as DELETED. Deleting an experiment will effectively discard any changes and additions assigned to the experimental split.

Like other products in beta, ACE has some core features still undergoing active development. Reporting is one area that’s getting special attention. Currently, getting performance data segmented by experiment and control splits is not supported through the AdWords API. Until it’s available, you can pull click and conversion data for each split from a tracking system using ValueTrack tags, as described above. Alternatively, experiments can be implemented so that every ad group is either control only or experiment only. You can then aggregate results for each campaign split using each ad group’s experimentDeltaStatus and check for statistically significant differences. A final interim solution is for users to log into the AdWords UI to check segmented performance stats.

If you have any questions about how to use this service we’ll be happy to address them on the forum. Have fun experimenting.

- David Torres, AdWords API Team

New codes and content in the documentation

Thursday, September 23, 2010

We’ve been hard at work updating the existing documentation and adding new resources. Here are some of the recent changes:

All of the code lists are available in CSV format to make it easier to integrate into your applications.

We’re always looking for new ways to improve our documentation, so if you have any ideas, let us know on the forum.

- Eric Koleda, AdWords API Team

Announcing Four AdWords API workshops

Friday, September 17, 2010

Join the AdWords API engineering team for a day of hacking on the latest features. Events will be held in the following cities:

  • London, September 28th
  • Hamburg, September 30th
  • San Francisco, October 7th
  • New York, October 12th
In addition to answering all of the questions you can ask us, we’ll be presenting technical deep dives of:
  • The new CustomerSyncService (Change History)
  • AdWords Campaign Experiments
  • The new TrafficEstimatorService
  • The completely rewritten (forthcoming) Java Client Library
  • Migrating from v13 to v2010 reports
  • New Ad Extensions and Product Ads
All events will have the same agenda, will run from 10:00 AM until 5:00 PM (local time), and will be geared towards software developers.

Seats are limited. For more information and to register, visit:

-- Aaron Karp, AdWords API Team

Discover v201008: TrafficEstimatorService upgrade

Wednesday, September 15, 2010

The TargetingIdeaService is a powerful tool for generating new keyword ideas and getting statistics about how those keywords perform globally. However, for more personalized estimates of how a keyword may perform in your account, the TrafficEstimatorService can be used. While this service was previously only available in the legacy v13 version of the AdWords API, it’s now available in v201008 with some slight changes.

Estimate Requests

While the v13 service provided separate methods for getting keywords estimates with and without an ad group or campaign context, the v201008 version has been simplified to use just a single get() method. This means that KeywordEstimateRequest objects must always be wrapped in AdGroupEstimateRequest and CampaignEstimateRequest objects, even if you don’t want to use the features those objects offer. Keep in mind though that specifying contextual information in estimate requests, especially the ids of existing ad groups and campaigns, can lead to more accurate estimates and is recommended when possible.

The CampaignEstimateRequest object allows you to set or override the targeting options for the estimation using the targets field. While this field accepts an array of any target type only the following are currently supported: LanguageTarget and GeoTarget, which itself is limited to only CountryTarget, CityTarget, MetroTarget, and ProvinceTarget. More information about the behavior of targeting is available here.

The following PHP example code demonstrates how to build up the estimate requests for three new keywords in a new ad group with a default bid of $1, in a new campaign that targets users in the US who speak English.

  // Create keywords. Up to 2000 keywords can be passed in a request.
  $keywords = array();
  $keywords[] = new Keyword('mars cruise', 'BROAD');
  $keywords[] = new Keyword('cheap cruise', 'PHRASE');
  $keywords[] = new Keyword('cruise', 'EXACT');

  // Create a keyword estimate request for each keyword.
  $keywordEstimateRequests = array();
  foreach ($keywords as $keyword) {
    $keywordEstimateRequest = new KeywordEstimateRequest();
    $keywordEstimateRequest->keyword = $keyword;
    $keywordEstimateRequests[] = $keywordEstimateRequest;

  // Create ad group estimate requests.
  $adGroupEstimateRequest = new AdGroupEstimateRequest();
  $adGroupEstimateRequest->keywordEstimateRequests = $keywordEstimateRequests;
  $adGroupEstimateRequest->maxCpc = new Money(1000000);
  $adGroupEstimateRequests = array($adGroupEstimateRequest);

  // Create campaign estimate requests.
  $campaignEstimateRequest = new CampaignEstimateRequest();
  $campaignEstimateRequest->adGroupEstimateRequests = 
  $campaignEstimateRequest->targets = array(new CountryTarget('US'),
      new LanguageTarget('en'));
  $campaignEstimateRequests = array($campaignEstimateRequest);

  // Create selector.
  $selector = new TrafficEstimatorSelector();
  $selector->campaignEstimateRequests = $campaignEstimateRequests;

Estimated Statistics

While the v13 KeywordEstimate object contained both the minimum and maximum estimated statistics, it has been split into a min and max StatsEstimate object in the v201008 version. This object bundles together the estimated average CPC, average position, clicks and total cost. To get values similar to those returned by the Traffic Estimator web interface you will need to get the mean of the min and max estimates.

The following code shows how to get the estimates for the selector created above and display the results.

  // Get traffic estimates.
  $result = $trafficEstimatorService->get($selector);

  // Display traffic estimates.
  if (isset($result)) {
    $keywordEstimates =
    for ($i = 0; $i < sizeof($keywordEstimates); $i++) {
      $keyword = $keywordEstimateRequests[$i]->keyword;
      $keywordEstimate = $keywordEstimates[$i];

      // Find the mean of the min and max values.
      $meanAverageCpc = ($keywordEstimate->min->averageCpc->microAmount
          + $keywordEstimate->max->averageCpc->microAmount) / 2;
      $meanAveragePosition = ($keywordEstimate->min->averagePosition
          + $keywordEstimate->max->averagePosition) / 2;
      $meanClicks = ($keywordEstimate->min->clicks
          + $keywordEstimate->max->clicks) / 2;
      $meanTotalCost = ($keywordEstimate->min->totalCost->microAmount
          + $keywordEstimate->max->totalCost->microAmount) / 2;

      printf("Results for the keyword with text '%s' and match type '%s':\n",
          $keyword->text, $keyword->matchType);
      printf("  Estimated average CPC: %d\n", $meanAverageCpc);
      printf("  Estimated ad position: %.2f \n", $meanAveragePosition);
      printf("  Estimated daily clicks: %d\n", $meanClicks);
      printf("  Estimated daily cost: %d\n\n", $meanTotalCost);
  } else {
    print "No traffic estimates were returned.\n";

Checking Keyword Traffic

The v13 service included a checkKeywordTraffic() method that could be used to determine if a keyword would get any traffic at all. This method has been removed from the v201008 service, but information about the search volume for a keyword can be obtained by using the TargetingIdeaService and requesting attributes such as AVERAGE_TARGETED_MONTHLY_SEARCHES, GLOBAL_MONTHLY_SEARCHES, or TARGETED_MONTHLY_SEARCHES.

If you have any questions about how to use this service we’ll be happy to address them on the forum.

- Eric Koleda, AdWords API Team

Introducing AdWords API version v201008

Tuesday, September 14, 2010

Today, we’re announcing a new version of the AdWords API: v201008. Following up on our release of v201003, this version includes many requested features, as well as TrafficEstimatorService and ReportDefinitionService (now out of beta). These two services will replace their v13 counterparts. While we’re not starting the sunset countdown for the v13 TrafficEstimatorService and ReportService just yet, we’d like to give you a heads-up that these services will be shut down in the first half of 2011. We’ll announce specific dates on this blog in the near future.

Here’s the list of what’s new in version v201008:

  • Reports: Now out of beta, the ReportDefinitionService service has what you need to receive detailed reporting for your AdWords accounts. With this, the rates for ReportDefinitionService have also been updated. Support for cross-client reports is expected in the next version of the API.
  • Traffic Estimates: An all-new version of the TrafficEstimatorService that will replace the existing v13 service.
  • Product Ads: Includes both Product Extensions and Product Listing Ads that feature rich product information, such as a product image, directly in your ads.  Note that you’ll need to use the AdWords web interface to link your campaigns with your Google Merchant Center account. We’ll add this feature to the API in an upcoming version. Also note that Product Listing Ads are not yet available to all AdWords users.
  • AdWords Campaign Experiments: Accurately test and measure changes to your keywords, bids, ad groups and placements by running split tests. Learn more
  • Ad group bid simulator (bid landscapes): Get bid simulator data at the ad group level with two sets of simulations: estimated results for changing the ad group default bid and estimated results for applying a single bid to all the keywords within that ad group. Learn more
  • Enhanced CPC: Dynamically raise or lower your Max. CPC bids to acquire more conversions at or below your current CPA. Learn more
  • Partial failure support for AdGroupCriterionService (beta): This functionality has been frequently requested by developers over the years and we’re excited to launch it in beta while we continue to develop and improve upon it. We’ll launch partial failure support for other key services in upcoming versions of the API.
We are also working on a couple of other new features that will be added to v201008 in the coming weeks.

The AdWords API team is working hard to bring you the features you’ve been asking for and we’re excited to hear what you think about the v201008 version of the API. We encourage you to start working with this new version and share your feedback with us on the developer forum.

Posted by Jason Shafton, Product Marketing Manager

Discover v201003: Using Ad Sitelinks

Thursday, September 09, 2010

Ad Sitelinks is a feature for search-based ads that allows you to extend the value of your existing AdWords ads by providing additional links to specific, relevant content deep within your website. Rather than sending all users to the same landing page, Sitelinks can provide up to 4 additional links for the user to choose from, as shown below.

(View larger image)

By providing users with more options, you can create richer, more relevant ads that improve the value of your brand terms and other targeted keywords. You can learn more about Sitelinks in the AdWords Help Center.

Using Ad Sitelinks in AdWords API v201003
Sitelinks is supported starting with the v201003 version of the AdWords API. Sitelinks is implemented as campaign ad extensions, and can be managed using the CampaignAdExtensionService. Keep in mind that each campaign can have only one CampaignAdExtension containing a SiteLinkExtension. This means that prior to adding Sitelinks to your campaign, you should check if the campaign already has one, and remove it if does. The C# code snippet below shows how to retrieve the campaign ad extension containing active Sitelinks for a given campaign.

private long? GetActiveSitelinkExtension(long campaignId) {
 long? siteLinkExtensionId = null;

 // Get the campaign ad extension containing sitelinks.
 CampaignAdExtensionSelector selector = new CampaignAdExtensionSelector();
 selector.campaignIds = new long[] { campaignId };
 selector.statuses = new CampaignAdExtensionStatus[] {
CampaignAdExtensionStatus.ACTIVE };

 CampaignAdExtensionPage page = campaignExtensionService.get(selector);
 if (page != null && page.entries != null) {
   foreach (CampaignAdExtension extension in page.entries) {
      if (extension.adExtension is SitelinksExtension) {
         siteLinkExtensionId =;
 return siteLinkExtensionId;

If GetActiveSitelinkExtension returns null, then you can remove the existing SitelinkExtension as shown below.

private SitelinksExtension RemoveActiveSitelinkExtension(
   long campaignId, long siteLinkExtensionId) {
 CampaignAdExtension campaignAdExtension = new CampaignAdExtension();
 campaignAdExtension.campaignId = campaignId;
 campaignAdExtension.adExtension = new AdExtension(); = siteLinkExtensionId;

 CampaignAdExtensionOperation operation = new CampaignAdExtensionOperation();
 operation.@operator = Operator.REMOVE;
 operation.operand = campaignAdExtension;
 CampaignAdExtensionReturnValue retVal =
     campaignExtensionService.mutate(new CampaignAdExtensionOperation[] {
         operation });
 if (retVal != null && retVal.value != null && retVal.value.Length > 0 &&
     retVal.value[0].adExtension is SitelinksExtension) {
   return (SitelinksExtension) retVal.value[0].adExtension;
 } else {
   return null;

You can now add new siteLinks as shown below.

private SitelinksExtension AddSitelinks(long campaignId, Sitelink[]
   siteLinks) {
 SitelinksExtension siteLinkExtension = new SitelinksExtension();
 siteLinkExtension.sitelinks = siteLinks;

 CampaignAdExtension campaignAdExtension = new CampaignAdExtension();
 campaignAdExtension.adExtension = siteLinkExtension;
 campaignAdExtension.campaignId = campaignId;

 CampaignAdExtensionOperation operation = new CampaignAdExtensionOperation();
 operation.@operator = Operator.ADD;
 operation.operand = campaignAdExtension;

 CampaignAdExtensionReturnValue retVal =
     campaignExtensionService.mutate(new CampaignAdExtensionOperation[] {
         operation });
 if (retVal != null && retVal.value != null && retVal.value.Length > 0) {
   return retVal.value[0].adExtension as SitelinksExtension;
 } else {
   return null;

The following snippet puts it all together.

Sitelink siteLink1 = new Sitelink();
siteLink1.displayText = "Birthday Flowers";
siteLink1.destinationUrl = "";

Sitelink siteLink2 = new Sitelink();
siteLink2.displayText = "Deal of the day";
siteLink2.destinationUrl = "";

long? linkId = GetActiveSitelinkExtension(campaignId);
if (linkId != 1) {   
 RemoveActiveSitelinkExtension(campaignId, linkId);
AddSitelinks(campaignId, new Sitelink[] { siteLink1, siteLink2});

As always, the latest API unit costs for adding, removing or or retrieving Sitelinks is available in the AdWords API rate sheet under the CampaignAdExtensionService.

We've included support for Sitelinks in each of our client libraries to help you get started, so please try it out and share your feedback with us on the forum.

-- Anash P. Oommen, AdWords API Team

AdWords Downtime: September 11, 10am-2pm PDT

Thursday, September 09, 2010

We'll be performing routine system maintenance on Saturday, September 11 from approximately 10:00am to 2:00pm PDT. You won't be able to access AdWords or the API during this time frame, but your ads will continue to run as normal.

- Eric Koleda, AdWords API Team 

Google Instant and the AdWords API

Wednesday, September 08, 2010

Today, we announced the launch of Google Instant, a new interface that shows relevant results while the user types. To read more about how this change affects AdWords advertisers, please visit the Inside AdWords Blog.

With this change, you might notice some fluctuations in impression volume.  For example, you may find that certain keywords receive significantly more or less impressions moving forward.  Despite any change in impressions, Google Instant is intended to increase the quality of the clicks on your ads and therefore boost your overall campaign performance.

For more information about Google Instant, visit our Help Center.

-- Posted by Jason Shafton, Product Marketing Manager