Segmentation

All methods in the Reporting API can return results for separate data segments or the entire site. To set the segment, use the filters parameter.

You can segment a request by dimensions and metrics. The dimensions and metrics don't 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 URL encoding.

  1. Filter format
  2. Categories and relationships
  3. Segmentation usage examples

Filter format

attribute operator 'value'

where

  • attribute is the dimension or metric, such as ym:s:trafficSource or ym:s:pageDepth. In comparison reports (for segments or drill down comparisons), metric filters aren't available.
  • operator is the filtration operator and specifies which type of filtration to apply, such as == or >=.
  • value is the comparison value. In the string with the value, the symbols ' and \ must be escaped using a \.

The following limits apply: 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=='Moscow'

Different filter operators are available for different dimensions (for example, see the Relations column under Sources).

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

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

Dimension and metric filters can only be combined at the top level (without parentheses) and only using the AND operator.

Note. The request language (the lang parameter) affects filter values.

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 Categories (for example, see 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 looks 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 are applied:

Operator Substitution operators
EXISTS == > < >= <= =@ =~ =* ! =.
NONE != !@ !~ !* !.
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. Dimension values are used for filtering. For more information about how to get 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, including 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, including 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