Querying the Google Ads API (Beta)

The following classes represents queries in the Google Ads Query Language (GAQL).

class Query(select=None, from_resource=None, where=None, during=None, order_by=None, limit=None, parameters=None)

Represents GAQL query used to retrieve data from Google Ads API.

You can use Interactive GAQL Builder to build your queries.

Introduction and specification can be found on Google’s developer documentation:

• https://developers.google.com/google-ads/api/docs/query/grammar

Parameters:

• select (list[str]) – List of columns to select, e.g. ['campaign.id', 'segments.device', 'metrics.clicks']

• from_resource (str) – Name of the resource, e.g. campaign

• where (list[Condition]) – List of conditions.

• during (DuringClause) – During clause.

• parameters (Parameter | None) – List of meta parameters.

• order_by (list[OrderBy]) – List of order-by clauses.

• limit (int | None) – Limit the number of results.

to_gaql()

Constructs query in GAQL.

Return type:

str

Returns:

Query representation as string.

class DuringClause

Abstract class for during clause.

abstract get_title()

Returns:

Title of the specified date range.

abstract to_gaql()

Transform to GAQL fragment: one of the reserved constants (e.g. LAST_30_DAYS) or a date pair in YYYYMMDD format.

Return type:

str

class LastNDaysRange(n_days, offset=1)

Range of Last N days.

Parameters:

• n_days (int) – How many days to go back when determining start date.

• offset (int) – How many days to go back when determining end date. Default value of 1 equals to yesterday.

get_title()

Returns:

Title of the specified date range.

to_gaql()

Transforms to GAQL query string. :rtype: str :return: GAQL fragment.

class During(reserved_const, title=None)

Definition of reserved during constants.

Parameters:

• reserved_const (str) – Reserved constant, e.g. LAST_30_DAYS.

• title (str | None) – Custom title, defaults to spec when not set.

LAST_14_DAYS = During(reserved_const=(LAST_14_DAYS, title=(Last 14 Days))

The last 14 days not including today.

LAST_30_DAYS = During(reserved_const=(LAST_30_DAYS, title=(Last 30 Days))

The last 30 days not including today.

LAST_7_DAYS = During(reserved_const=(LAST_7_DAYS, title=(Last 7 Days))

The last 7 days not including today.

LAST_BUSINESS_WEEK = During(reserved_const=(LAST_BUSINESS_WEEK, title=(Last Business Week))

The 5 day business week, Monday through Friday, of the previous business week.

LAST_MONTH = During(reserved_const=(LAST_MONTH, title=(Last Month))

All days in the previous month.

LAST_WEEK_MON_SUN = During(reserved_const=(LAST_WEEK_MON_SUN, title=(Last Week (starting Monday)))

The 7-day period starting with the previous Monday.

LAST_WEEK_SUN_SAT = During(reserved_const=(LAST_WEEK_SUN_SAT, title=(Last Week (starting Sunday)))

The 7-day period starting with the previous Sunday.

THIS_MONTH = During(reserved_const=(THIS_MONTH, title=(This Month))

All days in the current month.

THIS_WEEK_MON_TODAY = During(reserved_const=(THIS_WEEK_MON_TODAY, title=(This Week (starting Monday)))

The period between the previous Monday and the current day.

THIS_WEEK_SUN_TODAY = During(reserved_const=(THIS_WEEK_SUN_TODAY, title=(This Week (starting Sunday)))

The period between the previous Sunday and the current day.

TODAY = During(reserved_const=(TODAY, title=(Today))

Today only.

YESTERDAY = During(reserved_const=(YESTERDAY, title=(Yesterday))

Yesterday only.

get_title()

Returns:

Title of the specified date range.

to_gaql()

Transforms to GAQL query string. :rtype: str :return: GAQL fragment.

class Condition(column, op, value=None)

Predicate defining a condition from GAQL.

Parameters:

• column (str) – Left side of the operator: name of the column.

• op (Op) – Operator.

• value (list | Sequence | str | int | tuple[int, int] | None | date) – Right side of the operator: value to compare to.

to_gaql()

Transforms to GAQL query string. :rtype: str :return: GAQL fragment.

static transform(value, field)

Transform value

Parameters:

• value – value to be transformed.

• field – which field/resource transformation to perform

Return type:

Any

Returns:

transformed value

class Op(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Operators used in filtering conditions.

BETWEEN = 'BETWEEN'

Operator to use to select between two dates.

CONTAINS_ALL = 'CONTAINS ALL'

Set (e.g. labels) contains all of the specified values.

CONTAINS_ANY = 'CONTAINS ANY'

Set (e.g. labels) contains at least one of the specified values.

CONTAINS_NONE = 'CONTAINS NONE'

Set (e.g. labels) does not contain any of the specified values.

DURING = 'DURING'

Filter ‘date’ field with the predefined ‘date range’.

EQUALS = '='

Equal.

GREATER_THAN = '>'

Greater than.

GREATER_THAN_EQUALS = '>='

Greater than or equals.

IN = 'IN'

Value is equal to one of the values in list.

IS_NOT_NULL = 'IS NOT NULL'

Value is not null.

IS_NULL = 'IS NULL'

Value is null.

LESS_THAN = '<'

Less than.

LESS_THAN_EQUALS = '<='

Less than equals.

LIKE = 'LIKE'

Value matches a specified pattern.

NOT_EQUALS = '!='

Not equal.

NOT_IN = 'NOT IN'

Value is not equal to any of the values in list.

NOT_LIKE = 'NOT LIKE'

Value does not match a specified pattern.

NOT_REGEXP_MATCH = 'NOT REGEXP_MATCH'

Value does not match a regular expression pattern.

REGEXP_MATCH = 'REGEXP_MATCH'

Value matches a regular expression pattern.

class OrderBy(column, sort=Sort.ASCENDING)

Single ORDER BY clause.

Parameters:

• column (str) – Column to sort by.

• sort (Sort) – Sorting direction.

to_gaql()

Transform to GAQL. :rtype: str :return:

class Sort(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Sort order.

ASCENDING = 'ASC'

Ascending.

DESCENDING = 'DESC'

Descending.

class Parameter(meta_parameter, value)

Parameter clause to specify meta parameters for the request.

Parameters:

• meta_parameter (str) – Name of the query parameter.

• value (bool) – Parameter value.