Segmentation

All methods in the Reporting API can return results for each individual data segment, as well as for the entire website. 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 or ym:s:pageDepth. You can use parameters, for example, ym:s:goal<goal_id>IsReached, to filter goal completion events, where goal_id is the ID of the goal.

    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 isn't available.

  • operator: Filtering operator. Specifies which type of filtering to apply. For example, == or >=. The !=, <, <=, ==, >, and >= operators are supported for metrics. For more information, see List of dimensions and metrics.

  • value is the comparison value. In the string with the value, the characters ' and \ must be escaped with a \.

Note

The request language (lang parameter) affects the filter values. Specify the lang=ru parameter for Russian names. For example, ym:s:regionCityName=='Saint Petersburg'.

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'

You can combine filters by dimensions and metrics only 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 detects robots, see Help.

Sets and relationships

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

  • Segmentation by dimensions from Sets (see the Session parameters section for reference).
  • 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 it if you need at least one item from the set or pageview in the session that meets the condition in parentheses.

ALL

All

Use it if you need all elements of the set or pageviews in the session to meet the condition in parentheses.

NONE

Does not contain

Use it if you want 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 contain the client_id session parameter will look like this:

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

Metrics for sets can be filtered using dimensions of this set:

<metric>[<metric_filter>]

For example, the total value 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 total 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 for requests to URLs that contain category1:

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

Number of sessions without requests to URLs that contain category1:

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

Number of sessions for requests to URLs 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 driven by search queries that include a specific keyword fragment:

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

Segmentation examples

Use these examples to create more detailed reports. The filter relies on dimension values. For instructions on how to obtain these values, see Localization and interpretation of dimension values.

For examples, see the Examples.Presets section.

Previous
Recommendation widget
Next
Operators