Free Google Ads Scripts Guide [2022 + New Google Ads Scripts Examples]

Contents

1. What are Google Ads Scripts?

2. What was the Google Ads Scripts 2022 update?

3. How to write Google Ads scripts 

4. Google Ads Report vs. Query

5. Google Ads Scripts - Reports

   1. Types of reports

   2. Report filtering

   3. Working with dates in reports

   4. Example report query snippet

6. Google Ads Scripts - Queries

   1. Types of query

   2. Entities that can be queried

   3. Query filtering

   4. Working with dates in queries  

   5. Example query snippet

7. Using Google Apps Scripts within Google Ads scripts including code snippets

   1. SpreadsheetApp

   2. MailApp

   3. UrlFetchApp

8. Summary 

What are Google Ads Scripts?

Google Ads Scripts are an interface through which to access Google Ads, via the Google Ads API. Scripts can be used to programmatically make changes in your account (such as pausing ads or keywords that meet certain criteria), conduct analysis or pull reports from Google Ads. 

What was the Google Ads Scripts 2022 update?

In March 2022 Google announced that by September 31st 2022 all scripts would migrate to a new experience, based on the Google Ads API rather than the old Adwords API

The new Google Ads scripts experience makes use of ES6, bringing more modern Javascript to Google Ads scripts as well a better validation when writing in the preview mode. Scripts will continue to work in many cases, as AWQL code will be converted to the new GAQL on the backend. There are some instances where your scripts will need to be migrated, such as zero impression rows, which won’t work in GAQL.  

How to Write Google Ads scripts

Fortunately with the new scripts update comes a more modern, predictive interface so that you can better validate your code, which does make writing scripts within the interface somewhat easier.

The important thing to do when working with scripts is to always refer to the documentation so you know which classes and methods to use, and the values they can return. Google’s documentation also comes with helpful code snippets and best practices.

It’s only necessary to have a basic understanding of Javascript in order to get started with Scripts. FreeCodeCamp offers a number of introductory Javascript courses so is a good place to start to learn the basic concepts, and CodeAcademy also have a free introductory Javascript course. 

An intro course will get you familiar with basic concepts such as variables, objects, and methods. It’s then a good idea to start practising by tweaking scripts that others have already written, before starting to write your own from scratch. 

You’ll also need to get used to the concepts of selectors and iterators, which are essentially used to avoid loading a whole list of objects into memory at once and so that the query can be narrowed down to return the entities you want. For example by date, ID or name. 

First decide whether you want to run a report, or execute a query. This difference here is whether you only want to read data or also write too. If you only want to read, e.g. pull a report from Google Ads, then a report is fine. You can read data from a query, but cannot write from a report. Best practice advice is to use reports when you want to retrieve large amounts of data as it can provide better performance

We’ll start with an example of a report, and then build a query. 

Google Ads Script Example - Campaign Report 

In this example, we’re going to pull a Google Ads API report of Search campaign performance, which we’ll then push to a Google Sheet. This will be for the metrics clicks, impressions and cost, between 01-01-2021 and 31-12-2021. 

Google Ads Scripts Report queries are written in GAQL from the Google Ads API, meaning that working with filtering and date filtering is different from queries, which use Javascript 

You can also build and validate queries in the Google Ads Query Builder

1. Decide which report you’d like to query, how it should be filtered and which segments/metrics you’d like to return. The full list of reports can be found in the Google Ads API documentation. In this example below we’ll be using the campaign report 

let data = [];

 let query = 'SELECT ' +

     'segments.date, campaign.name, metrics.clicks, metrics.impressions, metrics.cost_micros ' +

     'FROM campaign ' +

     'WHERE metrics.impressions > 0 '+ 

     'AND campaign.name LIKE "%Search%" '+

     'AND segments.date BETWEEN "' +  '2021-01-01' + '" AND "' + '2021-12-31';

2. We’ll then use AdsApp.search method to execute the query, which will return SearchRowIterator. We’ll then iterate over the query with hasNext() and next() which will return each row, which we’ll push to the variable data. 

  let result = AdsApp.search(query);

   while (result.hasNext()) {

   let row = result.next();

   data.push([row.segments.date, row.campaign.name, row.metrics.costMicros/1000000, row.metrics.impressions, row.metrics.clicks])

   }

3. Finally, decide where you want to push the returned rows. We’ll be pushing the row array data to a Google Sheet by combining this with Google Apps Script so end up with something like the below. Here’s how to integrate Google Apps Script into your Scripts and push data to a Google Sheet ← jumplink

 let ss = SpreadsheetApp.openByUrl(settings.url);

 let sheet = ss.getSheetByName(settings.sheet);

  sheet.getRange("A2:E").clearContent();  // delete any old data from sheet */

  // get last row for column A in export sheet

 var columnToCheck = sheet.getRange("A:A").getValues();

 var lastRow = getLastRowSpecial(columnToCheck);

  sheet.getRange(lastRow+1,1,data.length,data[0].length).setValues(data) // export data to sheet

Pro Tip: If you want the date range in the query to be dynamic, then also insert the following code snippet. 

 //  DATE

 let MILLIS_PER_DAY = 1000 * 60 * 60 * 24;

 let now = new Date();

 let from = new Date(now.getTime() - 4 * MILLIS_PER_DAY);    // TODAY MINUS 4

 let to = new Date(now.getTime() - 1 * MILLIS_PER_DAY);      // YESTERDAY

 let timeZone = AdsApp.currentAccount().getTimeZone();

You can then update the date section of the query to include the from or two variables (or both) to make the date range on your report dynamic. In this example the query will start on 01-01-2021 and end yesterday 

let query = 'SELECT ' +

     'segments.date, campaign.name, metrics.clicks, metrics.impressions, metrics.cost_micros ' +

     'FROM campaign ' +

     'WHERE metrics.impressions > 0 '+ 

     'AND campaign.name LIKE "%Search%" '+

     'AND segments.date BETWEEN "' +  '2021-01-01' + '" AND "' + Utilities.formatDate(to, timeZone, 'yyyy-MM-dd') + '"';

Final script 

//

//

// PERFORMANCE MARKETING PLAYBOOK 2022

// settings

let settings = {

   url: '',                    // INSERT YOUR SHEET URL HERE

   sheet: '',                  // INSERT YOUR SHEET NAME HERE

 }

  //  DATE

 let MILLIS_PER_DAY = 1000 * 60 * 60 * 24;

 let now = new Date();

 let from = new Date(now.getTime() - 4 * MILLIS_PER_DAY);    // TODAY MINUS 4

 let to = new Date(now.getTime() - 1 * MILLIS_PER_DAY);      // YESTERDAY

 let timeZone = AdsApp.currentAccount().getTimeZone();

 function main() {

  let data = [];

let query = 'SELECT ' +

     'segments.date, campaign.name, metrics.clicks, metrics.impressions, metrics.cost_micros ' +

     'FROM campaign ' +

     'WHERE metrics.impressions > 0 '+ 

     'AND campaign.name LIKE "%Search%" '+

     'AND segments.date BETWEEN "' +  '2021-11-01' + '" AND "' + Utilities.formatDate(to, timeZone, 'yyyy-MM-dd') + '"';

  let result = AdsApp.search(query);

   while (result.hasNext()) {

   let row = result.next();

   data.push([row.segments.date, row.campaign.name, row.metrics.costMicros/1000000, row.metrics.impressions, row.metrics.clicks])

   }

 let ss = SpreadsheetApp.openByUrl(settings.url);

 let sheet = ss.getSheetByName(settings.sheet);

  sheet.getRange("A2:E").clearContent();  // delete any old data from sheet */

  // get last row for column A in export sheet

 var columnToCheck = sheet.getRange("A:A").getValues();

 var lastRow = getLastRowSpecial(columnToCheck);

  sheet.getRange(lastRow+1,1,data.length,data[0].length).setValues(data) // export data to sheet

 }

 // get last row special

  function getLastRowSpecial(range){

   var rowNum = 0;

   var blank = false;

   for(var row = 0; row < range.length; row++){

     if(range[row][0] === "" && !blank){

       rowNum = row;

       blank = true;

     }else if(range[row][0] !== ""){

       blank = false;

     };

   };

   return rowNum;

 };

Here’s a recap of what we’ve built

• We’ve built a Google Ads Query based on the campaign report between 01-01-2021 and 31-12-2021 for all campaigns that contain “Search”

• We’ve declared a new variable - data

• Used the Search method on our query variable which has exposed an iterator and we’ve then pushed each row to our new array called data

• We’ve then pushed the array called “data” to a Google Sheet, after first clearing the sheet

Google Ads Script Example - Get All Live Search Final Urls in Account

In this example, instead of a report, we’ll be building a query, in order to return all of the Search Final URLs currently running in the account. 

In order to do this we’ll need to navigate to the root object, AdsApp, from which we can find the entities we need. We’ll be looking to return the ad group name and final Url for each live search ad in the account. 

Select the correct method within AdsApp, e.g ads. This will allow you to select and return any/all of the ad groups in the account and then return an iterator. This will enable you to iterate over each ad group and perform other actions on the ad group, such as adding keywords or applying labels.

This then returns a selector of all ad groups in the account

You then fetch the ads by building your query, filtering for the ads you wish to return by column name and date range

var adSelector = AdsApp.ads().withCondition("campaign.name REGEXP_MATCH '.*Search.*'")

   .withCondition("campaign.status = ENABLED")

   .withCondition("ad_group.status = ENABLED")

   .withCondition("ad_group_ad.status = ENABLED")

   .forDateRange("TODAY");

As we’re working with final urls, we need to navigate to AdsApp.Ad, and from there, identify each method we need to call in order to return what we need. 

You may need to use the documentation to navigate to the correct level to return the value you need. E.g. to get the ad group name, you’ll first need to return the ad group, and then the ad group name.

Once you’ve found these, run the ad iterator and push the rows to data 

var data = [];

   var adSelector = AdsApp.ads().withCondition("campaign.name REGEXP_MATCH '.*Search.*'")

   .withCondition("campaign.status = ENABLED")

   .withCondition("ad_group.status = ENABLED")

   .withCondition("ad_group_ad.status = ENABLED")

   .forDateRange("TODAY");

   var adIterator = adSelector.get();

   while (adIterator.hasNext()) {

   var ad = adIterator.next();

     data.push([ad.getAdGroup().getName(),ad.urls().getFinalUrl()])

   }

Using Google Apps Scripts within Google Ads scripts [including code snippets]

Once you’ve queried your Google Ads reports, or programmatically made changes in your account, you may want to do other things with the returned data, such as sending alerts to your email or push your data to a spreadsheet. 

Here are some useful Google Apps Script classes that you can integrate into your Ads Scripts

URLFetchApp can be used to crawl URLs. Here are some idea for how it can be used in Google Ads

• Check for 404/300 response Urls

• Check stock availability of products and pause 

MailApp can be used to send emails from your Google Ads Script

SpreadsheetApp is useful for 

Summary

Understanding how to write Google Ads Scripts unlocks powerful automations which can really increase the efficiency of your work, and automate many time consuming, manual tasks.