Introduction
The Reports API allows you to get site traffic statistics and other data without using the Yandex Metrica interface.
API requests are created using dimensions and metrics.
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.
You can also make a report without dimensions. In this case, the cumulative 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
Let's explore the concepts of "dimension" and "metric" in more detail using the example of a Yandex Metrica operating system report:
|
Operating system |
Page depth |
|
Windows |
4.2 |
|
iOS |
3.1 |
|
Linux |
1.6 |
Where
Operating systemis an attribute of a session that is used for grouping report data (a dimension).Page depthis 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 data, 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
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://api-metrica.yandex.net/stat/v1/data.csv?id=44147844&metrics=ym:s:avgPageViews&dimensions=ym:s:operatingSystem&limit=5
Compatibility of dimensions and metrics
The API supports two types of groupings and metrics:
- Sessions — with the prefix
ym:s:. - Hits — have the
ym:pv:prefix.
You can't use different prefixes in the same request or specify more than one category (see Segmentation. Categories and relationships.
Alert
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:
https://api-metrica.yandex.net/stat/v1/data?dimensions=ym:s:searchEngineName&metrics=ym:s:visits,ym:s:users&filters=ym:s:trafficSourceName=='Переходы из поисковых систем' AND ym:pv:URL=@'help'&id=44147844
where
dimensions=ym:s:searchEngineName: Data grouped by the parameterym: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 dimensionsym:s:trafficSourceNameandym: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 a branch, 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 creating charts and tracking trends.
Use the /stat/v1/data/bytime method.
Comparison of segments specified in the same request. Data is presented in a table.
Use the /stat/v1/data/comparison method.
Comparison of segments specified in the same request. Data is presented 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://api-metrica.yandex.net/stat/v1/data.**csv**?<counter_id>&<metrics>&<dimensions>
Since JSON is the default format, it can be omitted:
GET https://api-metrica.yandex.net/stat/v1/data?<counter_id>&<metrics>&<dimensions>
Data disclosure
Yandex Metrica protects users' privacy and ensures that all collected information is depersonalized. Certain information, such as demographic data (gender, age, and so on), has limited disclosure. This data is provided only if there are more than 10 users in the sample.
Learn more about statistics depersonalization.
For example, suppose you want to find out what percentage of users who visited your site during one day were male. 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 you won't be able to obtain data about the number of male visitors.
How do I determine if an API response contains data with limited disclosure?
The API response includes a contains_sensitive_data parameter. If its value is true, the provided data has limited disclosure.