Google Analytics Remarketing API: We're Making A List, We're Checking It N Times Recursively

Revolutionise your remarketing audience creation

The ability to build remarketing audiences in Google Analytics is a very powerful feature - if you’re not familiar with remarketing audiences, maybe brush up a little before continuing. Still here? Good! Thankfully, the process of creating or editing remarketing lists in the Analytics interface is very simple and quick… if you’re only doing one at a time. Chances are, though, you probably want to be able to do these in batches - say, creating all of your audiences at once for one property, or creating the same audience multiple times across all your different properties. Sadly, the Analytics interface doesn’t offer batch creation or editing of audiences.

Enter: the Remarketing Audiences API!

This API sits under the Analytics Management API umbrella, and using it, it’s possible to manipulate your remarketing audiences to your heart’s content with JavaScript, Python, PHP or Java. You can use loops (or whatever method you like) to programmatically go through each one and edit it, or go through a list and make an audience for each item in the list, or make a generalisable function if you anticipate needing to do this multiple times.

The methods it offers are:

• get (to retrieve a single audience)

• list (list all audiences associated with a property)

• insert (create a new audience)

• update and patch (both of these update an audience, the difference being that ‘patch’ uses patch semantics)

The best part? It’s available to any Analytics accounts, not just Analytics 360.

The Set-Up

You can run this code on your own web server if you like - Google provides some detailed documentation on how to quickly set this up for each of the different languages and enable the API, set up authorisation, and so on. However, there is a simpler alternative: running it in AppsScript.

This blog won’t go into much detail on AppsScript in general (there’s so much to talk about that you could write a book on the subject), but essentially it’s a JavaScript platform in the cloud which attaches to a Google application, like a Sheet or Doc. Since it’s already based in a Google product, it doesn’t need you to create an authorised Analytics client object - you just need to enable the API in your script (Resources > Advanced Google Services...) and in the appropriate project in the Developer Console (see below).

Once you run the script, it will ask for authorisation to view and edit your Analytics accounts - just accept this, and you’re good to go. Much simpler! The other benefit is that you can display the results in the Google App you’re using - for example, as rows in a Sheet - and share that among your peers just as you would any other Google document.

Once you’ve got everything enabled and authorised, there’s the matter of actually using the API in your code. As before, there is of course detailed documentation for each language, although beware with the JavaScript documentation as there are a couple of syntax differences if you are running it in AppsScript (some more information here). Here’s an example comparing a request to retrieve a single audience:

AppsScript:

Externally (as per documentation):

Alternatively, if you’d just like to see how it works, or if you aren’t able to code, Google has its own API Explorer tool with fields for you to fill in so you can test it out for yourself: get, list, create, update, and patch.

However, this doesn’t take advantage of the full flexibility of the API, which is the fact that you can call the function as part of a larger block of code, such as to run it multiple times with different parameters.

Use Cases

So now we know how to set it up and how to use it. But why bother going to the trouble of setting it up? Let’s run through a couple of use case examples.

Say you’re a high-end clothing store with twenty different country sites, and the way that your Analytics account is set up you have a different property for each of these country sites. You’ve heard all about the wonders of remarketing audiences so you’ve started to set them up, and you want to target visitors who looked at a certain brand of jacket, to serve them ads when jackets under that brand go on sale.

Since remarketing audiences sit at the property level, you would need an audience for every property (not to mention that the pages with those products on them might be under different URL structures depending on the company’s site). This is tedious enough with just the one type of audience to set up, but if you start serving these ads and decide they’re very useful and want to set up new ones, you’ll be repeating the same work all over again.

Imagine having to do this over and over again... 

This is a perfect situation in which to use the API. You can write a function to take, as parameters, the segment (existing segments or dynamically created ones) of the audience you’d like to create, as well as the list of property IDs. Within this function, you could create a loop that iterates through the list of property IDs, and for each one, creates (using the ‘insert’ method) an audience in that property according to the segment you’ve defined.

Let’s say now that someone else has added some audiences in the Analytics interface and you want to check which properties they’ve been added to. Again, you could open the interface and click through each property, noting down which ones are where. Or, you could use the API to iterate through your list of properties and return a list of the remarketing audiences associated with each property (using, surprisingly, the ‘list’ method). You could even return these as rows in a Google Sheet to make it easy to read and share.

An example of using the list method to output all audiences for an account

Finally, let’s say that your site has had a structural overhaul, and the brand of jacket that you were using as the definition for your first batch of audiences has changed URLs. Obviously the old audiences with the old URLs are no longer applicable, and you’d like to change all of them. You know the drill by now - you can write a function that takes a list of properties, audience IDs, and segments, and iterates through them, updating each one to the appropriate new definition (using the ‘patch’ or ‘update’ methods). As an example of when you might need to change a URL-based audience definition:

With all of these, there is a twofold benefit in using the API over being in the interface: depending on how many different audiences you have to manipulate, it most likely saves you some time in the first instance, but also once you already have the function written, that’s the bulk of the time taken. In the future, if you ever want to do a similar task again, just run the function with new parameters and it’s as simple as that.

Hopefully, after all that, I’ve convinced you of the wonders of the Remarketing Audiences API. If you want some advice on how to use this to best optimise your remarketing strategies, or if you need our help setting it up, please don’t hesitate to get in touch!