Using the Google Ads API in Google Apps Script

Edit Google Ads entities programatically using the REST interface for the Google Ads API in Google Apps Script.

The problem

You cannot use Google Ads Scripts on some Google Ads entities. For example, creating new accounts.

Before considering Google Apps Script, it’s worth exploring whether it can be done in Google Ads Scripts first. Script previews, autocomplete and automated authentication make it easier to work with.

Need a hand?

If you need help with something similar to this blog post, then get in touch through my contact page.

Get in touch

Authentication

To get started, we to need to:

Edit our appsscript.json file to add the Google Ads API to the OAuth scopes.
Get our developer token from Google Ads. Here are the instructions from Google for how to get your developer token.
Create a new Google Cloud project to associate with our Google Apps script project.
Associate your new project number to a Google Apps Script project by going to Project Settings > Google Cloud Platform (GCP) Project and entering the project number.
Enable the Google Ads API in the new Google Cloud Project. Here are the instructions for this, where you’ll need to enable the ‘Google Ads API’ in the library.

Editing your appsscript.json file

This file is hidden by default. You can un-hide it under Project Settings > General Settings and tick the ‘Show “appsscript.json” manifest file in editor’ option.

Now it’s unhidden, we can edit it. Let’s add a key to this JSON file for ‘oauth scopes’, and set the value as an array of strings, which are the scopes. These tell the Script what we should have permission to read and modify.

appsscript.json

{
    "timeZone": "Pacific/Auckland",
    "exceptionLogging": "STACKDRIVER",
    "runtimeVersion": "V8",
    "oauthScopes": [
        "https://www.googleapis.com/auth/adwords",
        "https://www.googleapis.com/auth/script.external_request"
    ]
}

Now, when a user atttempts to run any function in the project, they’ll be prompted to grant management access to their Google Ads account and make external requests to other apps.

When that access is granted, we can grab the token in our script using ScriptApp.getOAuthToken().

To make a request, we’ll need to add both the OAuth token and the developer token to the headers of our requests, like this:

let headers = {
    Authorization: "Bearer " + ScriptApp.getOAuthToken(),
    "developer-token": "DEVELOPER_TOKEN",
    "login-customer-id": "THE_PARENT_MCC_CUSTOMER_ID_YOU_CREATED_THE_TOKEN_IN_WITH_NO_HYPHENS"
};

let requestParams = {
    method: "POST",
    contentType: "application/json",
    headers: headers,
    payload: JSON.stringify({
        YOUR_PAYLOAD: 'GOES_HERE'
    })
};

let response = UrlFetchApp.fetch("API_ENDPOINT_URL", requestParams);

Logger.log(response);

Lastly, we’ll need to fill in the payloads and API endpoints in our code based on the entities we want to manage.

It can be tricky to work out the correct API endpoint URL, and you may have to trawl through the code for the client libraries to find it. Check the ‘services’ files under the version number you’re working with and find the entity you want to read or modify. Then, check the comments for any URL structures for that particular entity.

Fetching reporting data

Firstly, you’re better off using Google Ads scripts for fetching reporting data, unless you want to create a user interface for your script in Google Sheets.

Putting that aside for now, we’ll demonstrate using the API in Google Apps Script with an example from Google for fetching reporting data for a campaign by device from the last 30 days.

We’re going to convert the code snippets from curl to Google Apps Script by filling in our payload and endpoint URL from our previous code snippet.

Our endpoint URL would be:

https://googleads.googleapis.com/v10/customers/{cid}/googleAds:searchStream

Where v10 represents the API verison number and the the cid is the Google Ads customer ID you’d like to pull data from, without any hyphens. Note that the latest version when this was last updated is v13.

Our payload would be:

{
    "query": `SELECT campaign.name, campaign.status, segments.device,
    metrics.impressions,
    metrics.clicks,
    metrics.ctr,
    metrics.average_cpc,
    metrics.cost_micros
    FROM campaign
    WHERE segments.date DURING LAST_30_DAYS`
}

When putting this together with our previous script, we also need to:

Replace the login-customer-id header value with the parent MCC customer ID where you created the API token.
Replace the developer-token header value with your developer token.

Putting it all together, it looks something like:

//replace these example values with your specific values - the customer IDs have no hyphens i.e. 123-456-789 becomes 123456789
const DEVELOPER_TOKEN = "abc123";
const PARENT_MCC_ID = "1234567";
const CHILD_CUSTOMER_ID = "1234568";

//the rest of the script

let headers = {
    Authorization: "Bearer " + ScriptApp.getOAuthToken(),
    "developer-token": DEVELOPER_TOKEN,
    "login-customer-id": PARENT_MCC_ID
};

let requestParams = {
    method: "POST",
    contentType: "application/json",
    headers: headers,
    payload: JSON.stringify({
        query: `SELECT campaign.name, campaign.status, segments.device,
                    metrics.impressions, metrics.clicks, metrics.ctr,
                    metrics.average_cpc, metrics.cost_micros
            FROM campaign
            WHERE segments.date DURING LAST_30_DAYS`
    })
};

let response = UrlFetchApp.fetch("https://googleads.googleapis.com/v12/customers/" + CHILD_CUSTOMER_ID + "/googleAds:searchStream", requestParams);

Logger.log(response);

Creating an account

The process for creating an account is similar, where we need to:

Update our endpoint URL from the reporting service, to the account service.
- We can find the endpoint URL in here, where we’ll go to our version (v12) > services > customer_service.proto.
- Within that file, look for the CreateCustomerClient.
Update our payload to represent an account, rather than a report query.

It will look something like:

//replace these example values with your specific values - the customer IDs have no hyphens i.e. 123-456-789 becomes 123456789

const DEVELOPER_TOKEN = "abc123";
const PARENT_MCC_ID = "1234567";
const NEW_ACCOUNT_NAME = "ABC Limited";
const NEW_ACCOUNT_CURRENCY_CODE = "NZD";
const NEW_ACCOUNT_TZ = "Pacific/Auckland";

//the rest of the script

let endpoint = "https://googleads.googleapis.com/v12/customers/" + PARENT_MCC_ID + "/:createCustomerClient";

let newCustomerResource = {
    descriptive_name: NEW_ACCOUNT_NAME,
    currency_code: NEW_ACCOUNT_CURRENCY_CODE,
    time_zone: NEW_ACCOUNT_TZ
};

let newCustomerResource2 = {
    customer_id: PARENT_MCC_ID,
    customer_client: newCustomerResource
};

let headers = {
    Authorization: "Bearer " + ScriptApp.getOAuthToken(),
    "developer-token": DEVELOPER_TOKEN,
    "login-customer-id": PARENT_MCC_ID
};

let accountCreateParams = {
    method: "POST",
    contentType: "application/json",
    headers: headers,
    payload: JSON.stringify(newCustomerResource2)
};

let response = UrlFetchApp.fetch(newAccountUrl, accountCreateParams);

Logger.log(response);

Running the above script should create a child account under your MCC.