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
POSTrequest to https://adwords.google.com/api/adwords/reportdownload/v201109. The
clientCustomerIdheader specifies the client for which this report is being run. The
Authorizationheader contains the authorization information for downloading the report. If you are using ClientLogin as the authorization method, this header takes the form
If you are using OAuth, the header takes the form
Authorization: GoogleLogin auth=AUTH_TOKEN_HERE
Authorization: OAuth OAUTH_SIGNATURE_HERE
returnMoneyInMicrosheader 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
developerTokenheader contains your AdWords API developer token. The Report Definition is written in XML format and is provided in the
__rdxmlparameter of the
POSTbody. The request should be encoded in
You may also use the
GETmethod instead of
POSTto 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
POSTexample. However, we recommend using
GETrequests 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.
When downloading AdHoc reports, the AdWords API server responds with
HTTPcode 200 and report in the response body. In case of an error, one of the two different
HTTPresponse 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
HTTPresponse 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.