How to use operators in Google Analytics API queries

To extract specific data from the Google Analytics API you will often need to use segments and filters to ensure you get the data you want. For example, you might want to find all the data on visitors with the userType of New Visitor, so you’d need to pass this to your Google Analytics API query using an operator.

Operators are basically a way of specifying how a given filter or segment should be extracted from your GA data. For example, you can use the == operator to find all the data on visitors with the userType of New Visitor, or you could use the != operator to find all the data on visitors who are not New Visitor.

In this post we’ll look at the different operators and how to use them in your Google Analytics API queries. We’ll be using my GAPandas Python package designed to make it quick and easy to query the Google Analytics API using Python and Pandas.

Google Analytics API query operators

The Google Analytics API includes query operators to handle: equals; does not equal; greater than; greater than or equal to, and less than or equal to. In addition, you can also create operators that identify whether a string contains a substring or not, or matches a regular expression (or regex) or not.

Since Google Analytics metrics contain numeric data and Google Analytics dimensions contain categorical data, you can only use certain operators on certain types of data. These are known as valid combinations. If you attempt to use an invalid combination, you’ll get an error.

Here’s a summary of the available operators and the data types they will work with.

Using operators with Google Analytics filters

You can apply Google Analytics operators to two places in an API query: the filters and the segment. As the name suggests, filters are used to filter your data and are the most basic of the two.

To use an operator with a Google Analytics filter using the API you need to call the metric or dimension with its ga: prefix followed by your operator and the value. For example, the filter ga:country==United Kingdom will return only sessions were the ga:country dimension was set to United Kingdom.

When passing operators to the API you ordinarily need to URL encode them, so == would become %3D%3D. However, GAPandas will automatically handle the URL encoding for you so you can just enter them in their unencoded form.

Using operators with filters

In the simple example below we’ll use the equals operator == to select all data from the API where the ga:country dimension is equal to United Kingdom. GAPandas will fetch the data from your Google Analytics account and return it in a neatly formatted Pandas dataframe.

import gapandas as gp
service = gp.get_service('client_secrets.json')
view = '1234567'

payload = {
    'start_date': '30daysAgo',
    'end_date': 'today',
    'metrics': 'ga:sessions',
    'dimensions': 'ga:date, ga:country, ga:userType',
    'filters': 'ga:country==United Kingdom'
}

df = gp.run_query(service, view, payload)
df.head()

Chaining multiple filters

If you have a more complex filter you want to run on your data, such as all the sessions from the United Kingdom who were using a mobile device running iOS, you can chain multiple filters together.

There are two main ways to chain operators: OR and AND. If you’re passing operators and want them to be considered with an OR operator you need to separate each filter query with a comma. For example, ga:county==United Kingdom,ga:userType==United States will return all sessions from either United Kingdom or United States.

To apply an AND operator to multiple filters you need to separate the values with a semicolon. For example, ga:county==United Kingdom;ga:country==United States will return all sessions from both United Kingdom and United States.

payload = {
    'start_date': '30daysAgo',
    'end_date': 'today',
    'metrics': 'ga:sessions',
    'dimensions': 'ga:date, ga:country, ga:userType',
    'filters': 'ga:country==United Kingdom;ga:country==United States'
}

df = gp.run_query(service, view, payload)
df.head()

Using operators with Google Analytics segments

The other way to select specific data from your Google Analytics account via the API is using segment. The neat thing about segment is that you can set them to extract data based on either the session or the user to group the data differently. You can also chain lots of them together to create very sophisticated queries.

In the below example we’ll create a segment that will extract all sessions with a sessionDuration of greater than or equal to 90 seconds. If you wanted to do the same for users, you’d substitute sessions:condition:: for users::condition:: before you call your first dimension or metric.

payload = {
    'start_date': '30daysAgo',
    'end_date': 'today',
    'metrics': 'ga:sessionDuration',
    'dimensions': 'ga:date, ga:country, ga:userType',
    'segment': 'sessions::condition::ga:sessionDuration>90'
}

df = gp.run_query(service, view, payload)
df.head()

Next, we’ll combine a few different operators to create a more complex segment. sessions::condition::ga:sessionDuration>90;ga:country==Guernsey,ga:country==Jersey will extract all sessions where the sessionDuration is greater than or equal to 90 seconds and the country is either Guernsey or Jersey.

Note that we used a semicolon ; and operator between the two segments. This is because the ; is a delimiter for the API and the ; is not a valid character in a segment, while , or comma is the operator for OR, so it will select either `

payload = {
    'start_date': '30daysAgo',
    'end_date': 'today',
    'metrics': 'ga:sessionDuration',
    'dimensions': 'ga:date, ga:country, ga:userType',
    'segment': 'sessions::condition::ga:sessionDuration>90;ga:country==Guernsey,ga:country==Jersey'
}

df = gp.run_query(service, view, payload)
df.head()

Matt Clarke, Tuesday, January 25, 2022