Now Available: AdWords API Local Database Sync

Today, we're pleased to announce the AdWords API Local Database Sync project. The scripts that make up the project can be used to schedule reports using the AdWords API, store the results in a local database (using SQLite), and then run queries against the database.

If you recall, one of the recommendations listed on our recent list of "AdWords API: Top Ten Practices" extolled the virtues of maintaining your AdWords account information in a local database, and using the AdWords API to keep that information up to date. Querying a local database offers speed and cost advantages compared to making repeated AdWords API calls when answering questions like "How many active AdWords campaigns do I have across all my accounts?" Maintaining a local database with historical information can also help you answer questions that the AdWords API alone can't, like "Which keywords were updated in my accounts during the past week?" Now, with the AdWords API Local Database Sync you can answer these questions.

Here are some of the technical details: The scripts are written in Python, and make use of the SOAPpy libraries for accessing the AdWords API SOAP service. The Python code is written against the dbapi2 database API, and by default it will use the SQLite implementation and store the report data in a SQLite database file on the local file system. It's possible to swap out the SQLite libraries for another database library that supports the dbapi2 interface.

While some developers may have already written their own in-house AdWords database synchronization code, we wanted to provide a standalone, open source solution for those developers who don't yet have such a system in place. We're also hopeful that the code serves as a helpful example of scheduling and parsing AdWords API reports, and that even folks who are already maintaining their own databases will get something out of the project.

Visit the project's home on Google Code and give it a try!

Cheers,
-Jeffrey Posnick, AdWords API Team

Common issues that lead to SOAP faults (Part III)

Welcome to part 3 of the series of posts that will give tips and tricks on how to deal with SOAP issues. As a SOAP-based web service, AdWords API can be easy to make calls to. At the same time, it can sometimes be difficult to debug the SOAP faults. In our previous episodes, we discussed how an invalid developer token or a missing SOAP header can lead to SOAP faults. Today we cover missing operations and methods.

Operation Doesn’t Exist

 

Developers may also come across the error “The request body did not contain an operation or the specified operation does not exist. (Error code 116)."

 

• The most obvious reason for this error is that the method you called does not exist in the webservice you called. This could happen due to a mistyped method name (e.g. GetAccountInfo instead of getAccountInfo) in your SOAP request. This could also happen because you sent your SOAP request to the wrong web service.

 

• You could also get this error if you mentioned a wrong namespace against your method. For example, For example, the following call to https://adwords.google.com/api/adwords/v12/AccountService will cause the error:

 

  <soap:Body>
    <getAccountInfo xmlns="https://adwords.google.com/api/adwords/v11"/>
  </soap:Body>

AdWords API will ignore all nodes that do not match its namespace, and trigger the error in this case.

Next time, we'll explore errors that result from failed validations and policy errors.

Common issues that lead to SOAP faults (Part II)

Welcome to part 2 of the series of posts that will give tips and tricks on how to deal with SOAP issues. As a SOAP-based web service, AdWords API can be easy to make calls to. At the same time, it can sometimes be difficult to debug the SOAP faults. In the last episode, we discussed how using an invalid Developer token could lead to SOAP faults. Now, below, we'll talk about dealing with missing headers in your SOAP requests.

No Header

New developers are also likely to get the error "The client request did not contain a [header type] header." (Error code 1, 2, 8...).

• If you get this error, the most obvious reason is that you haven’t mentioned a required SOAP header in your request XML. Each SOAP request requires the following headers: "email", "password", "developerToken", "applicationToken", and "useragent". In addition, you may also need to include the "clientEmail" or "clientCustomerId" header, depending on the API method you’re calling.

• Another possible reason for getting this error is that you have mentioned all the required headers, but have provided the wrong XML namespace in your XML. For example, if you send the following header request to https://adwords.google.com/api/adwords/v12/AccountService, you will get the error that email header was missing.

<soap:Header>

   <email xmlns="https://adwords.google.com/api/adwords/v11">INSERT_YOUR_ EMAIL _HERE</email>

   <!--more nodes-->

</soap:Header>

• The best way to fix this issue is to turn on SOAP XML logging and check your SOAP request XML for missing header values. A well-formed SOAP request message looks something like this:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   <soap:Header>

     <applicationToken xmlns="https://adwords.google.com/api/adwords/v12">INSERT_APPLICATION_TOKEN_HERE</applicationToken>

     <developerToken xmlns="https://adwords.google.com/api/adwords/v12">INSERT_DEVELOPER_TOKEN_HERE</developerToken>

     <email xmlns="https://adwords.google.com/api/adwords/v12">INSERT_YOUR_EMAIL_HERE</email>

     <password xmlns="https://adwords.google.com/api/adwords/v12">INSERT_YOUR_PASSWORD_HERE</password>

     <useragent xmlns="https://adwords.google.com/api/adwords/v12">INSERT_YOUR_USERAGENT_HERE</useragent>

   </soap:Header>

   <soap:Body>

     <getAccountInfo xmlns="https://adwords.google.com/api/adwords/v12"/>
   </soap:Body>

</soap:Envelope>

 

If you are using AdWords API code samples, then the headers are mentioned within the source code itself. If you are using an AdWords API client library, then the headers are often mentioned in an appropriate configuration file. The .NET client library uses app.config, the Java and Ruby client libraries use adwords.properties file and APIlity uses authentication.ini to store the header values. The Python library uses auth.pkl. You can inspect these files to see if the required headers are mentioned in the configuration files. Finally, all the client libraries have an appropriate constructor, which can accept the required headers and initialize the library, so you might want to inspect the code that initializes the library as well.

Next time, we'll explore errors related missing API operations and methods.



--Anash Oommen, AdWords API Team

Common issues that lead to SOAP faults (Part I)

As a SOAP-based web service, AdWords API can be easy to make calls to. At the same time, it can sometimes be difficult to debug the SOAP faults. We thought it would be useful to go over the most common SOAP faults that you might encounter while making AdWords API calls. To keep things fresh, we also decided to try a new format -- a series of posts. Hope you like it!

Invalid Developer Token

The most common error, encountered by developers making API calls for the first time, is "The developer token is invalid." (Error code 42). There are couple of main reasons you may get this error.

• If this is your first time making the call, make sure that you’re making calls to the account in production environment (adwords.google.com) rather than the AdWords API sandbox (sandbox.google.com). API sample code is configured by default to send the requests to sandbox account and not production account. Thus, if you started programming using this code, this is the most likely reason for the error.

• Similarly, if you are using an AdWords API client library, they are also configured by default to send request to the AdWords API sandbox. If you are using Java, .NET or Ruby client libraries, make sure that you haven’t provided "alternateUrl" key as part of user credentials in the configuration file (adwords.properties or app.config). For Apility library, make sure that Use_Sandbox key is set as ‘No’ in settings.ini file. For python client library, make sure you haven't provided an argument server="'https://sandbox.google.com'" when initializing service class. Also, each library has an appropriate constructor which will accept the credentials as parameters while initializing the library. Make sure that you haven’t provided “alternateUrl” here as well. Finally, some libraries might provide utility functions (e.g. .NET client library provides useSandbox()) that will allow you to switch between production and sandbox accounts at runtime. Make sure that these functions are not called in your code.

• A less common, but more obvious, reason for this error is that the token in your code is invalid. The chance of this happening is low, since most developers copy their token from their MCC account. Nevertheless, it could happen if you’ve mistakenly swapped the application and developer tokens, or if you’ve reset the developer token in your account but forgotten to update your code. Double checking your code should help you spot the reason for the error.

Next time, we'll explore errors related to missing headers in SOAP requests. Keep an eye on the blog for upcoming posts.

--Anash Oommen, AdWords API Team

AdWords Downtime: September 13, 10am-2pm PDT

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

Cheers,
-Jeffrey Posnick, AdWords API Team

Your software on a diet!

Cutting API calories from your app

One of the questions we often get asked by developers is how to spend fewer API units; if you're not careful, you might end up wasting a lot unnecessarily. Thankfully, you should be able to curb your software's appetite with a few simple suggestions:

- Two ways to get there
Do you run a lot of campaigns across your client accounts? If so, you might want to schedule Campaign Performance reports instead of using the getCampaignStats method of the Campaign Service. Conversely, if you keep few campaigns, the second option is probably better.

- Bird's-eye view
Sometimes you just need to retrieve a big chunk of an account's data, with few details. If you've got a lot of campaigns, ad groups, ads, or keywords, it might be a good idea to schedule a Structure report instead. That will give you a nice list of what you're looking for in a much more scalable approach.

- Schedule once, run forever
If you often need the same report, you might want to consider scheduling a periodic report via the AdWords website. It will automatically get generated every day, every week, or every month, and
all you have to do is retrieve it with the Report Service methods.

- Look before you leap
Whenever you submit a new ad or criterion, you should always validate it first. It's true that the validation method has a cost too, but it's significantly smaller than the cost of failing the submission.

- Can I have the list?
After reading the previous item, you might be thinking that it's a good idea to only submit one item at a time. Actually, you have no benefit in doing so, because in a failed call you only get charged for the items that did in fact fail. You should always submit lists of items, since that's how our system is optimized to work -- give it a bunch of data and it will happily take care of it for you.

- Find the differences
A common mistake when updating items (ads, criteria, etc.) is to include items that haven't actually been changed. This will add to your costs, with no benefit! A simple way of making sure this doesn't happen is to keep two separate lists of items in your software: one before modification, and one after. Before submitting the changes to the service, just compare the two and remove the identical items.

- No one's looking for that
Keywords are what advertising on the search network is all about. If you have the right keywords, people will find you. If you don't, business will be slow. Consider for a moment how many poorly performing keywords you have. Every time you retrieve them, update them, or check their statistics via the API, you spend units. One very good way of saving units in the long run is to make sure that you go for the best, and skip the rest. One of the easiest ways of doing this is to use the Traffic Estimator Service before you add them, in order to get an idea of how much traffic those keywords would generate.

- Go play in the sandbox
Are you still developing your application, or trying out some new functionality? Well, no need to be spending any units. After all, playing should be free! We've got a sandbox ready for you to test your code during development which is free and open to anyone, so you can hack away without worrying about how many times you've tried to get that right.

- Check the price before you buy
Finally, you should keep in mind the cost of the various API methods, so that you don't run into any surprises after running your software. The latest rate sheet is always available at this page.


Have you come across any other useful tricks to keep API usage costs down? If so, share with others!

Cheers,
-Sérgio Gomes, AdWords API Team