Google Analytics: API Filter Expressions

ga:medium%3D%3Dreferral

The filters query string parameter restricts the data returned from your request. To use the filters parameter, supply a dimension or metric on which to filter, followed by the filter expression. For example, the following query requests ga:pageviews and ga:browser for view (profile) 12134, where the ga:browser dimension starts with the string Firefox:

ga:browser%3D~%5EFirefox

Filtered queries restrict the rows that do (or do not) get included in the result. Each row in the result is tested against the filter: if the filter matches, the row is retained and if it doesn’t match, the row is dropped.

• URL Encoding: Filter operators and expressions must be URL encoded.
• Dimension filtering: Filtering occurs before any dimensions are aggregated, so that the returned metrics represent the total for only the relevant dimensions. In the example above, the number of pageviews would be only those pageviews where Firefox is the browser.
• Metrics filtering: Filtering on metrics occurs after the metrics are aggregated.
• Valid combinations: You can filter for a dimension or metric that is not part of your query, provided all dimensions/metrics in the request and the filter are valid combinations. For example, you might want to query for a dated list of pageviews, filtering on a particular browser. See the Dimensions and Metrics Reference for more information. The Analytics Edge connectors will grey-out fields that are not valid.

Filter Syntax

A single filter uses the form:

ga:name operator expression

In this syntax:

• name — the name of the dimension or metric to filter on. For example: ga:pageviews filters on the pageviews metric.
• operator — defines the type of filter match to use. Operators are specific to either dimensions or metrics.
• expression — states the values to be included in or excluded from the results. Expressions use regular expression syntax.

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.

Filter Expressions

There are a few important rules for filter expressions:

• URL encoding — Characters such as & must be URL-encoded. A good online utility to do this can be found at https://www.urlencoder.org/
• 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.

Combining Filters

Filters can be combined using OR and AND Boolean logic. This allows you to effectively extend the 128 character limit of a filter expression.

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.

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.