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

Location, location, location: so goes the mantra of the real estate business. Although, in this constantly connected world where people are carrying Internet-enabled mobile devices more and more, location is important to every retail business. Often, users are looking for the closest provider of a service or a product, rather than your specific business.

So how can you get your business on the map? In the past, we had an entirely separate ad type: the Local Business Ad (LBA). But with the new AdWords interface and AdWords API v2009, we have a much simpler solution available: Location Extensions. These allow you to easily add location information to any text ad in your campaigns.

Let's look at an example. Say your business has a few branches open throughout the city, and you want to add location information to your existing ads. The first step is to retrieve the location of each branch, based on its address. That means making a call to the new GeoLocationService, which uses a process known as "geocoding."

// Create address object.
Address address = new Address();
address.setStreetAddress("123 Easy Street");
address.setCityName("Mountain View");
address.setProvinceCode("US-CA");
address.setPostalCode("94043");
address.setCountryCode("US");
// Get location information from the service.
GeoLocationSelector selector = new GeoLocationSelector();
selector.setAddresses(new Address[] {address});
GeoLocation[] locations = geoLocationService.get(selector);
location = locations[0];

The next step is to use the CampaignAdExtensionService to add a location extension to your campaign using the information returned by the GeoLocationService:

// Create LocationExtension.
LocationExtension locationExtension = new LocationExtension();
locationExtension.setAddress(location.getAddress());
locationExtension.setGeoPoint(location.getGeoPoint());
locationExtension.setEncodedLocation(location.getEncodedLocation());
locationExtension.setCompanyName("Foo");
locationExtension.setPhoneNumber("650-555-5555");
locationExtension.setSource(LocationExtensionSource.ADWORDS_FRONTEND);
// Create CampaignAdExtension.
CampaignAdExtension campaignAdExtension = new CampaignAdExtension();
campaignAdExtension.setCampaignId(campaignId);
campaignAdExtension.setAdExtension(locationExtension);
// Add location extension to the campaign.
CampaignAdExtensionOperation operation = new CampaignAdExtensionOperation();
operation.setOperand(campaignAdExtension);
operation.setOperator(Operator.ADD);
CampaignAdExtensionOperation[] operations =
new CampaignAdExtensionOperation[] {operation};
CampaignAdExtensionReturnValue result =
campaignAdExtensionService.mutate(operations);

Multiple location extensions can be added to the same campaign, and by default each ad in the campaign will be associated with every location. When serving your ad the AdWords system will choose the most relevant location to display to the user. Do keep in mind that there is a limit of 9 manually created location extensions per campaign. Alternatively you can have AdWords pull addresses directly from your Local Business Center (LBC) account, which isn't subject to the same restriction. For now, LBC synchronization is only supported via the AdWords interface, but the next API version will include support for it as well.

Of course, not all ads are created equal, and you may want some ads to target only a single store. In that case, the solution is to create an Ad Extension Override for the one location extension that you do want to associate with that ad:

// Create ad extension override for the specified ad Id.
AdExtensionOverride adExtensionOverride = new AdExtensionOverride();
adExtensionOverride.setAdId(adId);
// Create ad extension object using specified campaign ad extension Id.
// This will be the only extension used for the specified ad.
AdExtension adExtension = new AdExtension();
adExtension.setId(campaignAdExtensionId);
adExtensionOverride.setAdExtension(adExtension);
// Add the override.
AdExtensionOverrideOperation operation = new AdExtensionOverrideOperation();
operation.setOperand(adExtensionOverride);
operation.setOperator(Operator.ADD);
AdExtensionOverrideOperation[] operations =
new AdExtensionOverrideOperation[] {operation};
AdExtensionOverrideReturnValue result =
adExtensionOverrideService.mutate(operations);

If you're looking for more detailed examples, be sure to check the 'examples' directory for the client library of your choice.

Extending your ads with location information will enable them to be shown on Google.com and other properties (such as Google Maps), bringing you closer to your customers' local searches. That way they'll not only find out about your offers, they'll actually be able to find you.

-- Sérgio Gomes, AdWords API Team