Documentation
Developer reference
Management API
Management of Yandex.Direct clients
Reporting API v1

Introduction

The Reports API allows you to get site traffic statistics and other data without using the Yandex.Metrica interface.

Dimensions and metrics are used for making API requests.

A dimension is an attribute of a session or hit that can be used for grouping data.

In API requests, dimensions are set in the dimensions parameter. If you need to list multiple dimensions, separate them with commas.

It is also possible to make a report without dimensions; in this case, the total result is calculated.

A metric is a numerical value that is based on an attribute of a hit or session.

In API requests, metrics are set in the metrics parameter. If you need to list multiple metrics, separate them with commas.

More about terminology

For a better understanding of the terms “dimension” and “metric”, consider the example of a Yandex.Metrica report on the operating system:

Operating systemPage depth
Windows4,2
IOS3,1
Linux1,6

Where

  • Operating system is an attribute of a session that is used for grouping report data (a dimension).
  • Page depth is a value calculated from numerical attributes of sessions (a metric) corresponding to the specified dimension.
Note. 

If you are familiar with SQL, you can think of dimensions as columns used for grouping, and metrics as the results returned by aggregate functions.

For example, the report shown above can be imagined as a query to a hypothetical table of sessions:

SELECT operatingSystem, avg(depth) from visits GROUP BY operatingSystem

Why is the term “dimension” used?

In the example, a session has a single attribute — the operating system. If we add another attribute (for example, the OS version):

Operating systemOS versionPage depth
Windows73,1
IOS63,1
WindowsXP1,1

we can show sessions in two dimensions:

  • the OS on one axis (dimension),
  • and the OS version on the other axis.

In this way, each attribute adds another dimension.

You can create the desired report structure by specifying metrics and dimensions in the API request.

For example, to get a report on page depth with data grouped by OS type and version, use this request:

https://beta.api-metrica.yandex.com/stat/v1/data.csv?id=2138128&metrics=ym:s:avgPageViews&dimensions=ym:s:operatingSystem&limit=5&oauth_token=05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037

Compatibility of dimensions and metrics

The API supports two types of dimensions and metrics:

  • Sessions, with the prefix ym:s:.
  • Pageviews (hits), with the prefix ym:pv:.

You cannot use different prefixes in the same request, or specify more than one category (see the section Categories and relationships).

Attention! 

You can specify a different prefix from the one set in the request and different categories when using the filters parameter for filtering resulting data by dimensions.

For example, this request generates a report on the number of sessions and unique users from search engines for the page specified in the request:

where

  • dimensions=ym:s:searchEngineName — Data grouped by the dimension ym:s:searchEngine (type of search engine).
  • metrics=ym:s:visits,ym:s:users — Number of sessions and users.
  • filters=ym:s:trafficSourceName=='Traffic from search engines' AND ym:pv:URL=@'help' — Data segmentation by the dimensions ym:s:trafficSourceName and ym:pv:URL.

Types of reports

Resulting data can be provided in the following formats:

All report levels and metrics are shown as a table.

To display data as a table, use the /stat/v1/data method.

Generating a single branch of a tree view report.

To create branches, use the /stat/v1/data/drilldown method.

Data is divided over units of time (such as days, weeks, and months). This format is convenient for building charts and tracking trends.

Use the /stat/v1/data/bytime method.

Comparison of segments specified in the same request. Data is shown as a table.

Use the /stat/v1/data/comparison method.

Comparison of segments specified in the same request. Data is shown in a tree-view report.

Use the /stat/v1/data/comparison/drilldown method.

Format of reports

The API returns responses in UTF-8 encoding. Responses are in JSON or CSV format.

The format is specified in the request after the URL:

GET https://beta.api-metrica.yandex.com/stat/v1/data.csv?<counter_id>&<metrics>&<dimensions>

Since JSON is the default format, it can be omitted:

GET https://beta.api-metrica.yandex.com/stat/v1/data?<counter_id>&<metrics>&<dimensions>

Data disclosure

Yandex.Metrica protects users' privacy and ensures that all collected information is depersonalized. For this reason, certain information such as social-demographic data (gender, age, and so on) has limited disclosure. Such data is provided only if there were more than 10 users in the sample.

For example, you want to know the percentage of males out of the total users for the day. At the time of the request, the site has been visited by 5 people (less than 10). In this case, the response will contain information about the total number of users for the day, but data will not be available for the number of males.