Discover v2009: Location Extensions

Wednesday, December 23, 2009


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

​AdWords API v2009 Hack Days

Thursday, December 17, 2009


​Have you been putting off migrating to v2009? Not sure where to start? Been way too busy? Well it's time to jump start your v2009 development with some in-person help from Google. Join us in San Francisco (January 7th) or New York (January 14th) for a full day of non-stop v2009 hacking.

To keep things interesting throughout the day, we'll do some coding demos of the cool things you can do with v2009 that weren't possible in v13, like asynchronous calls, dynamic ad parameters, and more.

Non-engineers beware! This is a developer-only event, and there will be no content or activities for attendees who don't plan to write code.

Space is very limited, and signups are on a first come, first serve basis. We ask that you limit attendance to two people per company. If you are based in Europe, please don't register yet, as a separate event for you is in the works and will be announced shortly.

More information and the signup form are available here: http://sites.google.com/site/v2009hackdays/

- Aaron Karp, AdWords API Team

Discover v2009: New Examples in Client Libraries

Friday, December 11, 2009


Our Discover v2009 series has focused on introducing you to the new services and objects that come with the update to the API. And while we hope these posts have been informative we know there is nothing like running a code example yourself to bring the concepts to life. That's why we've spent the last few weeks completely re-hauling the examples in our client libraries to provide a more complete set of sample code to try out. The following client libraries now have over 30 examples for the v200909 version of the API:

If you haven't tried out the v2009 API there is no better time to get started. With our client libraries you can go from download to making requests in under five minutes, and the built-in logging and utility classes make learning v2009 a breeze. Many client libraries (Java, .NET, Python, and Ruby) even come bundled with v13 support, allowing you to take advantage of new v2009 features without having to update your entire application at once.

As always, we are here to answer your questions, collect feedback, and assist with migration to the v2009 API.

- Eric Koleda, AdWords API Team

Discover v2009: validateOnly header

Wednesday, December 09, 2009


While making AdWords API calls, a common task that you have to perform as a developer is to ensure that the SOAP requests you make to the server are valid. This includes validation in terms of parameters required for an API call, as well as ensuring that your ads and criteria are in accordance with Adwords policies. AdWords API v200909 introduces a new RequestHeader field named
validateOnly to help you validate your API calls.

While making an API call in AdWords API v200909, if you include the validateOnly header in an API call, the servers will perform validation on the API parameters, but will not perform the requested operation like creating campaigns, ads, etc. For instance, the relevant parts of a SOAP request and response xml to validate a call to CampaignService::mutate() are given below.

SOAP Request

<soap:Header>
..<RequestHeader xmlns="https://adwords.google.com/api/adwords/cm/v200909">
....<!-- other headers here -->
....<validateOnly>true</validateOnly>
--</RequestHeader>
</soap:Header>

SOAP Response (Success)

<soap:Body>
..<mutateResponse xmlns="https://adwords.google.com/api/adwords/cm/v200909"/>
</soap:Body>

SOAP Response (Failure)

<soap:Body>
..<soap:Fault>
....<faultcode>...</faultcode>
....<faultstring>...</faultstring>
....<detail>
......<ApiExceptionFault
..........x
mlns="https://adwords.google.com/api/adwords/cm/v200909">
........<message>...</message>
........<ApplicationException.Type>ApiException</ApplicationException.Type>
........<errors.xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
...........xsi:type="BudgetError">
..........<fieldPath>operations[1].operand.budget</fieldPath>
..........<trigger/>
..........<ApiError.Type>BudgetError</ApiError.Type>
..........<reason>NON_MULTIPLE_OF_MINIMUM_CURRENCY_UNIT</reason>
........</errors>
........<!-- More errors here. -->
......</ApiExceptionFault>
....</detail>
..</soap:Fault>
</soap:Body>

As you can see, if the request were successful, then you would get an empty mutateResponse, which shows that the request was validated successfully, but no campaign was created. If the request had errors, then you would get back an APIException, and the errors field will contain a collection of ApiError objects, one for each error encountered on validation. The fieldPath contains the OGNL field path to identify cause of error, whereas other fields like reason and trigger gives you more information why the error occurred. For instance, the failed response xml shown above had an error in the second operation. It triggered a BudgetError since its budget was not a multiple of the minimum currency unit.

You can also use validateOnly headers to check if a batch of ads or criteria has any policy errors. AdWords API v13 exposed two methods, checkAds and checkCriteria to check a batch of ads or criteria for policy errors. The following java code snippet shows how you can use validateOnly headers to perform policy checks on ads, similar to checkAds.

AdGroupAdServiceInterface adGroupAdService = (AdGroupAdServiceInterface) ....user.getValidationService(AdWordsService.V200909.ADGROUP_AD_SERVICE);

TextAd textAd = new TextAd();
textAd.setHeadline(
"Luxury Cruise to MARS");
textAd.setDescription1(
"Visit the Red Planet in style.");
textAd.setDescription2(
"Low-gravity fun for everyone!!!"); // Force a policy violation.
textAd.setDisplayUrl("www.example.com");
textAd.setUrl(
"http://www.example.com");

AdGroupAd
adGroupAd = new AdGroupAd();
adGroupAd.setAd(textAd);
adGroupAd.setAdGroupId(Long.parseLong(
"INSERT_ADGROUP_ID_HERE"));
adGroupAd.setStatus(
AdGroupAdStatus.ENABLED);

AdGroupAdOperation
operation = new AdGroupAdOperation();
operation.setOperator(
Operator.ADD);
operation.setOperand(adGroupAd);

try
{
..AdGroupAdReturnValue result =
......adGroupAdService.mutate(new AdGroupAdOperation[] {operation});

..// No policy violations found. Add the ads using the non-validating service.
..adGroupAdService = (AdGroupAdServiceInterface)
......user.getService(AdWordsService.V200909.ADGROUP_AD_SERVICE);
..result = adGroupAdService.mutate(new AdGroupAdOperation[] {operation});
}
catch (ApiException e) {
..for (ApiError error: e.getErrors()) {
....if (error instanceof PolicyViolationError) {
......PolicyViolationError policyError = (PolicyViolationError) error;
......// Handle your policy violations here.
....}
..}
}


Finally, the use of validateOnly header will cost you only 0.05 units per validated item. All costs are rounded to the next greater or equal integer (i.e., both .05 and .95 are rounded to 1). This way, you can validate your calls and fix the errors without wasting a lot of API units on a failed API call. We've included support for validateOnly in all of our client libraries to help get you started, so please try it out and let us know of any feedback you may have on our forum.

-- Anash P. Oommen, AdWords API Team

Discover v2009: New Ad Types

Wednesday, December 02, 2009


The release of the new v200909 included a number of improvements and new features. Among these additions are new ad types: DeprecatedAd, LocalBusinessAd, MobileImageAd, and TemplateAd, which are all part of the AdGroupAdService.

DeprecatedAd:
The idea behind deprecated ads is to have a consistency in returning ads that are no longer supported. For example, if your ad group has a Click To Call ad (this ad format was deprecated on Dec. 3, 2007) and you try to fetch this particular ad via API, we will return it as a DeprecatedAd type and allow you to delete it. This is a quick and easy way for cleaning up your outdated inventory using API.

Note that deprecated ads can be deleted, but can not be created.

MobileImageAd:
This is a new format of ads that can appear on mobile websites. When users click on your ad, they will be sent to your mobile webpage. Below is a Python snippet of code that shows how to add a mobile image ad for T-Mobile and Verizon carriers in US.

  operations = [{
    'operator': 'ADD',
    'operand': {
      'type': 'AdGroupAd',
      'adGroupId': '123456789',
      'ad': {
        'type': 'MobileImageAd',
        'markupLanguages': ['HTML'],
        'mobileCarriers': ['T-Mobile@US', 'Verizon@US'],
        'image': {
          'dimensions': [{
            'key': 'SHRUNKEN',
            'value': {'width': '192', 'height': '53'}
          }],
          'name': 'image_192x53.jpg',
          'data': MOBILE_IMAGE_DATA
        },
        'url': 'http://www.mywebsite.com/mobile',
        'displayUrl': 'www.mywebsite.com'
      }
    }
  }]
  ad_group_ad_service.Mutate(operations)

LocalBusinessAd:
This ad type represents a legacy local business ad format. When edited via the AdWords interface, the legacy ad will be converted to create a new text ad with ad-level location extension and the original local business ad will be deleted. The location extension itself is created at campaign level with the association for that ad at the ad-level. The usage of the LocalBusinessAd format will allow you to perform the conversion via API of your existing legacy local business ads into the new location extensions. We plan to spend more time talking about the new location extension format in one of our upcoming posts.

Note that local business ads can be deleted or paused/unpaused, but can not be modified.

TemplateAd:
The template ad is an easy way to add new formats to the AdWords interface. In a nutshell, we come up with an idea for an ad format, a set of required input data elements is created, and that's all. There is now a new ad format that is available in AdWords.

Note that template ads run only on content network.

To help you get started, we've included support for these and other ad types in our
client libraries. As always, we are here to answer your questions, collect feedback, and assist with migration to v200909 of the AdWords API.

Keep an eye on the blog for the next part of the "Discover v2009" series.

--Stan Grinberg, AdWords API Team