Examples
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.
The examples provided below are helpful for solving common tasks.
These requests do not define the date1
and date2
parameters (the dates of the beginning and end of the report period). By default, the report period is 7 days (including the current day).
The /stat/v1/data
method is used for forming requests.
Presets
Sources — Summary report
preset=sources_summary
https://api-metrica.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
Technologies — 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-metrica.yandex.net/stat/v1/data?preset=tech_platforms&dimensions=ym:s:browser&id=44147844
where the parameter dimensions=ym:s:browser sets a dimension in the preset for grouping resulting data.
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-metrica.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-metrica.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 with depth greater than 5 pages
metrics=ym:s:visits
filters=ym:s:pageViews>5
https://api-metrica.yandex.ru/stat/v1/data?metrics=ym:s:visits&filters=ym:s:pageViews>5&id=44147844
Sources — Keywords 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
Dimensions and metrics
Number of sessions
metrics=ym:s:hits
https://api-metrica.yandex.net/stat/v1/data?metrics=ym:s:hits&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 the 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 will be grouped by traffic source.
https://api-metrica.yandex.net/stat/v1/data?dimensions=ym:s:trafficSource&metrics=ym:s:users,ym:s:goal%3Cgoal_id%3EconversionRate&goal_id=30606884&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-metrica.yandex.net/stat/v1/data?metrics=ym:s:users,ym:s:goal30606884conversionRate,ym:s:goal4197739conversionRate&id=44147844
API requests. 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. 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).
-
row_ids
— Array of arrays in JSON format. Each sub-array may contain dimension values (name
orid
) corresponding to the set of values defined in the request for thedimensions
parameter. The size of a sub-array indicates the dimensions that data will be 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 the sub-array contains dimension values of a single group (for example, Geography), the 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","Saratov 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 data set 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 themetrics
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-metrica.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-metrica.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-metrica.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-metrica.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-metrica.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-metrica.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-metrica.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 and 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%20и%Moscow region"],["Russia","Saint Peteresburg%20и%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-metrica.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-metrica.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 users of Windows, Yandex.Browser, and Internet Explorer. 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
The number of hits per day for the last 30 days
In the example, data will be given for making a chart. The /stat/v1/data/bytime
method is used for getting data.
metrics=ym:s:hits
date1=30daysAgo
date2=today
group=day
https://api-metrica.yandex.net/stat/v1/data/bytime?metrics=ym:s:hits&date1=30daysAgo&date2=today&group=day&id=44147844
API requests. Comparing segments
The /stat/v1/data/comparison
method is used for comparing data.
Comparison of two weeks
In this example, the number of users is compared. Data is grouped by traffic source.
metrics=ym:s:users
dimensions=ym:s:trafficSource
date1_left=2014-01-06
date2_left=2014-01-12
date1_right=2014-02-13
date2_right=2014-02-19
http://api-metrica.yandex.net/stat/v1/data/comparison?metrics=ym:s:users&dimensions=ym:s:trafficSource&date1_left=2014-01-06&date2_left=2014-01-12&date1_right=2014-02-13&date2_right=2014-02-19&id=44147844
Comparing sessions from mobile and non-mobile devices
In this example, the number of users and bounce rate are compared. Data is grouped by traffic source.
metrics=ym:s:users,ym:s:bounceRate
dimensions=ym:s:trafficSource
filters_left=ym:s:isMobile=='Yes'
filters_right=ym:s:isMobile=='No'
http://api-metrica.yandex.net/stat/v1/data/comparison?metrics=ym:s:users,ym:s:bounceRate&dimensions=ym:s:trafficSource&filters_left=ym:s:isMobile=='Yes'&filters_right=ym:s:isMobile=='No'
API requests. Drilldown
Technologies-Operating systems report in tree view
To generate the Operating systems report in tree view, you need to:
-
Send a request for getting top-level data, using the tech_platforms preset (the Operating systems report).
-
In the response, the
expand
parameter has the valuetrue
. This means that the node can be expanded to the next level. In our case, we can get data about the operating system version.... { "dimension": { "id": "100", "name": "Windows" }, "metrics": [ 21779, 52056, 17.7786, 2.39019, 182.664 ], "expand": true } ...
To do this, we will define the path to this level from the root in the
parent_id
parameter. Since theid
element of thedimension
parameter has the value"100"
, the request will look like this:In the response, the
expand
parameter has the valuefalse
. In other words, this node cannot be expanded further.... { "dimension": { "id": "33", "name": "Windows 7 or 2008 Server" }, "metrics": [ 14948, 36300, 7214, 42842, 048 ], "expand": false } ...