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