AdWords API Developer Docs: Now in Chinese and Japanese!

It's easy to write code using the AdWords API in the programming language of your choice, thanks to all of our client libraries. But when it comes to written language, you're more constrained--our recent developer documentation has only been maintained in English.

We're happy to announce that this is no longer the case, and our Developer's Guide now features a Chinese and Japanese translation. If you're not automatically redirected to the appropriate language when you visit that page, use the popup menu in the upper right hand corner of the web page to switch to one of the supported languages.

Please note that only the v12 version of the Developer's Guide has been translated. We're working hard to get v13 translated as well, and hope that the v12 documentation proves useful for v13 developers--the majority of the documentation is the same between the two versions. We will be leaving the v12 documentation up on the site for an extended period of time.

We'll be releasing translations for additional languages in the future, so stay tuned for more updates!

--The AdWords API Team

AdWords Downtime: February 21, 10am-2pm PST

We'll be performing routine system maintenance on Saturday, February 21 from approximately 10:00am to 2:00pm PST. You won't be able to access AdWords or the API during this time frame, but your ads will continue to run as normal.

Cheers,
-Jeffrey Posnick, AdWords API Team

Sunsetting v12 on February 23, 2009

In accordance with our policy of sunsetting older versions of the AdWords API, we will turn off access to version 12 of the API on Monday, February 23, 2009. Version 13 of the API has been available for over four months now, and supports a number of new features. We hope that you've already taken the opportunity to upgrade your code.

The latest versions of the publicly available official Google client libraries all support version 13 of the API, so if you're using one of those, please check the relevant README file for information on how to switch from version 12 to 13.

As always, if you have any questions about the AdWords API or upgrading to our latest versions, you can check out our Frequently Asked Questions or ask them in our developer forum.

-- AdWords API Team

Keyword Match Type and the KeywordToolService

We first blogged about AdWords API v13's new keyword search volume info functionality back in November, and it remains a popular topic among developers. We've heard a number of follow-up questions about how the results from v13's KeywordToolService match up with the results available via the corresponding web application, especially when it comes to issues regarding keyword match type. There are two different scenarios in which you might want to specify match type when retrieving keyword variations, and hopefully the information in this blog post will clear up some confusion as to how the KeywordToolService supports that functionality.

One scenario involves giving a hint to the keyword variation service as to what kind of query you want to use as the seed. If you're calling getKeywordVariations(), you use the type attribute of the SeedKeyword object to do this. So, for example, if you want to generate variations based on a phrase match for "baseball bat", you'd specify "Phrase" for the type attribute and "baseball bat" for the text attribute of the SeedKeyword. If instead of a phrase match you were interested in generating keyword variations based on a broad match, you'd instead specify "Broad" for the type attribute. The important thing here is that the type attribute can affect the specific variations that are returned. In the "baseball bat" example, most of the variation keywords that are returned are the same for the two match types, but there are some differences. For example, the variation "baseball training bat" is only returned when you specify a Broad match type.

The options outlined above directly translate into using the web version of the tool and specifying two different match types for the source keyword. In the section in which you're instructed to "Enter one keyword or phrase per line", if you were to enter the literal text "baseball bat" (with quotes) you'd specify a Phrase match type. If you entered baseball bat (without quotes) you'd specify a Broad match type. (An Exact match type is expressed as [baseball bat], i.e. with brackets around the text.)

This distinction only applies to the getKeywordVariations() method of the KeywordToolService. getKeywordsFromSite() doesn't allow you to specify a match type for the source keyword because there is no source keyword; instead, you're passing in a specific URL to use as the source, and a match type would not make sense in that context.

The second scenario in which you might care about match type involves the search volume results for each SiteKeyword or KeywordVariation object that is returned from getKeywordsFromSite() and getKeywordVariations(). The web version of the tool provides a popup menu in the results area allowing you to select the match type you're interested in. When you choose a match type, it will update the search volume information of each suggested keyword accordingly. Unfortunately, there is currently no way to retrieve search volumes for different match types using the API's KeywordToolService methods. The search volumes in the results returned from the API should roughly correspond to what you'd see with the Broad setting for match type in the web tool, but retrieving search volumes for Phrase or Exact match types is not possible.

--Jeffrey Posnick, AdWords API Team

AdWords Downtime: January 10, 10am-2pm PST

We'll be performing routine system maintenance on Saturday, January 10 from approximately 10:00am to 2:00pm PST. You won't be able to access AdWords or the API during this time frame, but your ads will continue to run as normal.

Cheers,
-Jeffrey Posnick, AdWords API Team

A preview of 2009 AdWords API changes

The AdWords API team has been hard at work on some big improvements for 2009 that we're very excited to bring you. Although we're still working on the details, we wanted to give you a preview so you can plan your programming resources accordingly.

These fundamental changes will offer you some major advantages, as well as improve our API infrastructure:

• New calls features
  
• More operations in a single call: We're changing the way services are constructed so that you'll be able to accomplish more work per call. Specifically, operations will accept a variety of modifiers acting on elements across ad groups. For example, you'll be able to add, update, and delete keywords across ad groups, all within a single call.
• Asynchronous calls: We'll offer asynchronous calls, which will allow you to work with large sets of data faster and more easily. Instead of having to wait for our system to fully complete your request before you can make another one, you'll be able to make another call as soon as the API service confirms that it's received your previous call. No more waiting for large requests to be finished. (Synchronous methods will still be supported as well.)
• Partial failure acceptance: We plan to support partial failure, so large posts aren't rolled back due to a few errors. This allows you to keep moving forward with development and not have to re-do the same posts.
• Lower costs: We plan to directly reduce API units consumed for the new asynchronous methods, and are exploring other ways to improve the value you get from the AdWords API by lowering costs and/or quota use.
• Faster development: Our new codebase will allow us to expose new AdWords features faster, keeping the API more closely in line with the AdWords web interface. This will make it easier for you to keep your applications current and to take advantage of the latest AdWords advancements.

We expect to launch this new API version in the first half of 2009. Since we're introducing more changes than usual, we'll extend the normal sunset period for v13 to at least 6 months after the new version's launch. These new features, and others, are still in development, but we'll be giving you more details as soon as we have them in the new year.

Sincerely,

Doug Raymond
Product Manager, AdWords API

AdWords API Hostnames

Just a friendly heads-up to developers out there: when you send SOAP requests to the Production AdWords API service, you should be connecting to the adwords.google.com hostname. (Requests to the AdWords API Sandbox should be sent to sandbox.google.com.)

If you're using one of our client libraries or generate your own client code using the standard WSDL definitions then you should already be doing the right thing. Your requests will automatically be sent to a URL starting with https://adwords.google.com/api/adwords/. Our logs show that the overwhelming majority of incoming traffic falls into this category.

However, if you've gone out of your way to specifically send your traffic to a hostname other than adwords.google.com, or directly to a specific IP address, please note that they'll stop accepting AdWords API traffic in the near future. If you think that you might be sending to a non-standard hostname, then please take the time to remediate your code.