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 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 is the dimension or metric, For example, ym:ge:mobileDeviceModel or ym:ge:users.
operator is the filtration operator and specifies which type of filtration to apply. For example, ==.
value is the comparison value. In the string with the value, the symbols ' and \ must be escaped using a \.

In addition, the following limits are imposed: a maximum of 10 unique dimensions and metrics, 20 separate filters, and 2000 characters in the filter string.

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

filters=ym:ge:regionCity=='Moscow'

Different filtration operators are available for different dimensions (for example, see the Relations column in the Application section).

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

&metrics=ym:ge:users&dimensions=ym:ge:age&filters=NOT(ym:ge:age!=18)

ym:ge:regionCity=='Moscow' OR ym:ge:regionCity=='St. Petersburg'

You can also set priority using parentheses:

(ym:ge:regionCity=='Moscow' OR ym:ge:regionCity=='St. Petersburg') AND ym:ge:gender=='male'

You can combine dimension filters and metric filters, but only at the top level (outside of parentheses) and only using the AND operator.

Note. The request language (the lang parameter) affects filter values. We recommend always specifying this parameter.

Example using segmentation

Number of users based on the region

dimensions=ym:ge:mobileDeviceModel

metrics=ym:ge:users

filters=ym:ge:regionCityName=='Moscow'

curl -X GET \
  'https://api.appmetrica.yandex.ru/stat/v1/data?id=1111&metrics=ym:ge:users&dimensions=ym:ge:mobileDeviceModel&filters=ym:ge:regionCityName==%27Москва%27' \
  -H 'Authorization: OAuth 05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037'
Copied to clipboard

GET /stat/v1/data?id=1111&metrics=ym:ge:users&dimensions=ym:ge:mobileDeviceModel&filters=ym:ge:regionCityName=='Москва' HTTP/1.1
Host: api.appmetrica.yandex.ru
Authorization: OAuth 05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037
Copied to clipboard