Examples

The examples provided below are helpful for solving common tasks.

These requests don't define the date1 and date2 parameters (the dates of the beginning and end of the reporting period). By default, the reporting period is 7 days (including the current day).

A demo account is used as the id parameter.

The /stat/v1/data method is used for making requests.

Note. The request language (the lang parameter) affects filter values.
  1. Presets
  2. Segmentation
  3. Dimensions and metrics
  4. Displaying data by time
  5. Comparing segments
  6. Drill down

Presets

“Sources, Summary” report

preset=sources_summary

https://api-metrika.yandex.net/stat/v1/data?preset=sources_summary&id=44147844

“Sources, summary” report. Users from California

preset=sources_summary

filters=ym:s:regionAreaName=='State of California'

Report data is segmented using the parameter filters=ym:s:regionAreaName=='State of California'.

https://api-metrica.yandex.net/stat/v1/data?preset=sources_summary&filters=ym:s:regionAreaName=='State of California'&id=44147844

“Keywords” report

preset=sources_search_phrases

https://api-metrika.yandex.net/stat/v1/data?preset=sources_search_phrases&id=44147844

“Browsers” report

preset=tech_platforms

dimensions=ym:s:browser

This preset helps create a report on user browsers, without accounting for the browser version.

https://api-metrika.yandex.net/stat/v1/data?preset=tech_platforms&dimensions=ym:s:browser&id=44147844

where the dimensions=ym:s:browser parameter sets a dimension in the preset for grouping resulting data.

Content analytics. Category report

Category report

Use this preset to create a report with general statistics by category.

publishers_rubrics

https://api-metrika.yandex.net/stat/v1/data?preset=publishers_rubrics&id=44147844&date1=today&date2=today
Traffic sources

This preset helps you create a report on sources that users clicked through to the site content.

preset=publishers_sources
https://api-metrika.yandex.net/stat/v1/data?preset=publishers_sources&id=44147844&date1=today&date2=today

Segmentation

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 and users, including the specified region

dimension=ym:s:regionCityName=.('Moscow', 'Saint Petersburg')

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

https://api-metrika.yandex.net/stat/v1/data?metrics=ym:s:visits,ym:s:users&dimension=ym:s:regionCityName=.('Moscow','Saint Petersburg')&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

Dimensions and metrics

Number of sessions

metrics=ym:s:visits

https://api-metrika.yandex.net/stat/v1/data?metrics=ym:s:visits&id=44147844

Number of users and conversion rate for a specified goal

This example uses parametrization of the ym:s:goal<goal_id>conversionRate metric by goal ID:

metrics=ym:s:users,ym:s:goal<goal_id>conversionRate

dimensions=ym:s:trafficSource

goal_id=<goal ID>

The report will include the number of users who reached the specified goal. Data is grouped by traffic source.

https://api-metrika.yandex.net/stat/v1/data?dimensions=ym:s:trafficSource&metrics=ym:s:users,ym:s:goal%3Cgoal_id%3EconversionRate&goal_id=30606879&id=44147844

Conversion rate for multiple goals

This example uses parametrization of the ym:s:goal<goal_id>conversionRate metric by the goal ID in the expression body.

metrics=ym:s:users,ym:s:goal<first goal ID>conversionRate,ym:s:goal<second goal ID>conversionRate

https://api-metrika.yandex.net/stat/v1/data?metrics=ym:s:users,ym:s:goal30606879conversionRate,ym:s:goal30606884conversionRate&id=44147844

Content analytics. Material report

Report on the number of site content views. Data is grouped by article.

dimensions=ym:s:publisherArticle

metrics=ym:s:publisherviews

filters=(ym:s:publisherArticle!n)

sort=-ym:s:publisherviews

https://api-metrika.yandex.net/stat/v1/data?ids=44147844&date1=2019-10-01&date2=2019-10-01&dimensions=ym:s:publisherArticle&metrics=ym:s:publisherviews&filters=(ym:s:publisherArticle!n)&sort=-ym:s:publisherviews

Displaying data by time

The /stat/v1/data/bytime method is used for getting data.

The examples below show how to get data for a specific period of time. This data can be grouped together. To define the type or number of groups (dimensions), use the row_ids or top_keys parameter. If the row_ids parameter is omitted, the top_keys parameter is used automatically. By default, it is set to 7 (the maximum is 30).

More information about parameters

  • row_ids — Array of arrays in JSON format. Each sub-array may contain dimension values (name or id) corresponding to the set of values defined in the request for the dimensions parameter. The sub-array size indicates the dimensions that data is grouped by.

    For example, if data is grouped by a single dimension, the size of this sub-array is 1.

    ...?row_ids=[["Russia"]]&...&dimensions=ym:s:regionCountryName,ym:s:regionAreaName,ym:s:regionCityName&...
    Note.

    If a sub-array contains dimension values for a single group (for example, Geography), data is grouped by the last specified dimension.

    ...?row_ids=[["Russia","Saratovskaya region","Saratov"]]&...&dimensions=ym:s:regionCountryName,ym:s:regionAreaName,ym:s:regionCityName&...

    To use multiple sub-arrays, separate them with commas:

    ...?row_ids=[["Russia"],["Russia","Saratovskaya region"],["Russia","Saratovskaya region","Saratov"]]&...&dimensions=ym:s:regionCountryName,ym:s:regionAreaName,ym:s:regionCityName&...

  • The top_keys parameter takes the first values from the dataset in the first dimension specified in the request. You can set the quantity of these values (30 maximum). Data is sorted in the API response by decreasing order of the first value of the metrics parameter.

    ...?top_keys=3&...&dimensions=ym:s:regionCountry,ym:s:regionArea,ym:s:regionCity&group=day&ids=44147844&metrics=ym:s:visits

“Sources, Summary” report

In the example, the response will contain data grouped by the type of traffic source.

Example without the row_ids parameter. The top_keys parameter is used by default:

https://api-metrika.yandex.net/stat/v1/data/bytime?date1=2018-01-01&date2=2018-01-14&group=day&dimensions=ym:s:<attribution>TrafficSource&attribution=last&ids=44147844&metrics=ym:s:visits

Example with a value set for the top_keys parameter:

https://api-metrika.yandex.net/stat/v1/data/bytime?top_keys=3&date1=2018-01-01&date2=2018-01-14&group=day&dimensions=ym:s:<attribution>TrafficSource&attribution=last&ids=44147844&metrics=ym:s:visits

The examples below show reports that specify dimension values for the Sources group.

Traffic sources for the day:

https://api-metrika.yandex.net/stat/v1/data/bytime?row_ids=[["direct"],["organic","organic.yandex"],["social","social.ya"],["ad"]]&date1=2018-01-13&date2=2018-01-13&group=day&dimensions=ym:s:<attribution>TrafficSource,ym:s:<attribution>SourceEngine&attribution=last&ids=44147844&metrics=ym:s:visits

Traffic sources for two weeks, grouped by days:

https://api-metrika.yandex.net/stat/v1/data/bytime?row_ids=[["direct"],["organic","organic.yandex"],["social","social.ya"],["ad"]]&date1=2018-01-01&date2=2018-01-14&group=day&dimensions=ym:s:<attribution>TrafficSource,ym:s:<attribution>SourceEngine&attribution=last&ids=44147844&metrics=ym:s:visits

Traffic sources for two weeks, grouped by weeks. Data is grouped by calendar weeks:

https://api-metrika.yandex.net/stat/v1/data/bytime?row_ids=[["direct"],["organic","organic.yandex"],["social","social.ya"],["ad"]]&date1=2018-01-01&date2=2018-01-14&group=week&dimensions=ym:s:<attribution>TrafficSource,ym:s:<attribution>SourceEngine&attribution=last&ids=44147844&metrics=ym:s:visits

Users - Geography report

In this example, the report will contain data on the number of users, grouped by geographical location.

Example without the row_ids parameter. The top_keys parameter is used by default:

https://api-metrika.yandex.net/stat/v1/data/bytime?date1=2018-01-01&date2=2018-01-14&group=day&dimensions=ym:s:regionCountry,ym:s:regionArea,ym:s:regionCity&ids=44147844&metrics=ym%3As%3Avisits

Example with a value set for the top_keys parameter:

https://api-metrika.yandex.net/stat/v1/data/bytime?top_keys=3&date1=2018-01-01&date2=2018-01-14&group=day&dimensions=ym:s:regionCountry,ym:s:regionArea,ym:s:regionCity&ids=44147844&metrics=ym%3As%3Avisits

The examples below show reports that specify dimension values for the Geography group.

The number of sessions from Russia, the Saratovskaya region, and Saratov over two weeks. Data is grouped by calendar weeks:

https://api-metrica.yandex.net/stat/v1/data/bytime?row_ids=[["Russia"],["Russia","Saratovskaya%region"],["Russia","Saratovskaya%20region","Saratov"]]&date1=2018-01-01&date2=2018-01-14&group=week&dimensions=ym:s:regionCountryName,ym:s:regionAreaName,ym:s:regionCityName&ids=44147844&metrics=ym%3As%3Avisits

The number of sessions from Russia, Moscow, the Moscow region, Saint Petersburg, and the Leningradskaya region over two weeks:

https://api-metrica.yandex.net/stat/v1/data/bytime?row_ids=[["Russia"],["Russia","Moscow%20and%Moscow region"],["Russia","Saint Petersburg%20and%20Leningradskaya region"]]&date1=2018-01-01&date2=2018-01-14&group=week&dimensions=ym:s:regionCountryName,ym:s:regionAreaName,ym:s:regionCityName&ids=44147844&metrics=ym%3As%3Avisits

Report on operating systems and browsers

In this example, the report will contain data on the number of users, grouped by the type of operating system they are using.

Example without the row_ids parameter. The top_keys parameter is used by default:

https://api-metrika.yandex.net/stat/v1/data/bytime?date1=2018-01-01&date2=2018-01-14&group=day&dimensions=ym:s:operatingSystemRootName,ym:s:browserName&ids=44147844&accuracy=medium&metrics=ym:s:visits

Example with a value set for the top_keys parameter:

https://api-metrika.yandex.net/stat/v1/data/bytime?top_keys=10&date1=2018-01-01&date2=2018-01-14&group=day&dimensions=ym:s:operatingSystemRootName,ym:s:browserName&ids=44147844&accuracy=medium&metrics=ym:s:visits

The examples below show reports that specify dimension values for the Operating systems and Browsers groups.

The number of sessions for Windows, Yandex.Browser, and Internet Explorer users. Data is grouped by days:

https://api-metrica.yandex.net/stat/v1/data/bytime?row_ids=[["Windows"],["Windows","Yandex.Browser"],["Windows","MSIE"]]&date1=2018-01-01&date2=2018-01-14&group=day&dimensions=ym:s:operatingSystemRootName,ym:s:browserName&ids=44147844&accuracy=medium&metrics=ym:s:visits

Data is grouped by calendar weeks:

https://api-metrica.yandex.net/stat/v1/data/bytime?row_ids=[["Windows"],["Windows","Yandex.Browser"],["Windows","MSIE"]]&date1=2018-01-01&date2=2018-01-14&group=week&dimensions=ym:s:operatingSystemRootName,ym:s:browserName&ids=44147844&accuracy=medium&metrics=ym:s:visits

Number of views per day for the last 30 days (chart)

In the example, data is given for making a chart. The