https://developers.google.com/adwords/api/docs/guides/reporting#awql
Overview
There are two main steps to generate reports from the API:
- Create a report definition. The report definition is an XML or AWQL fragment that defines the parameters of your report, including the report name, the types of information to include in the report, the download format, and other details.
- Enclose the report definition in an HTTP POST request, and submit it to the Google server.
Both of these steps are described below.
Create a report definition
The report definition constitutes the body of the request, where you specify the elements to include in the report.
You can create report definitions in XML or in AWQL, the AdWords Query Language.
The sections below cover XML-based report definitions. Check out the reporting section of the AWQL guide if you'd prefer to use AWQL instead of XML.
Below is an example of an XML report definition. The table below it defines each element in the report definition.
SELECT CampaignId, AdGroupId, Impressions, Clicks, Cost
FROM ADGROUP_PERFORMANCE_REPORT
WHERE AdGroupStatus IN [ENABLED, PAUSED]
DURING LAST_7_DAYS Data freshness
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 Google Ads. To use reporting effectively, see the data freshness documentation.
Prepare the request
Once your report definition is created, you can now prepare the HTTP POST request.
You can make plain synchronous HTTP requests directly to the Google 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 toward the daily operations quota, but there is a report downloads-per-day limit.
For an XML report definition, the POST request body must contain a parameter named "__rdxml" whose value is your XML report definition.
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. |
useRawEnumValues: true|false |
Set to true if you want the returned format to be the actual enum value, for example, "IMAGE_AD" instead of "Image ad". Set to false or omit this header if you want the returned format to be the display value. |
includeZeroImpressions: true|false |
If true, report output will include rows where all specified metric fields are zero, provided the requested fields and predicates support zero impressions. If false, report output will not include such rows. Thus, even if this header is false and the Impressions of a row is zero, the row is still returned in case any of the specified metric fields have non-zero values. If omitted, the report will use the default behavior described in the Zero Impressions guide. |
HTTP request URL
The request consists of an HTTP POST to the Google server at the following URL:
https://adwords.google.com/api/adwords/reportdownload/v201809
Complete example
Here is a complete example showing the report definition above enclosed within an HTTP POST request.
POST /api/adwords/reportdownload/v201809 HTTP/1.1 Host: adwords.google.com User-Agent: curl, gzip Accept: */* Accept-Encoding: gzip Authorization: Bearer [Enter OAuth 2.0 access token here] developerToken: [Enter developerToken here] clientCustomerId: [Enter clientCustomerID here] Content-Length: 182 Expect: 100-continue Content-Type: multipart/form-data; boundary=------------------------12d01fae60c7b559 Parameters: __fmt: CSV __rdquery: SELECT CampaignId, AdGroupId, Impressions, Clicks, Cost
FROM ADGROUP_PERFORMANCE_REPORT
WHERE AdGroupStatus IN [ENABLED, PAUSED] DURING LAST_7_DAYS
Response codes
If the report request is successful, the server returns a Response Code of 200.
A Response Code of 400 indicates an API error; check for any issues with the XML in your report definition.
A Response Code of 500 typically indicates a temporary problem with the server; if this error occurs, retry the request after a few moments.
Reports for multiple accounts
A given report request can only include data from a single Google Ads 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.
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 timeouts 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.
Supported 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. |
Choosing the right report
Because of the extensive reporting options available in the AdWords API, determining the correct report for a particular business need can be tricky.
Use the chart below to determine the most suitable report, then check out the details for that report on the Report Types page.
Segmentation
For more detailed statistics, you can split the data by segments. For example, you might be interested in knowing the number of impressions specific to the Google Search Network, separate from the Google Display Network; in which case, you will want to segment your report by network.
Segmentation, which is available in the UI as a separate menu, is achieved in the API by just adding the proper field to the report. For example, adding the field AdNetworkType1 to an Ad Group Performance report results in a report with a row for each ad group and network combination, and the statistical values (impressions, clicks, conversions, etc.) split between them. While in the UI only one segment at a time can be used for display, with the API you can combine multiple segments in the same report. Keep in mind that the amount of rows can increase exponentially for each additional segment field included in your report.
Format of various fields
While all fields returned in reports have a Type, the actual values returned won't always match these values. You should always check the Notes column, which often contains additional information about the expected format of values. For example, the Notes column for ConversionRate states: Percentage returned as "x.xx%".
Money fields in reports
Fields of type Money are returned in micro currency units (micros) but may be prefixed with "auto: " or may simply be the string "auto" if automatic bidding is used. For example, $1.23 will come back as 1230000 (1.23 x 1,000,000). Micro amounts always refer to the account's local currency.
When filtering on money fields, you'll have to provide the value in micros. For example, WHERE AverageCpc > 1000000 will return rows where the AverageCpc is greater than $1 (one unit of the account currency).
Two dashes
A value of two dashes (--) indicates there is no value for this cell.
https://developers.google.com/adwords/api/docs/guides/awql
AWQL is a SQL-like language for performing queries against most common AdWords API services. Any service with a query() method is supported.
AWQL is inspired by SQL, though it does not support the full SQL vocabulary. Notable omissions are the JOIN and GROUP BY clauses.
For each service, you can get the list of queryable fields from Selector Fields.
Additionally, you can use AWQL to query reports. See Report Types for a comprehensive list of queryable fields.
Using AWQL with reports
AWQL is often used in reporting. Instead of specifying the XML fragment in the "__rdxml" POST parameter as you normally would for reports, supply these two parameters:
- "
__rdquery": contains the AWQL query string. - "
__fmt": defines the report download format.
Example (POST body):
__rdquery=SELECT+Criteria+FROM+KEYWORDS_PERFORMANCE_REPORT+DURING+20150101,20150325&__fmt=CSV
There are also some usage differences when using AWQL for reports:
Formal grammar
Here is the formal AWQL grammar for reference.
Statement -> SelectClause FromClause1 WhereClause?
DuringClause2 OrderByClause?3 LimitClause?4
SelectClause -> SELECT ColumnList
FromClause -> FROM SourceName
WhereClause -> WHERE ConditionList
DuringClause -> DURING DateRange
OrderByClause -> ORDER BY Ordering (, Ordering)*
LimitClause -> LIMIT StartIndex , PageSize
ConditionList -> Condition (AND Condition)*
Condition -> ColumnName Operator Value
Value -> ValueLiteral | String | ValueLiteralList | StringList
Ordering -> ColumnName (DESC | ASC)?
DateRange -> DateRangeLiteral | Date,Date
ColumnList -> ColumnName (, ColumnName)*
ColumnName -> Literal
SourceName -> Literal
StartIndex -> Non-negative integer
PageSize -> Non-negative integer
Operator -> = | != | > | >= | < | <= | IN | NOT_IN | STARTS_WITH | STARTS_WITH_IGNORE_CASE |
CONTAINS | CONTAINS_IGNORE_CASE | DOES_NOT_CONTAIN |
DOES_NOT_CONTAIN_IGNORE_CASE | CONTAINS_ANY | CONTAINS_NONE | CONTAINS_ALL
String -> StringSingleQ | StringDoubleQ
StringSingleQ -> '(char)'
StringDoubleQ -> "(char)"
StringList -> [ String (, String)*