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:

    AdWords API Google Ads API Difference
    CONTAINS_ALL CONTAINS ALL Underscore removed.
    CONTAINS_ANY CONTAINS ANY Underscore removed.
    CONTAINS_NONE CONTAINS NONE Underscore removed.
    DOES_NOT_CONTAIN CONTAINS NONE 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 as a separate clause DURING (in the WHERE clause) DURING is now an operator instead of a top-level clause.
    STARTS_WITH LIKE LIKE ignores case.
    STARTS_WITH_IGNORE_CASE LIKE LIKE ignores case.
    NOT_IN NOT IN Underscore removed.
    n/a BETWEEN Only available in the Google Ads API.
    n/a NOT LIKE 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.

  • GoogleAdsService.SearchStream is recommended in most cases. You can still page via the GoogleAdsService.Search method which 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 >= '2020-01-01' AND segments.date <= '2020-01-31'
    ... WHERE segments.date >= '2020-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)