Before you start
This article explain how to use custom filters for all Google Analytics widgets, except for the current visitor gauge and current visitor map. If you’re setting up one of these two widgets, please check this other article instead.Most Google Analytics widgets use Google Analytics' Core Reporting API which lets you request data from Google Analytics to display as a metric in Geckoboard.
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 Core Reporting API, the name
always begin with ga: followed by the dimension or metric you want to filter by. Google has a great resource called the Dimensions & Metrics Explorer that lists and describes all of the dimensions and metrics available through the Core Reporting API.
Popular dimensions and metrics include:
- campaign
- year
- keyword
- city
- pageTitle
- language
- transactions
- userAgeBracket
- date
- medium
- day
- goalPreviousStep1
- browser
- timeOnPage
- country
- source
- month
- productBrand
- pagePath
- screenResolution
- bounceRate
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
==
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
==
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
\,
- semicolon
- 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.
- Maximum length of 128 characters — Regular expressions longer than 128 characters result in a
Example of a custom filter statement
ga:source==twitter
Where ga:source
is the name of the filter expressed as ga: 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 finallytwitter
is the expression that contains the value for the comparison.
When applied to a Google Analytics widget (such as Sessions), this custom filter will include only results where the source is Twitter (and results from any other source will be filtered out). In other words, only sessions that had Twitter as source.
More examples
ga:keyword==geckoboard
Referring keyword is ‘geckoboard’
ga:pageTitle==Contact
Title of page is ‘Contact’ (exact match)
ga:pagePath=~contact
URL of page contains ‘contact’ anywhere
ga:country==United Kingdom
Visitor country is United Kingdom
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):
ga:country==United%20States,ga:country==Canada
Firefox users on (Windows OR Macintosh) operating systems:
ga:browser==Firefox;ga:operatingSystem==Windows,ga: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.
Examples: (each must be URL encoded)
Country is United States AND the browser is Firefox:
ga:country==United%20States;ga:browser==Firefox
Operating system is (Windows OR Macintosh) AND browser is (Firefox OR Chrome):
ga:operatingSystem==Windows,ga:operatingSystem==Macintosh;ga:browser==Firefox,ga:browser==Chrome
Country is United States AND sessions are greater than 5:
ga:country==United%20States;ga:sessions>5
Example of custom filters combined
ga:country==United Kingdom;ga:city!=London
Country is United Kingdom and City is not London
ga:eventCategory==DownloadReport,ga:event
Category==DownloadCaseStudy
Show all events with the category DownloadReport or DownloadCaseStudy
ga:eventCategory==DownloadReport,ga:event
Label!=ShareCaseStudy
Show all events with the category Download but not Label ShareCaseStudy