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. 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 URL encoding.

  1. Filter format
  2. Categories and relationships
    1. Syntax
    2. Examples of operator usage
  3. Segmentation usage examples
    1. Types of traffic sources
    2. Number of sessions and users from search engines without robot sessions
    3. Number of sessions and users from search engines
    4. Number of sessions and new users from search engines
    5. Number of sessions with depth greater than 5 pages

Filter format

attribute operator 'value'

where

  • attribute — The dimension or metric. For example, ym:s:trafficSource or ym:s:pageDepth.

    The metric by which the data is filtered should be specified in the metrics parameter. In comparison reports (segment or comparison-drill down), filtering by metric is not available.

  • operatorFiltration operator. Specifies which type of filtration to apply. For example, == or >=.
  • value is the comparison value. In the string with the value, the symbols ' and \ must be escaped using the \ symbol.
Note. The request language (the lang parameter) affects the filter values.
Restrictions:
  • Maximum number of unique dimensions and metrics is 10.
  • Maximum number of individual filters is 20.
  • Maximum string length in a filter is 10,000 characters.
  • Maximum number of values in a single filter condition is 100..

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

filters=ym:s:regionCityName=='Moscow'

For different dimensions, you can use different filtering operators (for example, see the Relations column in the Sources section).

To combine filters in a request, use the binary AND, OR operators and the unary NOT operator:

&metrics=ym:s:visits&dimensions=ym:s:age&filters=NOT(ym:s:age!=18)
ym:s:regionCityName=='Moscow' OR ym:s:regionCityName=='Saint Petersburg'

You can also set priority using parentheses:

(ym:s:regionCityName=='Moscow' OR ym:s:regionCityName=='Saint Petersburg') 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.

This way, you can track statistics excluding robot sessions, using the parameter filters=ym:s:isRobot=='No' (example). For more details on how Yandex Metrica identifies robots, see the Help section.

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:

  • Segmenting by dimensions from Sets (see the Session parameters section, for example).
  • 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 elements of the set or pageviews in the session to meet the condition in parentheses.
NONE Does not contain Use if you need none of the elements in the set or pageviews in the session to meet the condition in parentheses.
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 elements of the set or pageviews in the session to meet the condition in parentheses.
NONE Does not contain Use if you need none of the elements in the set or 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']

You can filter sets without the EXISTS, ALL, or NONE operators. In this case, the EXISTS operator is used automatically.

List of logical operators.

Examples of operator usage

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 parameters for {"order":"created"}:

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')

Number of sessions for requests to the URL starting with https://example.com/tariff/, including the specified page:

metrics=ym:s:visits&filters=EXISTS(ym:pv:URL=*'https://example.com/tariff/*')

Number of sessions for search queries that include a keyword fragment:

metrics=ym:s:visits&filters=EXISTS(ym:s:<attribution>SearchPhrase=*'*yandex*')

Segmentation usage examples

Use these examples to create more detailed reports. Filter relies on using dimension values. To learn how to obtain these values, see Localization and interpretation of dimension values.

Types of traffic sources

dimensions=ym:s:lastTrafficSource

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

filters=ym:s:lastTrafficSource=.('organic','direct','referral')

https://api-metrika.yandex.net/stat/v1/data?dimensions=ym:s:lastTrafficSource&metrics=ym:s:visits,ym:s:users&filters=ym:s:lastTrafficSource=.('organic','direct','referral')&id=44147844&lang=ru

Number of sessions and users from search engines without robot sessions

Yandex Metrica identifies robots based on behavioral factors and other technical signals. Filtering robots in Yandex Metrica reports helps you get accurate data. For example, bounce rate, time on site, and page depth. To learn more, see the Help section.

dimensions=ym:s:searchEngine

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

filters=ym:s:trafficSource=='organic' AND ym:s:isRobot=='No'

https://api-metrika.yandex.net/stat/v1/data?dimensions=ym:s:searchEngine&metrics=ym:s:visits,ym:s:users&filters=ym:s:trafficSource=='organic' AND ym:s:isRobot=='No'&id=44147844

Number of sessions and users from search engines

dimensions=ym:s:searchEngine

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

filters=ym:s:trafficSource=='organic'

https://api-metrika.yandex.net/stat/v1/data?dimensions=ym:s:searchEngine&metrics=ym:s:visits,ym:s:users&filters=ym:s:trafficSource=='organic'&id=44147844

Number of sessions and new users from search engines

dimensions=ym:s:searchEngine

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

filters=ym:s:trafficSource=='organic' AND ym:s:isNewUser=='Yes'

https://api-metrika.yandex.net/stat/v1/data?dimensions=ym:s:searchEngine&metrics=ym:s:visits,ym:s:users&filters=ym:s:trafficSource=='organic' AND ym:s:isNewUser=='Yes'&id=44147844

Number of sessions with depth greater than 5 pages

metrics=ym:s:visits

filters=ym:s:pageViews>5

https://api-metrika.yandex.net/stat/v1/data?metrics=ym:s:visits&filters=ym:s:pageViews>5&id=44147844

All segmentation examples