Discover v2009: New Examples in Client Libraries

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:

• Java
• .NET
• Python
• Ruby
• PHP

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

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
..........xmlns="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

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

Discover v2009: Setting ad parameters with the AdParamService

In a blog post yesterday we introduced ad parameters, a new AdWords feature that allows for dynamic insertion of numeric and currency values into ads while retaining ad history. To manage ad parameters, a new service was added to the v200909 API: the AdParamService.

In the example introduced earlier, you own a business selling antique cups that wants to add price and inventory information to your ads. To leverage ad parameters you create a text ad like:

and you configure the following ad parameters on your keywords:

keyword	param1	param2
antique cups	$80	18

A user searching for "antique cups" would will see the following ad text:

Text ads, even those with ad parameter placeholders, can be created using the normal methods of the AdGroupAdService. The AdParamService is only used for setting ad parameter values on keywords. This service allows for the getting and setting of AdParam objects, which contain the ad group ID and criterion ID for the target keyword, the insertion text, and the parameter index.

For example, to set the ad parameters for "antique cups" we would use the following PHP code (using the AdWords API PHP Client Library):

$adParam1 = new AdParam($adGroupId, $criterionId, '$80', 1);

$adParam2 = new AdParam($adGroupId, $criterionId, '18', 2);

$operation1 = new AdParamOperation($adParam1, 'SET');

$operation2 = new AdParamOperation($adParam2, 'SET');

$adParams = $adParamService->mutate(array($operation1, $operation2));

Existing ad params can be selected by ad group ID or by ad group ID and criterion ID. To get the ad parameters set above we would run the following:

$selector = new AdParamSelector(array($adGroupId), array($criterionId));

$adParamPage = AdParamServiceTest::$service->get($selector);

Some key points to remember about the ad parameters and the AdParamService are:

• Ad parameters are set on keywords, not ads.
• Ad parameters can only accept numerical and currency values, but the default text of the placeholder in the ad can be any string.
• The length of the default text in the placeholder contributes to the total length of the line in the ad, but the curly braces, parameters name, and colon do not.
• Ad parameters are 1-based indexed, meaning the two parameters are "1" and "2".
• The AdParamOperation should always use the "SET" operator, even when you are setting the parameters for the first time.

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

More Dynamic Ads with Ad parameters

We're excited to announce that a new feature of the v2009 API, called Ad parameters, is now available. Ad parameters enable you to change numeric information (for example: prices, discount percentages, etc.) within your text ad, while keeping the history and statistics associated with the ad.

Here's a hypothetical scenario illustrating how Ad parameters might help you make your ads more specific and appealing:

Let's say that you sell high-end antique tea cups on your website and it is important for you to qualify users before they even click on your ads. After running some tests, you have found that you can attract serious buyers to your website by including a starting price in your ads. You also want to include the number of varieties of tea cups you currently have in stock, to make your ad appear fresh.

You would like to update your ad text via the AdWords API in response to price and availability fluctuations within your inventory system, but you don't want to lose the statistics associated with your ad. Ad parameters can solve this problem for you.

With Ad parameters, you can specify an ad like this:

Notice that you can specify default values for param1 and param2 within the ad text. You need to set dynamic numeric values for param1 and param2 at the keyword level via the AdParamService of the v2009 API.

On a certain day, if your inventory of tea cups starts at $80 with 18 designs in stock, you can set these values for the relevant keywords within your ad group, as follows:

keyword	param1	param2
antique cups	$80	18

A user searching for "antique cups" subsequently will see the following ad:

For more information on using Ad parameters, be sure to check out our Discover v2009 blog post on this topic (coming soon).

Finally, a few notes about this feature:

• Ad parameters can only be updated via the AdWords API. Updates are not currently supported in AdWords Editor or in the AdWords interface
• You can specify at most two parameters
• While the default value of the parameters (specified within the ad text) can be non-numeric, the dynamic value of the parameters (specified via the AdWords API) must always be numeric. Currency symbols are allowed
  
• As usual, your ads must comply with our AdWords Advertising Policies

-- Shreyas Doshi, Product Manager, AdWords API

Version v200906 beta will be shut down on February 2, 2010

The v200906 API, which we released as a limited beta in June 2009, will be shut down on February 2, 2010. The recently-launched v200909 API is a full replacement for v200906 and it adds substantial additional functionality. For most developers, the migration from v200906 to v200909 will be just a matter of updating the version in the namespace and re-compiling/building their application.

If you are using one of our client libraries, the changes required for migration will be as easy as

• Java
• Change import com.google.api.adwords.v200906.cm.CampaignServiceInterface; to import com.google.api.adwords.v200909.cm.CampaignServiceInterface;
• Change CampaignServiceInterface campaignService = user.getService(AdWordsService.V200906.CAMPAIGN_SERVICE); to CampaignServiceInterface campaignService = user.getService(AdWordsService.V200909.CAMPAIGN_SERVICE);
• DotNet
• Change using com.google.api.adwords.v200906; to using com.google.api.adwords.v200909;
• Change namespace com.google.api.adwords.samples.v200906 to namespace com.google.api.adwords.samples.v200909
  
• Change CampaignService service = (CampaignService) user.GetService(AdWordsService.v200906.CampaignService); to CampaignService service = (CampaignService) user.GetService(AdWordsService.v200909.CampaignService);
• Python
• Explicitly set version, campaign_service = client.GetCampaignService(version='v200909')
• Ruby
• Change campaign_srv = adwords.get_service('Campaign', 200906) to campaign_srv = adwords.get_service('Campaign', 200909)
• Perl
• Change version in types, Google::AdWords::v200906::Types::SomeType to Google::AdWords::v200909::Types::SomeType
  
• PHP
• Defaults to v200909

As always, the AdWords API team is available to help ensure a smooth transition to the new v200909 API. Feel free to post your questions on the forum. Finally, to learn about the exciting new features of v200909, we encourage you to check out the weekly posts in our Discover v2009 series.

--Stan Grinberg, AdWords API Team

AdWords Downtime: November 14th, 10am-2pm PDT

We'll be performing routine system maintenance on Saturday, November 14th 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.

Best,
-Eric Koleda, AdWords API Team