Downloading reports for lots of client accounts

Friday, October 28, 2011

Reporting has changed significantly with v201109. We’d like to take this opportunity to discuss how to download reports for lots of clients simultaneously. To download reports for a large number of client accounts, we recommend requesting the download of these reports simultaneously.

We recommend requesting no more than 10 reports concurrently and to use one thread for each concurrent download. If for some reason the report download fails, we recommend you retry after a short wait. The length of the wait should increase with the number of times the request has been tried (known as Exponential Backoff). This backoff algorithm helps prevent making too many requests to the server in a short period of time.

You should check the specific reason the download failed and only retry if it was a transient error (such as exceeding the rate limit) instead of retrying if the report definition XML was invalid. The HTTP Status of the response provides useful information:
  • HTTP Status 500 indicates there is a transient server side issue and the request can be retried after a delay. We retrying no more than 5 times for any given report.
  • HTTP Status 400 indicates there was a problem with the request (or the report itself) and retrying will not help.
  • HTTP Status 200 means the report download was successful.
With v201109 you should use Ad Hoc reports to download new reports. With this new feature, there is no need for stored ReportDefinitions. The XML describing a Report Definition is sent directly with report download. A developer token is required, but the API call accrues no costs (report downloads are now free!).

Another benefit of downloading reports in this fashion is you get data more quickly than with legacy cross-client reports. As soon as a report download succeeds, you can start processing the data by putting it into a database or performing further logic on the results.

We hope this discussion of best practices will help you with writing report download code in the future. We’ve published a reference implementation showing how to do this in java here. If you have any questions about downloading reports, you can ask us on the forum.

, AdWords API Team