Google Ads API is returning to beta status. Please read our blog post for more details.

Querying in the Google Ads API

The syntax for Google Ads Query Language is similar to AWQL from the AdWords API, with some minor changes.

  • Fields you want to use in a WHERE or ORDER BY clause may also be required in the SELECT clause. Fields directly on the resource you are selecting are not required, but if you want to filter or sort by a field on another related resource, you must select that field explicitly. For example, if you are selecting FROM ad_group, ad group fields aren't required in the SELECT clause, but if you want to order by the related campaign ID, you must include campaign.id in the SELECT clause.

  • The list of valid operators for WHERE clauses is different. The new list of supported operators is:

    Google Ads API AdWords API Difference
    BETWEEN n/a Only available in the Google Ads API.
    CONTAINS ALL CONTAINS_ALL Underscore removed.
    CONTAINS ANY CONTAINS_ANY Underscore removed.
    CONTAINS NONE CONTAINS_NONE Underscore removed.
    CONTAINS NONE DOES_NOT_CONTAIN DOES_NOT_CONTAIN requires a single value, while CONTAINS NONE requires a list of values. To mirror DOES_NOT_CONTAIN functionality, provide a single element list as the value for CONTAINS NONE.
    DURING (in the WHERE clause) DURING as a separate clause DURING is now an operator instead of a top-level clause.
    LIKE STARTS_WITH LIKE ignores case.
    LIKE STARTS_WITH_IGNORE_CASE LIKE ignores case.
    NOT IN NOT_IN Underscore removed.
    NOT LIKE n/a Only available in the Google Ads API.
  • The list of operators in AdWords API WHERE clauses that are not supported in the Google Ads API:

    • CONTAINS
    • CONTAINS_IGNORE_CASE
    • DOES_NOT_CONTAIN
    • DOES_NOT_CONTAIN_IGNORE_CASE
  • Ordering of results is now allowed in all queries.

  • Limiting the number of results is now allowed in all queries. Previously, there was a LIMIT clause that was used with the query method of the AdWords API services to define the page size and start index. The idea of using a limit with a page size and start index no longer is used in the Google Ads API.

  • Paging now uses a page token so you can pick up directly where you left off, rather than the LIMIT clause that was present in AWQL. You can specify a page size as part of the request to the GoogleAdsService.

  • Date filtering is different. There is no longer a DURING clause; instead, DURING is an operator that can be used in WHERE clauses. Filter the field date using the DURING clause for the same functionality as the DURING clause in AWQL. For example:

    ... WHERE segments.date DURING LAST_30_DAYS
    ... WHERE segments.date >= '2018-01-01' AND segments.date <= '2018-01-31'
    ... WHERE segments.date >= '2018-01-01'
    
  • The syntax for lists has changed. In the AdWords API, you used [] brackets. In the Google Ads API, use () parentheses instead. For example, you would specify a predicate for a list of ad group Status values as:

    ad_group.status IN (ENABLED, PAUSED)