Using custom filters for current visitor gauge and current visitor map

Before you start

This article explain how to use custom filters for the current visitor gauge and current visitor map widgets exclusively. If you’re setting up any other Google Analytics widget, please check this other article instead.

The current visitor gauge and current visitor map widgets use Google Analytics' Real Time Reporting API  which lets you track data and events occurring currently on your website.

To connect your Google Analytics data to Geckoboard, you must be on a Pro plan.

Syntax of custom filters

The syntax of custom filters is always the same:

name operator expression

Filter names

For Real-Time Reporting, the name always begin with rt: followed by the dimension or metric you want to filter by.  All the dimensions and metrics available through the Real-Time Reporting API are listed in Google's documentation 

Popular dimensions and metrics include:

  • campaign
  • pageTitle
  • referralPath
  • browser
  • source
  • pagePath
  • minutesAgo
  • country
  • region
  • city
  • mobileDeviceModel
  • eventAction

Filter operators

There are six filter operators for dimensions and six filter operators for metrics. The operators must be URL-encoded in order to be included in URL query strings.

Tip: Use the Data Feed Query Explorer to design filters that need URL encoding, since the Query Explorer automatically encodes URLS containing strings and spaces.

Metric Filters

Operator
Description
URL Encoded Form

==

Equals

%3D%3D

!=

Does not equal

!%3D

>

Greater than

%3E

<

Less than

%3C

>=

Greater than or equal to

%3E%3D

<=

Less than or equal to

%3C%3D

Dimension Filters

Operator
Description
URL Encoded Form

==

Exact match

%3D%3D

!=

Does not match

!%3D

=@

Contains substring

%3D@

!@

Does not contain substring

!@

=~

Contains a match for the regular expression

%3D~

!~

Does not match regular expression

!~

Filter expressions

The expression states the values to be included in or excluded from the results.

There are a few important rules for filter expressions:

  • URL-reserved characters — Characters such as & must be url-encoded in the usual way.
  • Reserved characters — The semicolon and comma must be backslash escaped when they appear in an expression:
    • semicolon \;
    • comma \,
  • Regular Expressions — You can also use regular expressions in filter expressions using the =~ and !~ operators. Their syntax is similar to Perl regular expressions and have these additional rules:
    • Maximum length of 128 characters — Regular expressions longer than 128 characters result in a 400 Bad Request status code returned from the server.
    • Case sensitivity — Regular expression matching is case-insensitive.

Example of a custom filter statement

rt:source==twitter

Where rt:source is the name of the filter expressed as rt: and the specific dimension you want to filter by (in this case source), the operator is how you want the dimension to be compared (==means Equals), and finallytwitteris the expression that contains the value for the comparison.

When applied to a Google Analytics widget (such as the current visitor map), this custom filter will include only results where the source is Twitter (and results from any other source will be filtered out). 

rt_filter.png

visitors_map.png

Combining custom filters

Filters can be combined using OR and AND boolean logic to create a very specific set of data within a metric.

OR

The OR operator is defined using a comma (,). It takes precedence over the AND operator and may NOT be used to combine dimensions and metrics in the same expression.

Examples: (each must be URL encoded)

Country is either (United States OR Canada):
rt:country==United%20States,rt:country==Canada

Firefox users on (Windows OR Macintosh) operating systems:
rt:browser==Firefox;rt:operatingSystem==Windows,rt:operatingSystem==Macintosh

AND

The AND operator is defined using a semi-colon (;). It is preceded by the OR operator and CAN be used to combine dimensions and metrics in the same expression.

Example of custom filters combined:

Country is United States AND the browser is Firefox:
rt:country==United%20States;rt:browser==Firefox

Operating system is (Windows OR Macintosh) AND browser is (Firefox OR Chrome):
rt:operatingSystem==Windows,rt:operatingSystem==Macintosh;rt:browser==Firefox,rt:browser==Chrome

Country is United States AND hit occurred less than 5 minutes ago:
rt:country==United%20States;rt:minutesAgo<5

Was this article helpful?

Awesome! 👍 Thanks so much for your feedback!

Sorry about that! Start a conversation now.

We're ready to help, 24 hours a day, 5 days a week

Get support
  • Fernanda Customer Success Avatar

    Megan

    USA
  • Hariharan Customer Success Avatar

    Hariharan

    India
  • Fernanda Customer Success Avatar

    Yasmin

    Spain
  • Luis Customer Success Avatar

    Luis

    UK
  • Richard Customer Success Avatar

    Richard

    UK
  • Fernanda Customer Success Avatar

    Fernanda

    Brazil
  • Heather Customer Success Avatar

    Heather

    USA