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.
Filter format
attribute operator 'value'
where
- attribute — The dimension or metric. For example,
ym:s:trafficSource
orym: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.
- value is the comparison value. In the string with the value, the symbols
'
and\
must be escaped using the\
symbol.
- 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