Discover v201003: Using Ad Sitelinks

Introduction
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 = extension.adExtension.id;
         break;
      }
   }
 }
 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();
 campaignAdExtension.adExtension.id = 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 = "http://www.flowers.com/birthday";

Sitelink siteLink2 = new Sitelink();
siteLink2.displayText = "Deal of the day";
siteLink2.destinationUrl = "http://www.flowers.com/deals/today";

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

Discover v201003: Learn from the past with the Bid Simulator

Have you ever wondered how your keywords could have performed with a different bid? The bid simulator feature released last year allows you to do just that. Using data from the last seven days, it calculates the impressions, clicks, and cost your keywords could have received if different maximum CPC bids were used. This information was previously only exposed in the AdWords web interface, but is now available in the v201003 version of the API with the BidLandscapeService.

The getBidLandscape() method is used to retrieve the bid simulation results, also known as bid landscapes. You can use the selector to filter the results by campaign, ad group, or keyword ID. For example, to retrieve the results for a single keyword using the PHP client library you would use the following code:

  // Create selector.
  $selector = new CriterionBidLandscapeSelector();

  // Create id filter.
  $idFilter = new BidLandscapeIdFilter();
  $idFilter->adGroupId = $adGroupId;
  $idFilter->criterionId= $keywordId;
  $selector->idFilters = array($idFilter);

  // Get bid landscape for keyword.
  $bidLandscapes = $bidLandscapeService->getBidLandscape($selector);

The returned BidLandscape contains a series of LandscapePoints, each of which represents a single simulation for that keyword. It isn’t possible to configure which bids are used in the simulations, but the points are chosen automatically by the system to give an interesting range of data. Each landscape point contains the impressions, clicks, and cost that the keyword could have received at that bid. In addition, it contains the field marginalCpc, which contains the incremental cost-per-click (ICC) at the simulated bid. More information on ICC values and how you can use them is outlined in a video by Google's Chief Economist, Hal Varian. Please note that depending on the recent performance of the keyword, only some of this information may be populated in the landscape point.

Bid simulations are currently only available for campaigns that use ManualCPC bidding and target the GOOGLE_SEARCH or SEARCH_NETWORK networks. Additional restrictions are listed in the AdWords Help Center. The bid simulations are performed automatically in regular intervals, and new keywords or those with no impressions in the last seven days won’t have any associated results. No errors will be thrown when this happens, but the response will not contain a BidLandscape for that keyword.

Example code using the BidLandscapeService is available in the client libraries. Please post any questions about this service to the forum. Additional information about the bid simulator can be found in the Help Center.

- Eric Koleda, AdWords API Team