I think I must have written a similar tutorial several times over the years, but it's time to post another one as the method to extract reports from AdWords has just changed once again. The latest version of the AdWords API (v201109) was released a few days ago with an announcement there's a new way to download reports. I've been checking out the changes and playing with the code, so read on if your interested in how it's now working.
What's Changed in the Latest Version of the API?
When the AdWords API was first released, reports were available via the AdWords Report Center and worked asynchronously: they needed to be scheduled then polled in a similar way to the current [adCenter API reporting solution][link-14]. Then, in 2009, Google released a completely revised version of the API with new reporting, which coincided with the change in AdWords to put reporting in the Campaigns tab instead of the Report Center. This version required developers to first define a report using the
ReportDefinitionService, then download it via a HTTP request. The actual download was free, but the call to the
ReportDefinitionService still used API quota.
Now, from October 2011, we no longer need to define a report first using the
ReportDefinitionService; instead, reports can be defined and downloaded using a single HTTP call. The
ReportDefinitionService has been depreciated and replaced with an AdHoc reports service that enables you to simply send the
ReportDefinition to the AdWords server in the body of a HTTP POST request, then wait for the report to be produced and downloaded.
This new method is advantageous because it uses less resources, so allows applications to download more than one report at a time; moreover, the actual AdWords API SOAP interface is no longer used at all, which finally makes downloading reports completely free of charge!
[link-14]: "adCenter API Reports"
Using the AdHoc Reporting Service
I've just downloaded a few of the latest versions of the Client Libraries, but, for today at least, there aren't any updates to use the new service. Don't let that deter you from digging into this great new feature though; it's not too difficult to construct the request yourself then post it using cURL or something similar.
Composing the Report Definition
The first thing you need to do is specify the parameters of the report you want to create. This is done using a similar XML syntax to the definitions in the
ReportDefinitionService, but without the extraneous SOAP bits: Define a
ReportDefinition using an XML fragment with the
<reportDefinition> tag as the root node. The elements that you can use to describe a report request can be found on the ReportDefinition page in the API documentation.
Although the documentation might seem daunting at first without a client library, a simple trick to generate the XML fragment is to use the
ReportDefinitionService from the old version of the API, then log the SOAP that gets generated and use it in your code. Here's an example I've generated to get started with:
Requesting the AdHoc Report
OK, now we have a basic report request it needs to be submitted to the AdWords API server. The URL to use is:
https://adwords.google.com/api/adwords/reportdownload/[API Version], where
[API Version] needs to be replaced with the current release of the API, so should currently be:
https://adwords.google.com/api/adwords/reportdownload/v201109. Your POST request needs to include the following headers:
- Authorization - A standard Google Accounts login token obtained from the
- clientCustomerId - The numerical ID of the account for which the report is being produced: For example, “123-456-7890”.
Here's some example PHP code that uses cURL to get an
authToken from the
Once you've got your token it needs to be placed into the
Authorization header along with the
ReportDefinition needs to be sent in the
Now we can send this off and should get our report back: