Examples

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).

Sample values are given for the id and oauth_token parameters.

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

Presets

Sources — Summary report

preset=sources_summary

https://api-metrica.yandex.com/stat/v1/data?preset=sources_summary&id=2138128&oauth_token=05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037

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.com/stat/v1/data?preset=sources_summary&filters=ym:s:regionAreaName=='State of California'&id=2138128&oauth_token=05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037

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.com/stat/v1/data?preset=tech_platforms&dimensions=ym:s:browser&id=2138128&oauth_token=05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037

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.com/stat/v1/data?dimensions=ym:s:searchEngine&metrics=ym:s:visits,ym:s:users&filters=ym:s:trafficSource=='organic'&id=2138128&oauth_token=05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037

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.com/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=2138128&oauth_token=05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037

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=2138128&oauth_token=05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037

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.com/stat/v1/data?preset=sources_search_phrases&filters=ym:pv:URL=~'.*/id[0-9]+/.*'&id=2138128&oauth_token=05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037

Dimensions and metrics

Number of sessions

metrics=ym:s:hits

https://api-metrica.yandex.com/stat/v1/data?metrics=ym:s:hits&id=2138128&oauth_token=05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037

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.com/stat/v1/data?dimensions=ym:s:trafficSource&metrics=ym:s:users,ym:s:goal%3Cgoal_id%3EconversionRate&goal_id=4197733&id=2138128&oauth_token=05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037

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.com/stat/v1/data?metrics=ym:s:users,ym:s:goal4197733conversionRate,ym:s:goal4197739conversionRate&id=2138128&oauth_token=05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037

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).

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 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 the metrics parameter.

    ...?top_keys=3&...&dimensions=ym:s:regionCountry,ym:s:regionArea,ym:s:regionCity&group=day&ids=2138128&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.com/stat/v1/data/bytime?date1=2015-01-01&date2=2015-01-14&group=day&dimensions=ym:s:<attribution>TrafficSource&attribution=last&ids=2138128&metrics=ym:s:visits&oauth_token=05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037

Example with a value set for the top_keys parameter:

https://api-metrica.yandex.com/stat/v1/data/bytime?top_keys=3&date1=2015-01-01&date2=2015-01-14&group=day&dimensions=ym:s:<attribution>TrafficSource&attribution=last&ids=2138128&metrics=ym:s:visits&oauth_token=05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037

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

Traffic sources for the day:

https://api-metrica.yandex.com/stat/v1/data/bytime?row_ids=[["direct"],["organic","organic.yandex"],["social","social.ya"],["ad"]]&date1=2015-01-13&date2=2015-01-13&group=day&dimensions=ym:s:<attribution>TrafficSource,ym:s:<attribution>SourceEngine&attribution=last&ids=2138128&metrics=ym:s:visits&oauth_token=05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037

Traffic sources for two weeks, grouped by days:

https://api-metrica.yandex.com/stat/v1/data/bytime?row_ids=[["direct"],["organic","organic.yandex"],["social","social.ya"],["ad"]]&date1=2015-01-01&date2=2015-01-14&group=day&dimensions=ym:s:<attribution>TrafficSource,ym:s:<attribution>SourceEngine&attribution=last&ids=2138128&metrics=ym:s:visits&oauth_token=05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037

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

https://api-metrica.yandex.com/stat/v1/data/bytime?row_ids=[["direct"],["organic","organic.yandex"],["social","social.ya"],["ad"]]&date1=2015-01-01&date2=2015-01-14&group=week&dimensions=ym:s:<attribution>TrafficSource,ym:s:<attribution>SourceEngine&attribution=last&ids=2138128&metrics=ym:s:visits&oauth_token=05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037

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.com/stat/v1/data/bytime?date1=2015-01-01&date2=2015-01-14&group=day&dimensions=ym:s:regionCountry,ym:s:regionArea,ym:s:regionCity&ids=2138128&metrics=ym%3As%3Avisits&oauth_token=05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037

Example with a value set for the top_keys parameter:

https://api-metrica.yandex.com/stat/v1/data/bytime?top_keys=3&date1=2015-01-01&date2=2015-01-14&group=day&dimensions=ym:s:regionCountry,ym:s:regionArea,ym:s:regionCity&ids=2138128&metrics=ym%3As%3Avisits&oauth_token=05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037

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.com/stat/v1/data/bytime?row_ids=[["Russia"],["Russia","Saratovskaya%region"],["Russia","Saratovskaya%20region","Saratov"]]&date1=2015-01-01&date2=2015-01-14&group=week&dimensions=ym:s:regionCountryName,ym:s:regionAreaName,ym:s:regionCityName&ids=2138128&metrics=ym%3As%3Avisits&oauth_token=05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037

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

https://api-metrica.yandex.com/stat/v1/data/bytime?row_ids=[["Russia"],["Russia","Moscow%20и%Moscow region"],["Russia","Saint Peteresburg%20и%20Leningradskaya region"]]&date1=2015-01-01&date2=2015-01-14&group=week&dimensions=ym:s:regionCountryName,ym:s:regionAreaName,ym:s:regionCityName&ids=2138128&metrics=ym%3As%3Avisits&oauth_token=05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037

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.com/stat/v1/data/bytime?date1=2015-01-01&date2=2015-01-14&group=day&dimensions=ym:s:operatingSystemRootName,ym:s:browserName&ids=2138128&accuracy=medium&metrics=ym:s:visits&oauth_token=05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037

Example with a value set for the top_keys parameter:

https://api-metrica.yandex.com/stat/v1/data/bytime?top_keys=10&date1=2015-01-01&date2=2015-01-14&group=day&dimensions=ym:s:operatingSystemRootName,ym:s:browserName&ids=2138128&accuracy=medium&metrics=ym:s:visits&oauth_token=05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037

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.com/stat/v1/data/bytime?row_ids=[["Windows"],["Windows","Yandex.Browser"],["Windows","MSIE"]]&date1=2015-01-01&date2=2015-01-14&group=day&dimensions=ym:s:operatingSystemRootName,ym:s:browserName&ids=2138128&accuracy=medium&metrics=ym:s:visits&oauth_token=05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037

Data is grouped by calendar weeks:

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

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.com/stat/v1/data/bytime?metrics=ym:s:hits&date1=30daysAgo&date2=today&group=day&id=2138128&oauth_token=05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037

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.com/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=2138128&&oauth_token=05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037

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.com/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'&oauth_token=05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037

API requests. Drilldown

Technologies-Operating systems report in tree view

To generate the Operating systems report in tree view, you need to:

  1. Send a request for getting top-level data, using the tech_platforms preset (the Operating systems report).

    https://api-metrica.yandex.com/stat/v1/data/drilldown?preset=tech_platforms&id=2138128&oauth_token=05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037

  2. In the response, the expand parameter has the value true. 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 the id element of the dimension parameter has the value "100", the request will look like this: 

    https://api-metrica.yandex.com/stat/v1/data/drilldown?preset=tech_platforms&id=2138128&oauth_token=05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037&parent_id=["100"]

    In the response, the expand parameter has the value false. 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

}
...