AdWords API

The AdWords Query Language (AWQL)

AWQL is a SQL-like language for performing queries against most common AdWords API services. Any service with a query method is supported. Note that the DataService has two query methods for different types of data.

Additionally, you can use AWQL in AdHoc report queries.

AWQL usage

In service calls

AWQL is inspired by SQL, though it does not support the full SQL vocabulary. Notable omissions are the JOIN and GROUP BY clauses.

Here's an example query that you might want to send to the CampaignService:

SELECT     CampaignId, CampaignName
WHERE      Ctr > 0.05
           AND Impressions < 100
DURING     20120201,20120228
ORDER BY   CampaignName DESC
LIMIT      0,50

The equivalent AWQL query string that would accompany the query method is:

CampaignPage p = client.query("SELECT CampaignId,CampaignName
                WHERE Ctr > 0.05 AND Impressions < 100
                DURING 20120201,20120228 ORDER BY CampaignName DESC LIMIT 0,50");

Notes:

  • A FROM clause is not needed since the data source is already determined by the service to where the request is sent.
  • A DURING clause is optional in service calls.
  • Although keywords (e.g., WHERE) are not case-sensitive, field (column) names (e.g., CampaignName) and Literals (e.g., YESTERDAY) are case-sensitive.
  • When using IN and NOT_IN operators in your WHERE clause, you are limited to 10,000 items.

In AdHoc reports

AWQL can also be used in AdHoc report download requests. Instead of specifying the XML fragment in the "__rdxml" POST parameter as you normally would for AdHoc reports, supply these two parameters:

  1. "__rdquery": contains the AWQL query string.
  2. "__fmt": defines the report download format.

Example (POST body):

__rdquery=SELECT+Name+FROM+KEYWORDS_PERFORMANCE_REPORT+DURING+20120101,20120625&__fmt=CSV

There are also some usage differences for AdHoc reports:

  • The query must contain a report type in the FROM clause, for example: SELECT Name FROM KEYWORDS_PERFORMANCE_REPORT. Note that while FROM is disallowed in service calls, is is mandatory in report downloads.
  • Date ranges for the report are defined in the mandatory DURING clause of the query. Date ranges can be specified in two different ways:
    1. A custom date range using regular AWQL syntax, for example: SELECT Name FROM KEYWORDS_PERFORMANCE_REPORT DURING 20120101,20120625.
    2. A date range type, for example: SELECT Name FROM KEYWORDS_PERFORMANCE_REPORT DURING LAST_7_DAYS. Note: The DateRangeTypes ALL_TIME and CUSTOM_DATE are NOT supported.
  • ORDER BY and LIMIT (Sorting and Paging) are NOT supported for AdHoc reports. Including these clauses in a query will generate an error.
  • To omit zero-impression rows, include a 'WHERE Impressions > 0' condition.

Formal grammar

Here is the formal AWQL grammar for reference.

Statement        -> SelectClause FromClause1 WhereClause?
                                 DuringClause2 OrderByClause? LimitClause?
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
String           -> StringSingleQ | StringDoubleQ
StringSingleQ    -> '(char)'
StringDoubleQ    -> "(char)"
StringList       -> [ String (, String)* ]
ValueLiteral     -> [a-zA-Z0-9_.]*
ValueLiteralList -> [ ValueLiteral (, ValueLiteral)* ]3
Literal          -> [a-zA-Z0-9_]*
DateRangeLiteral -> TODAY | YESTERDAY | LAST_7_DAYS | THIS_WEEK_SUN_TODAY | THIS_WEEK_MON_TODAY | LAST_WEEK |
                    LAST_14_DAYS | LAST_30_DAYS | LAST_BUSINESS_WEEK | LAST_WEEK_SUN_SAT | THIS_MONTH
Date             -> 8-digit integer: YYYYMMDD

Notes:

  • 1 FROM is disallowed in service calls but required in report downloads.
  • 2 DURING is optional in service calls but required in report downloads.
  • 3 For ValueLiteralList, square brackets [ ] are required, elsewhere, they denote a range.
  • ? signifies optional; * signifies one or more.
  • Order: SELECT...FROM...WHERE...DURING...ORDER BY...LIMIT...
  • All keywords are case-insensitive.
  • Column names and Literals are case-sensitive.
  • White space doesn't matter.
  • Both double quotes and single quotes are accepted for strings. Escape sequences are \", \', \\.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.