Google Ads Query Language

Overview

The Google Ads Query Language provides the flexibility to query the Google Ads API for:

  • Any resource or stat in GoogleAdsService.Search. You would use Google Ads Query Language for these purposes:

    • To query multiple resources at a time because each of the services returns only one resource at a time using the Get method.
    • To query stats such as impressions and clicks. For a full list of metrics, see Metrics.
  • Query for metadata about the fields and resources available in GoogleAdsFieldService. You would use this query language for the purpose of getting a catalog of what fields are available to query in the Google Ads API along with specifics about compatibility and types.

The result of GoogleAdsService queries is a list of GoogleAdsRow instances. Each GoogleAdsRow contains the resource. If metrics were requested, then it also includes metrics.

The result of GoogleAdsFieldService queries is a list of GoogleAdsField instances. Each GoogleAdsField contains details about the field that you requested.

Example query

When querying for stats, you can also have the details of the associated resources returned at the same time. You can then immediately take those resources, modify them, and then send them back to the Mutate methods of their services. This means that the following example workflow is possible:

  • Query all the campaigns that are currently PAUSED and have impressions greater than 1000.
  • Process each GoogleAdsRow returned in the list, and retrieve the campaigns that are in each GoogleAdsRow.
  • Change the status of each campaign from PAUSED to ENABLED.
  • Call CampaignService.MutateCampaigns with the modified campaigns to update them.

Resources query

There are times when you may not care about the stats. Here's a query for campaigns showing how to get the campaign ID, name, and status, while ordering by campaign ID.

SELECT campaign.id, campaign.name, campaign.status
  FROM campaign
  ORDER BY campaign.id

To find out what other fields are available to query for campaign, see the Campaign.

Each GoogleAdsRow has a campaign populated with the selected fields.

Stats query

When querying for stats, you can query for the resource and stats at the same time. Here's a query for campaigns showing how to get the campaign ID, name, status, and impressions. The query filters for only the campaigns that have a status of PAUSED and have had greater than 1000 impressions while ordering by campaign ID.

SELECT campaign.id, campaign.name, campaign.status, metrics.impressions
  FROM campaign
  WHERE campaign.status = 'PAUSED' AND metrics.impressions > 1000
  ORDER BY campaign.id

To find out what other fields are available to query for campaign, see the Campaign. To find out what other metrics are available, see Metrics.

Each GoogleAdsRow has a campaign populated with the selected fields, and the GoogleAdsRow has metrics populated with the selected metrics.

Fields metadata query

Queries can be used with the GoogleAdsFieldService to view field metadata. Here's a query for getting the field metadata for campaign.id. You can replace campaign.id in this query with either a resource (such as customer, campaign) or a field (such as metrics.impressions, ad_group.id). Please note that there's no FROM clause in this query.

SELECT name, category, selectable, filterable, sortable, selectable_with, data_type, is_repeated
  WHERE name = campaign.id

To find out what other fields are available to query for field metadata, see the GoogleAdsField.

Code examples

The client libraries have examples of using the Google Ads Query Language in the GoogleAdsService. The basic operations folder has examples such as GetCampaigns, GetKeywords, and GetArtifactMetadata. The reporting folder has the GetKeywordStats example.

Next steps

For more information on the Google Ads Query Language, continue reading:

Send feedback about...

Google Ads API Beta
Google Ads API Beta
Need help? Visit our support page.