AdHoc reports is one of the new features we introduced in v201109 of the AdWords API. AdHoc reports are free, synchronous and don’t require a stored report definition. This blog post explains this new feature and covers the best practices.
Downloading the report
AdHoc reports utilizes plain HTTP POST requests to generate reports synchronously from the AdWords API server. A raw HTTP request to download the reports is shown below:
POST /api/adwords/reportdownload/v201109 HTTP/1.1
HOST: adwords.google.com
clientCustomerId: XXX-XXX-XXXX
Content-Type: application/x-www-form-urlencoded
developerToken: XXXX
Authorization: GoogleLogin auth=XXX
returnMoneyInMicros: true
Content-Length: XXXX
__rdxml=URL_ENCODED_DEFINITION_XML
As shown, the report is downloaded by making a
POST request to
https://adwords.google.com/api/adwords/reportdownload/v201109. The
clientCustomerId header specifies the client for which this report is being run. The
Authorization header contains the authorization information for downloading the report. If you are using
ClientLogin as the authorization method, this header takes the form
Authorization: GoogleLogin auth=AUTH_TOKEN_HERE
If you are using
OAuth, the header takes the form
Authorization: OAuth OAUTH_SIGNATURE_HERE
The
returnMoneyInMicros header tells the server whether to return money values in micros or not. This is true by default; if set to false, money values are downloaded in actual currency format. The
developerToken header contains your AdWords API developer token. The Report Definition is written in XML format and is provided in the
__rdxml parameter of the
POST body. The request should be encoded in
application/x-www-form-urlencoded or
multipart/form-data format.
You may also use the
GET method instead of
POST to download reports by sending your request to
https://adwords.google.com/api/adwords/reportdownload/v201109?__rdxml=URL_ENCODED_REPORT_DEFINITION_XML with the same headers as in the
POST example. However, we recommend using
POST over
GET since
GET requests are more likely to incur URL length limit errors.
Creating definition xml
A Report Definition corresponds to the serialized form of the
ReportDefinition type. For instance, a Report Definition that downloads an AdGroup performance report for the last 7 days in CSV format would look like this:
<reportDefinition>
<selector>
<fields>CampaignId</fields>
<fields>Id</fields>
<fields>Impressions</fields>
<fields>Clicks</fields>
<fields>Cost</fields>
<predicates>
<field>Status</field>
<operator>IN</operator>
<values>ENABLED</values>
<values>PAUSED</values>
</predicates>
</selector>
<reportName>Custom Adgroup Performance Report</reportName>
<reportType>ADGROUP_PERFORMANCE_REPORT</reportType>
<dateRangeType>LAST_7_DAYS</dateRangeType>
<downloadFormat>CSV</downloadFormat>
</reportDefinition>
Details about the supported report types and their field are available at
http://code.google.com/apis/adwords/docs/appendix/reports.html.
Error codes
When downloading AdHoc reports, the AdWords API server responds with
HTTP code 200 and report in the response body. In case of an error, one of the two different
HTTP response code may be returned:
1. HTTP Status code is 400: This error occurs when the AdWords API server throws an API error. When this happens, the error message will be returned in the server response body. You need to examine your report definition XML and server response body and fix any errors before retrying the call. The response body would look like
!!!2|||-1|||Error message here???
An easy way to parse the error message is to match it against the regex pattern
"\!\!\!([^\|]*)\|\|\|(.*)"
2. HTTP Status code is 500: This error implies that the server faced an issue while generating the report. Chances are that this is a temporary error and may go away if you retry the call after waiting for 30 seconds. However, if you get this error even after five retries, you should skip the download and report the issue on the
forum.
Using the client libraries
All of the
client libraries support AdHoc reports, and takes care of details like making requests with the right HTTP headers and encoding, constructing authorization headers, handling the
HTTP response codes, etc. For instance, the
DownloadAdHocReports.cs code example shows how to download AdHoc reports using AdWords API .NET library:
Support for cross-client reports
As mentioned in an
earlier blog post, AdHoc reports do not support cross-client reports. If you wish to run reports against many clients, you can refer to this
blog post for details.
We hope this blog post will help you use this new feature effectively. As usual, If you have any questions about downloading reports, you can ask us on the
forum or our upcoming
live Hangouts with the Developer Relations team.
--Anash P. Oommen, AdWords API Team
