Segmentation

All methods in the Reporting 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.

  1. Filter format
  2. Example using segmentation

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. 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 the \ symbol.

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