Google Ads Search

Google Ads scripts supports the ability to perform searches directly using the Google Ads API. You can use these searches to fetch both structural and metric data about resources in your account.

To initiate a search, use AdsApp.search, which takes an argument representing the query. It also takes an optional argument which you can use to explicitly specify a Google Ads API version. If left unspecified, the latest supported version will be used. For all specific call details, see the AdsApp.search documentation.

These searches differ from reports in a few different ways:

1. The only query language supported is Google Ads Query Language (GAQL). AdWords Query Language (AWQL) is not supported with search. Consult the Google Ads API documentation for a complete breakdown of the GAQL grammar and a list of accessible resources and their fields.
2. The returned object from the search request is an iterator of rows rather than a report object.
3. The returned rows are GoogleAdsRow objects with nested sub-objects for each contained resource, rather than a single JSON object. So if you request a campaign's name, for example, you would access it with row.campaign.name rather than row['campaign.name']. If you would prefer a flattened result, you can issue an AdsApp.report call using GAQL.
4. The results may contain some additional fields not explicitly requested, such as associated resource names.

Here is a sample code snippet demonstrating a simple search request:

var query = 'SELECT campaign.name, campaign.start_date, metrics.clicks FROM campaign';

// The second argument is optional.
var result = AdsApp.search(query, {apiVersion: 'v13'});
while (result.hasNext()) {
  var row = result.next();
  Logger.log('The start date of the campaign ' + row.campaign.name + ' is ' + row.campaign.startDate);
}