Reporting Basics

Reporting of performance data is an integral part of most AdWords API applications.

You can obtain a report with the performance data for an entire campaign. Or you can focus more narrowly, for example on the search queries which triggered your ad. See the documentation about report types to learn what options are available.

To obtain a report, your application needs to tell the AdWords server who you are, what type of report you want, your choice of download format, the name you want to give the report, and a few other things. All of this goes into the Report Definition, which your application sends to Google to initiate the download of a report.

Some statistics that go into your reports may be calculated continuously, while others may be calculated once a day. This is one aspect of how data freshness works in AdWords. To use reporting effectively, read the data freshness documentation.

Overview

For reporting, you can make plain synchronous HTTP requests directly to the AdWords server, an approach whose low overhead makes it suitable for high-volume reporting, especially when implemented using multiple threads (we recommend starting with 10). The HTTP request is synchronous because the call effectively blocks until the report data is ready to download.

You'll probably reach the Queries Per Second (QPS) limit (RateExceededError) before you exceed the number of open connections allowed on the server. Reporting requests do not count towards the daily operations quota, but there is a report downloads-per-day limit.

HTTP request

The request consists of an HTTP POST to the AdWords server at the following URL:

https://adwords.google.com/api/adwords/reportdownload/v201506

Request headers

Use the normal HTTP Header values when downloading reports:

HTTP Header	Description
`Authorization: Bearer OAUTH2_ACCESS_TOKEN`	Authorization to download the report. Use the same `accessToken` that's used for the SOAP request header.
`developerToken: DEVELOPER_TOKEN`	Your developer token consisting of a unique string, for example, `1a2B3c4D5e_-6v7w8x9y0z`.
`clientCustomerId: CLIENT_CUSTOMER_ID`	Customer ID of the client account.

You can specify the following optional HTTP headers to control whether your report includes a header or summary row:

Optional HTTP Header	Description
`skipReportHeader: true\|false`	If `true`, report output will not include a header row containing the report name and date range. If `false` or not specified, report output will include the header row.
`skipColumnHeader: true\|false`	If `true`, report output will not include a header row containing field names. If `false` or not specified, report output will include the field names.
`skipReportSummary: true\|false`	If `true`, report output will not include a summary row containing the report totals. If `false` or not specified, report output will include the summary row.
`includeZeroImpressions: true\|false`	If `true`, report output will include zero impression rows, provided the requested fields and predicates support zero impressions. If `false`, report output will not include zero impression rows. If omitted, the report will use the default behavior described in the zero impressions guide.

Request body

You have two options when defining your report definition:

Use an XML-based report definition.
Use an AWQL-based report definition.

The remainder of this section covers XML-based report definitions.

For an XML-based report definition, the POST request body must contain a parameter named "__rdxml" whose value is an XML fragment that defines the report, for example:

<reportDefinition xmlns="https://adwords.google.com/api/adwords/cm/v201506">
  <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>

An XML Schema (XSD) defining the structure of the reportDefinition is published at the following URL:

https://adwords.google.com/api/adwords/reportdownload/v201506/reportDefinition.xsd

Both application/x-www-form-urlencoded and multipart/form-data Content-Types are supported; for the former, you would need to URL-encode the submitted XML.

Date ranges

To specify the date range of your report, use a ReportDefinition.DateRangeType from the report definition XSD.

Valid DateRangeTypes
`TODAY`
`YESTERDAY`
`LAST_7_DAYS`
`LAST_WEEK`
`LAST_BUSINESS_WEEK`
`THIS_MONTH`
`LAST_MONTH`
`ALL_TIME`
`CUSTOM_DATE`
`LAST_14_DAYS`
`LAST_30_DAYS`
`THIS_WEEK_SUN_TODAY`
`THIS_WEEK_MON_TODAY`
`LAST_WEEK_SUN_SAT`

If you use any of the ReportDefinition.DateRangeTypes besides CUSTOM_DATE (e.g., LAST_7_DAYS), then only the dateRangeType is required.

<reportDefinition xmlns="https://adwords.google.com/api/adwords/cm/v201506">
    ...
  <dateRangeType>LAST_7_DAYS</dateRangeType>
</reportDefinition>

If you want a custom date range, then you must:

Specify CUSTOM_DATE for the dateRangeType.
Include a dateRange with min and max in YYYYMMDD format on your selector.

<reportDefinition xmlns="https://adwords.google.com/api/adwords/cm/v201506">
  <selector>
    ...
    <dateRange>
      <min>20150201</min>
      <max>20150301</max>
    </dateRange>
  </selector>
  <dateRangeType>CUSTOM_DATE</dateRangeType>
</reportDefinition>

Timeouts

The report download request may time out on extremely large data sets. There is no explicit data size limit; however, due to a variety of factors, the server may return an error if the report is too large.

If you encounter time outs or errors, try a shorter date range or use predicates to break up the report request into multiple, smaller requests. For example, instead of running a single report for all campaigns, you could submit multiple requests that each filter for a subset of Campaign IDs.

Reporting on multiple accounts

A given report request can only include data from a single AdWords account. If you need to gather reporting data for multiple accounts, submit a separate report request for each account by setting the clientCustomerId header described above.

Supported reports download formats

Format	Description
CSVFOREXCEL	The format for Excel. This uses a format of unicode which is prepended with a BOM (byte order marker) to signal to Excel that it is unicode. Excel defaults to use tab as a separator when unicode is being used. If comma is used then Excel will put all of the data in each row into a single column (by default).
CSV	The csv (comma separated) output format.
TSV	The tsv (tab separated) output format.
XML	The xml output format.
GZIPPED_CSV	The gzip compressed csv (comma separated) output format.
GZIPPED_XML	The gzip compressed xml output format.