Segmentation

All methods in the Reports API can return results for each separate data segment, as well as for the entire site. To set the segment, use the filters parameter.

You can segment a request by dimensions and metrics. The dimension or metric does not have to be specified in the request.

Dimension filters are applied to source (ungrouped) data, and metric filters are applied to grouped rows in the result.

To set a filter in the request URL, use .

Filter format

attribute operator 'value'

where

  • attribute — The dimension or metric. For example, ym:s:trafficSource or ym:s:pageDepth.
  • operatorFiltration operator. Specifies which type of filtration to apply. For example, == or >=.
  • value — Value for comparison. In the string with the value, the symbols ' and \ must be escaped using the  \ symbol.

In addition, the following limits are imposed: a maximum of 10 unique dimensions and metrics, 20 separate filters, and 10 000 characters in the filter string.

For example, to get data only for sessions from Moscow, use this filter:

filters=ym:s:regionCityName==''

Use the following operators in filters:

Different dimensions have different filtration operators available.

To combine filters in a request, use the AND and OR operators:

ym:s:regionCityName=='' OR ym:s:regionCityName==''

You can also set priority using parentheses:

(ym:s:regionCityName=='' OR ym:s:regionCityName=='') AND ym:s:sex=='male'

Filters by dimensions and by metrics can only be combined at the top level (without parentheses) and only using the AND operator.

Note.

The request language (the lang parameter) affects the filter values. We recommend always specifying this parameter.

Categories and relationships

A single session may have multiple parameters for sessions or pageviews. The API allows you to make more specific requests using special expanded syntax. It can be applied in the following cases:

  • Segmentation by dimensions from a Category (for example, see the section Session parameters).
  • Segmentation of sessions by pageviews.

Syntax

You can use the following operators in the filter syntax:

[EXISTS|ALL|NONE](<filter>)
Operator Value Description
EXISTS Contains Use if you need at least one item from the category/pageview in the session that meets the condition in parentheses.
ALL All Use if you need all items in the category/pageviews in the session to meet the condition in parentheses.
NONE Does not contain Use if you need none of the items in the category/pageviews in the session to meet the condition in parentheses.

For example, a filter for sessions that contains the client_id session parameter will look like this:

filters=EXISTS(ym:s:paramsLevel1=='client_id')

Metrics for categories can be filtered using dimensions of this category:

<metric>(<metric_filter>)

For example, the total sum of session parameters for all parameters with the top-level money key:

metrics=ym:s:sumParams(ym:s:paramsLevel1=='money')

Filters can also be used on categories without the EXISTS, ALL, or NONE operators. In this case, substitution operators will be applied:

Operator Substitution operators
EXISTS == > < >= <= =@ =~ =* !
NONE != !@ !~ !* =n
Click to see examples

The sum of numerical values of session parameters for all parameters with the top-level money key:

metrics=ym:s:sumParams(ym:s:paramsLevel1=='money')

Number of order:created parameters:

metrics=ym:s:paramsNumber(ym:s:paramsLevel1=='order' AND ym:s:paramsLevel2=='created')

Segmentation by sessions with the {"new_client":"no"} session parameter:

filters=EXISTS(ym:s:paramsLevel1=='new_client' AND ym:s:paramsLevel2=='no')

Segmentation by sessions with the {"new_client":"no"} session parameter and the {"orange_button":"yes"} session parameter:

filters=EXISTS(ym:s:paramsLevel1=='new_client' AND ym:s:paramsLevel2=='no') AND EXISTS(ym:s:paramsLevel1=='orange_button' AND ym:s:paramsLevel2=='yes')

Segmentation by sessions with the {"new_client":"no"} session parameter but without the {"orange_button":"yes"} session parameter:

filters=EXISTS(ym:s:paramsLevel1=='new_client' AND ym:s:paramsLevel2=='no') AND NONE(ym:s:paramsLevel1=='orange_button' AND ym:s:paramsLevel2=='yes')

Number of sessions by queries to a URL containing category1:

metrics=ym:s:visits&filters=EXISTS(ym:pv:URL=='category1')

Number of sessions without queries to a URL containing category1:

metrics=ym:s:visits&filters=NONE(ym:pv:URL=='category1')

Segmentation usage examples

Use these examples to create more detailed reports.

Number of sessions and users, including search engines

dimensions=ym:s:searchEngineName

metrics=ym:s:visits,ym:s:users

filters=ym:s:trafficSourceName=='Search engine traffic'

Number of sessions and new users, including search engines

dimensions=ym:s:searchEngineName

metrics=ym:s:visits,ym:s:users

filters=ym:s:trafficSourceName=='Search engine traffic' AND ym:s:isNewUser=='Yes'

Number of sessions with depth greater than 5 pages

metrics=ym:s:visits

filters=ym:s:pageViews>5

Keyword sources report

This example helps you create a report that includes users who visited the page indicated in the request. In this request, the page URL contains the specified id.

To set id in the filters parameter, use a regular expression: .*/id[0-9]+/.*

preset=sources_search_phrases

filters=ym:pv:URL=~'.*/id[0-9]+/.*'