Just recently Google made the new AdWords API 2009 sandbox and documentation available to the public. Some information about it is also in the AdWords API Blog.

I have started to toy around with it. I have written a mayor part of the current AdWords API integration for the company I work for, so it’s best to be prepared for the mayor overhaul Google has done with this new API implementation. Here is a quick overview and some thoughts I have about it.

Authentication

Google seems to unify the use of their APIs with a common login interface: the Account Authentication API. You can make a HTTPS Post Request to the API and use your Google credentials to get an Auth token. This token then will be used to access the functionalities of the API.

I think it is good to unify different kinds of API authentication into a single login service. I just hope that it is stable enough to endure all the load from not just one kind of service but every piece of Google API which will make use of it.

Accessing the Sandbox

I created some example codes (will publish some code in another article soon) to access the Google AdWords Sandbox. At first I had some difficulties because I don’t just use the examples from Google, I created my own kind of library to access the API. That lead to the assumption that I can always use the SOAP end url as namespace – which was wrong because the namespace for the request XML has to be

https://adwords.google.com/api/adwords/cm/v200902

while the actual xml request is being sent to

https://adwords-sandbox.google.com/api/adwords/cm/v200902/....

When sending the wrong namespace the API returns a server error, but no detailed error code about what kind of error occured. I hope Google will improve their error reporting there.

Get & Mutate – the new methods of getting data and manipulating data

Past versions of the AdWords API left the impression of a patchwork API. This time you basically have two functions:

get

Getting data is simple: just build an xml which contains all the parameters you need and send it to the API.

Example:

<get xmlns="https://adwords.google.com/api/adwords/cm/v200902">
 <selector>
  <StatsSelector>
   <campaignIds></campaignIds>
  </StatsSelector>
 </selector>
</get>

This piece of xml tells the API (assuming the header information with the AuthToken, sorry not posting that one here ) to retrieve all the campaigns in the account. You can limit the campaigns by telling it to only include certain campaign IDs (filling the StatsSelecter/campaignIds node with subnodes containing the actual IDs).

mutate

Mutate is the method to create and manipulate data structures in the API.

Example:

<mutate xmlns="https://adwords.google.com/api/adwords/cm/v200902">
 <operations>
  <operator>ADD</operator>
  <operand>
   <name>Test Campaign - 1242726211</name>
   <status>PAUSED</status>
   <budget>
    <period>DAILY</period>
    <amount>
     <currencyCode>EUR</currencyCode>
     <microAmount>1000000</microAmount>
    </amount>
    <deliveryMethod>STANDARD</deliveryMethod>
   </budget>
  </operand>
 </operations>
</mutate>

It tells the API to create a new campaign in the account defined by the client email in the header (again not posted here). The additional OPERATOR tells what kind of operation (ADD, REMOVE, SET). After that all the necessary data for the operation are being added.

Final words (for now)

I think the new API is very clean and straight forward, with a new authentication method. The problems I currently see is the amount of work necessary to migrate applications based on the existing API v13 to the new v2009, but if people are using frameworks like APIlity or one of the other provided libraries, it is safe to assume that new versions will be available soon after the release to make a smooth upgrade.

I am looking forward to work closely with the new API.