Update on AdWords API v201101 sunset dates

We recently launched AdWords API v201101, including details on the deprecation timeline for previous versions.

We would like to clarify the sunset dates for the following versions and services:

• API v13 TrafficEstimatorService: we’re making changes to the TrafficEstimatorService algorithm in v201101 and v201008 to bring you more accurate estimates. We will therefore be sunsetting API v13 TrafficEstimatorService on June 30, 2011. See more on updates to the traffic estimates algorithm on the Inside AdWords Blog.

• API v200909, v201003, v201008, and API v13 ReportService - the sunset date will be four months from when MCC cross-client reports go live. We will post to this blog as soon as MCC cross-client reports becomes available.

For help migrating to v201101, review the resources on the AdWords API code site, including release notes and AdWords API client libraries. If you have any questions please post them on the AdWords API forum.

UPDATE as of Jul 14, 2011

We want to clarify that the sunset that will happen four months from when MCC cross-client reports go live will include ALL services in the following versions:

• v200909
• v201003
• v201008

In addition to v13 ReportService.

The ONLY functional services remaining will be:

• All v201101 services
• v13 AccountService

Posted by Katie Miller, AdWords API Team

Discover v2009: Error handling

As with any programming system, error handling is a critical part of the AdWords API as well. In v13, we used to describe every error by its own error code. While this was simple and handy, the API provided less additional information about the error itself. In v2009, we decided instead to use error types with additional fields to describe the specifics of each error. The new error handling system gives you the type of error (e.g. PolicyViolationError), the cause of error (e.g. the editorial policy that was violated), the field that triggered the error and so forth. In this blog post, I'll cover the v2009 error handling in detail, with focus on v2009 synchronous services.

Error handling in v13 and v2009 APIs

To show the difference in error handling between v13 and v2009, consider the following v13 code to create a campaign.

try {
  AdWordsUser user = new AdWordsUser();
  CampaignInterface service = 
      (CampaignInterface) user.getService(AdWordsService.V13.CAMPAIGN_SERVICE);
  Campaign campaign = new Campaign();
  campaign.setName("New campaign");
  campaign.setBudgetPeriod(BudgetPeriod.Daily);
  campaign.setBudgetAmount(50L);
  campaign = service.addCampaign(campaign); 
} catch (ApiException e) {
  for (ApiError error : e.getErrors()) {  
    System.out.println("There is an error on argument " + error.getIndex() 
        + ". Error code is " + error.getCode() 
        + ", details are \"" + error.getDetail() 
        + "\", field is " + error.getField()); 
  }
}

This code generates the following output:

There is an error on argument 0. Error code is 34, details are "Money amount less than CurrencyMinCpc.", field is budget.

The same code in v2009 is given below:

try {
  user = new AdWordsUser();
  CampaignServiceInterface service = (CampaignServiceInterface) 
      user.getService(AdWordsService.V200909.CAMPAIGN_SERVICE);
  Campaign campaign = new Campaign(); 
  campaign.setName("New campaign");
  campaign.setBiddingStrategy(new ManualCPC());
  campaign.setBudget(new Budget(BudgetBudgetPeriod.DAILY, 
      new Money(null, 50L), BudgetBudgetDeliveryMethod.STANDARD));
  CampaignOperation operation = new CampaignOperation();
  operation.setOperator(Operator.ADD);
  operation.setOperand(campaign);
  campaign = service.mutate(new CampaignOperation[] {operation}).getValue()[0];
} catch (ApiException e) {
  for (ApiError error : e.getErrors()) { 
    System.out.println("There is an error on argument " + error.getFieldPath() 
        + ".");
    if (error instanceof BudgetError) {  
      BudgetError budgetError = (BudgetError) error;
      System.out.println("Reason is " + budgetError.getReason());
    }
  }
}

The code generates the following output:

There is an error on argument operations[0].operand.budget. Reason is NON_MULTIPLE_OF_MINIMUM_CURRENCY_UNIT.

As shown in the code above, v2009 returns an error object derived from ApiError, with an appropriate error reason that gives more insight into why the error occurred. This allows you to write a switch-case to handle error categories and reasons that are significant for your program more elegantly than in v13. Also, the list of exceptions raised by a service are available along with the service documentation. For instance, all the exceptions that can possibly be raised by CampaignService are listed at http://code.google.com/apis/adwords/v2009/docs/reference/CampaignService.html#errors

Retrieving the violating field using FieldPath

FieldPath is another useful item you get from a v2009 error. FieldPath stores the OGNL path to the field that caused the violation. OGNL stands for Object-Graph Navigation Language; it is an expression language for getting and setting properties of objects. You can use it as a debugging aid while developing your application, retrieve the value of the violating field, etc. For instance, the following code shows how to retrieve the value of budget that caused the error using the library from opensymphony.

try {
  OgnlContext ognlContext = new OgnlContext(); 
  ognlContext.put("operations", operations);
  Object value = Ognl.getValue(error.getFieldPath(), ognlContext);
  System.out.println("Violating field is " + error.getFieldPath() 
      + " and value is " + value);  
} catch (OgnlException e) { 
  e.printStackTrace();
}

This code will print the output as

Violating field is operations[0].operand.budget and value is 50.

In case you are interested in just the index of the violating operation, you can evaluate it using a simple regex as follows:

public static int getOperationsIndex(String ognl) {
  String OPERATIONS_INDEX_REGEX = "^operations\\[(\\d+)\\]";
  Matcher m = Pattern.compile(OPERATIONS_INDEX_REGEX).matcher(ognl);
  if (m.find()) {
    return Integer.parseInt(m.group(1));
  } else {
    return -1;
  }
}

Validating API calls using validateOnly

AdWords API also allows you to validate your API calls to see if the request will generate any errors or not. You can validate any API call by setting the validateOnly SOAP header to true and making the API call as usual. If the request contains errors, you will get ApiError objects. If the request is fine, no errors are thrown, and the API call doesn't perform any action either. In addition to providing a way to validate your API calls, validateOnly is significantly cheaper than normal calls. You can refer to the rate sheet to calculate how many API units a validateOnly call will cost you. For more details on how to use validateOnly headers, you can refer to our blog post here

In our next blog post, we will cover how v2009 error handling works in BulkMutateJobService. We've included support for error handling in all of our client libraries to help get you started, so please try it out and share your feedback with us on the forum.

-- Anash P. Oommen, AdWords API Team

14 days left to migrate to v2009

If you haven’t migrated to the new v2009 AdWords API yet you have only 14 days left to do so. Developers that don’t migrate by April 22 will experience failed calls to most v13 services. The only v13 services that will remain accessible are AccountService, ReportService, and TrafficEstimatorService.

Have questions about migrating? Review the per-call migration guide, visit the developer forum and follow us on Twitter.

– Jason Shafton, Product Marketing Manager

Alert: 30 days before major v13 sunset

Attention AdWords API developers: you now have just 30 days to migrate your application to the new AdWords API. On April 22, most v13 services will be sunset. We announced version v200909 on October 22, 2009 and told you that in six months we would sunset most v13 services. If you have not begun migrating your application to v200909, it’s very important that you start right away.

Be sure to follow us on Twitter for the latest news, tips, and tricks about the AdWords API and please post your migration questions to the Developer Forum.

– Jason Shafton, Product Marketing Manager

60 days left to migrate to v200909

Last month we reminded you that on April 22 most v13 services will be turned off. In 60 days, the following v13 services will no longer be accessible:
CampaignService
AdGroupService
CriterionService
AdService
InfoService
KeywordToolService
SiteSuggestionService

These three v13 services will continue to be accessible until the same functionality is available in the new AdWords API later this year:
AccountService
TrafficEstimatorService
ReportService
Don't worry, we won't sunset these services until their replacements have been available for at least four months.

To help you migrate your application, we've demonstrated how your code can simultaneously use the remaining v13 services and the new v2009 services. Here are some examples: Java, .NET, Python, and Ruby.

Please continue to post your migration questions and feedback on the Developer Forum.

– Jason Shafton, Product Marketing Manager

v2009 Hack Day Video Preview

Our recent AdWords API Hack Days in San Francisco and New York were a huge success, filled with presentations, question and answer sessions, and one-on-one coding help. We were glad to see that many developers have already started the migration to the v2009 API, and these events were a great way to kick off the process for those just getting started. Don't forget that most v13 services will be turned off on April 22.

We will be posting videos of the presentations on YouTube over the coming weeks, starting this week with Migrating from v13 to v2009 by Adam Rogal. The presentation gives an overview of the suggested migration process, provides some tips and tricks, and includes live coding examples.

This video is the first of many, and if you'd like to get the full experience there is still space available in our upcoming Paris Hack Day. Get more information and register for an upcoming Hack Day.



Best,
- Eric Koleda, AdWords API Team

100 days until major v13 sunset

In October of last year we launched the v200909 API and shared with you that the majority of v13 services would be turned off on April 22 of this year. This is a reminder to our developers that less than 100 days are left before most v13 services will be turned off.

As of April 22, 2010, the following v13 services will no longer be accessible:
CampaignService
AdGroupService
CriterionService
AdService
InfoService
KeywordToolService
SiteSuggestionService

The AccountService, TrafficEstimatorService, and ReportService v13 services will continue to be accessible because they are not yet available in the v2009 API. In the coming months, we'll announce the launch dates for these services in the v2009 API and corresponding sunset dates for the v13 services.

Want to learn more about migrating your application to the v2009 API? Review the side-by-side differences between v13 and v2009. Try out the code examples in these client libraries: Java, .NET, Python, Ruby, and PHP. You can also learn more from our Discover v2009 series of blog posts.

As we go into the last 100 days before migration to v2009, please continue to ask us your questions and share your feedback on the AdWords API Developer Forum.

–- Jason Shafton, Product Marketing Manager

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: 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

Discover v2009: Getting ideas with TargetingIdeaService

As we announced recently, KeywordToolService and SiteSuggestionService were among the services deprecated to make way for their v2009 successors. In designing their new replacement, we sought to create a unified experience similar to our other v2009 services. The new TargetingIdeaService combines queries for both keywords and placements into one service with a common method to retrieve TargetingIdeas. In this blog post, we will discuss querying the new service for ideas to aid you in shaping your campaign and how you would go about migrating from v13.

Similar to our other new services, the TargetingIdeaService uses a get method along with a selector to query for both keywords and placements. There are currently two types of requests that can be made - ideas and stats. We will discuss querying for ideas here and save stats for a future blog post.

There are 4 main parameters of the selector which are used for querying ideas:

• requestType - the request type equal to IDEAS or STATS.
• ideaType - the type of idea to get equal to KEYWORD or PLACEMENT.
• searchParameters - contains both the seed parameters as well as filters to apply to the results, which are specific to the ideaType.
• requestedAttributeTypes - narrows the attributes returned to only those requested, which are specific to the searchParameters and ideaType.

Using these 4 parameters, you will have a vast degree of customization for your results. Each of these parameters and their limitations is best described in the TargetingIdeaSelector documentation page. We will now walk through a few examples on how you would replicate v13's functionality, and how you can improve upon it with v2009.

Replicating KeywordToolService.getKeywordVariations

In v13, you would typically retrieve a list of keyword variations from the getKeywordVariations method. Below is a snippet of code which replicates the basic functionality of this method.

    Keyword keyword = new Keyword();

    keyword.setText("cheap airline tickets");

    keyword.setMatchType(KeywordMatchType.BROAD);

    LanguageTarget language = new LanguageTarget();

    language.setLanguageCode("en");

    CountryTarget country = new CountryTarget();

    country.setCountryCode("US");

    TargetingIdeaSelector selector = new TargetingIdeaSelector();

    selector.setRequestType(RequestType.IDEAS);

    selector.setIdeaType(IdeaType.KEYWORD);

    selector.setSearchParameters(new SearchParameter[] {

      new RelatedToKeywordSearchParameter(null, new Keyword[] {keyword}),

      new LanguageTargetSearchParameter(null, new LanguageTarget[] {language}),

      new CountryTargetSearchParameter(null, new CountryTarget[] {country})});

    selector.setPaging(new Paging(0, 6));

The results you get back may resemble keywords like:

    cheap airline tickets/EXACT

    cheap airline tickets/BROAD

    cheap airline tickets/PHRASE

    airline tickets/BROAD

    airline tickets/EXACT

    airline tickets/PHRASE

As you can see, since the results were not filtered, they weren't that great. You can improve the results by specifying additional search parameters in the selector:

    // Using the same keyword from above, filter by removing the original

    // keyword, by keeping the same match type, and by only choosing

    // "long-tail" keywords.

    new ExcludedKeywordSearchParameter(null, new Keyword[] {keyword}),

    new KeywordMatchTypeSearchParameter(null,

        new KeywordMatchType[] {keyword.getMatchType()}),

    new CompetitionSearchParameter(null,

        new CompetitionSearchParameterLevel[] {

          CompetitionSearchParameterLevel.LOW}),

The results are now more interesting:

    legion air tickets/BROAD

    air tram tickets/BROAD

    block air tickets/BROAD

    sheap air tickets/BROAD

    cheap airfare tracker/BROAD

    cheap airfare forum/BROAD

You will notice now that the results are beginning to give you a better idea on how you would shape your campaign. We will now explore placement functionality, formerly found within the SiteSuggestionService.

Replicating SiteSuggestionService.getSitesByUrls

In v13, you would typically retrieve a list of similar websites to expand your content network campaign using the getSitesByUrls method. Below is a snippet of code which replicates the basic functionality of this method.

    String[] urls = new String[] {"made-up-tickets-site.com",

        "made-up-ticket-seller.com"};

    LanguageTarget language = new LanguageTarget();

    language.setLanguageCode("en");

    CountryTarget country = new CountryTarget();

    country.setCountryCode("US");

    TargetingIdeaSelector selector = new TargetingIdeaSelector();

    selector.setRequestType(RequestType.IDEAS);

    selector.setIdeaType(IdeaType.PLACEMENT);

    selector.setSearchParameters(new SearchParameter[] {

      new RelatedToUrlSearchParameter(null, urls, true),

      new PlacementTypeSearchParameter(null,

         new SiteConstantsPlacementType[] {SiteConstantsPlacementType.SITE}),

      new LanguageTargetSearchParameter(null, new LanguageTarget[] {language}),

      new CountryTargetSearchParameter(null, new CountryTarget[] {country})});

    selector.setPaging(new Paging(0, 6));

The results you get back may resemble placements like:

    made-up-tickets-site.com

    made-up-tickets-site.com::Search Results,Top center

    made-up-ticket-seller.com

    made-up-ticket-seller.com::Homepage,Bottom right

    another-made-up-ticket-seller.com

    yet-another-made-up-ticket-seller.com

Though you now have a better idea of which placements you would like to pursue, you may still have difficulty ranking your results. We will finally discuss pulling additional attributes to help better evaluate targeting ideas.

Requesting more attributes

The TargetingIdeaService adds new functionality not previously found in v13 to help you better understand your results. For example, you may notice from the results above that "another-made-up-ticket-seller.com" looks interesting, but does not offer much information beyond its URL. To investigate, you can request that a sample URL for each placement be supplied to determine if this is the right website for you. You can do this by adding the SAMPLE_URL attribute to the requestedAttributeTypes parameter:

    // PLACEMENT is added to associate with SAMPLE_URL.

    selector.setRequestedAttributeTypes(new AttributeType[] {

      AttributeType.PLACEMENT, AttributeType.SAMPLE_URL});

When the results are returned, you will then be able to visit each sample URL to investigate the location and quality of placement yourself, something that was not previously possible with v13's SiteSuggestionService. All available attributes are listed in the AttributeType documentation page.

As we've shown in this blog post, there are many new and exciting uses for the TargetingIdeaService. We've included examples of using this service in all of our client libraries to help get you started, so please jump in and let us know of any feedback you may have on our forums.

-- Adam Rogal, AdWords API Team