Segmentation

Attention.

Access tokens will not be accepted in URL parameters starting February 13, 2019. To continue working with the Yandex.Metrica API, set up authorization by passing the token in the HTTP header.

The outdated authorization method will be temporarily disabled on January 23, January 30, and February 6 for maintenance. Authorization using URL parameters will be unavailable on these dates.

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

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=='Moscow'

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

You can also set priority using parentheses:

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

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>)
OperatorValueDescription
EXISTSContainsUse if you need at least one item from the category/pageview in the session that meets the condition in parentheses.
ALLAllUse if you need all items in the category/pageviews in the session to meet the condition in parentheses.
NONEDoes not containUse 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:

OperatorSubstitution 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=='Traffic from search engines'

https://api-metrica.yandex.net/stat/v1/data?dimensions=ym:s:searchEngineName&metrics=ym:s:visits,ym:s:users&filters=ym:s:trafficSourceName=='Traffic from search engines'&id=44147844

Number of sessions and new users, including search engines

dimensions=ym:s:searchEngineName

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

filters=ym:s:trafficSourceName=='Traffic from search engines' AND ym:s:isNewUser=='Yes'

https://api-metrica.yandex.net/stat/v1/data?dimensions=ym:s:searchEngineName&metrics=ym:s:visits,ym:s:users&filters=ym:s:trafficSourceName=='Traffic from search engines' 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-metrica.yandex.net/stat/v1/data?metrics=ym:s:visits&filters=ym:s:pageViews>5&id=44147844

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]+/.*'

https://api-metrica.yandex.net/stat/v1/data?preset=sources_search_phrases&filters=ym:pv:URL=~'.*/id[0-9]+/.*'&id=44147844