API request

Attention.

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.

Below are parameters which can be entered into an API request. The response is returned in UTF-8 in the form of a JSON file.

  1. Request syntax
  2. Response format

Request syntax

https://api-metrica.yandex.net/analytics/v3/data/ga
 ? [end-date=<string>]
 & [ids=<string>]
 & [metrics=<string>]
 & [start-date=<string>]
 & [callback=<string>]
 & [dimensions=<string>]
 & [filters=<string>]
 & [max-results=<int>]
 & [samplingLevel=<g_a_sample_accuracy>]
 & [sort=<string>]
 & [start-index=<integer>]
Query parameters
end-date

Date of end of reporting period.

You can specify the date in the format YYYY-MM-DD or use comparative time values: today, yesterday, NdaysAgo.

idsNumber of the counter whose data you want to obtain. You must specify the prefix ga: in front of the counter code.
metrics

Yandex.Metrica allows you to get data on session statistics and the activity of site users.

If in the request you did not specify a dimension, then the API returns a total value of metrics for the selected time interval without dividing it into any sort of group.

Please note the following features:

  • The composition of one query may not include more than 10 metrics.
  • The majority of metrics can be used in combination with one another, provided that no dimensions are selected.
  • Not all metrics can be combined with other metrics and dimensions as part of one query.
start-date

Start date of reporting period.

You can specify the date in the format YYYY-MM-DD or use comparative time values: today, yesterday, NdaysAgo.

Note.

Comparative time values are relative to your time zone, which is set according to your Yandex.Metrica account details.

callbackCallback. If specified, the result will be wrapped in a callback(...);
dimensions

Dimensions group data by criteria.

For example, use the parameter dimensions=ga:browser,ga:city to:

  1. Get data on the number of sessions.
  2. Group this data by browser, which the user used and the city in which the user was located during the session.

If data on a specified dimension was not received, it returns the value (not set).

Please note the following restrictions:

  • A single query cannot contain more than 7 dimensions.
  • A request cannot be made from only dimensions, but must contain at least one metric.
  • Not all dimensions can be combined with one another in one request.
filters

Filter allows you to limit the data returned in the result of a request.

Please note the following features:

  • Filtration by dimension is performed before the use of dimensions. Thus, the resulting metric represents the total value only for data satisfying the condition of the dimension.
  • Filtration by metric is performed before the use of metrics.
  • You can use for filtration those dimensions and metrics which were not entered as part of your request.
max-results

Maximum number of rows which will be shown in report.

Use this parameter in conjunction with the parameter start-index, to get a subset of elements, the first of which corresponds to the value specified in the parameter start-index.

The default setting of the value is 100. The maximum number of rows is 10000.

The number of rows in a report can be less than what you specified, if for the selected segment there are not enough entries. For example, for the dimension ga:country you can get no more than 300 entries.

samplingLevelUse this parameter for specifying the level of sampling (number of visits used in the calculation of the overall value).

Default value: DEFAULT

Allowed values:

  • HIGHER_PRECISION — shows the most precise value possible using the largest possible data set. In this mode more time may be required to process your data request.
  • FASTER — shows quick results based on a limited data set.
  • DEFAULT — shows results when selecting for speed and accuracy of data.
sort

A list of metrics and dimensions may be used for the sorting of collected data.

By default the sorting is done in ascending order. To sort by descending order, specify the symbol “-” in the request in front of the list of metrics and dimensions.

As the value of the parameter sort you can use only those values of dimensions and metrics for which data has been obtained.

start-index

This parameter by default has the value 1.

Use this parameter in combination with the parameter max-results for those instances when the number of elements of a list totalResults exceeds, for example, 10000, and you need to get 10001 values.

Note.

The parameter start-index is measured from 1, not from 0.

Default value: 1

Response format


{
    "kind" :  < string > ,
    "id" :  < string > ,
    "selfLink" :  < string > ,
    "containsSampledData" :  < boolean > ,
    "sampleSize" :  < string > ,
    "sampleSpace" :  < string > ,
    "query" : {
        "start-date" :  < string > ,
        "end-date" :  < string > ,
        "dimensions" : [  < string > , ... ],
        "metrics" : [  < string > , ... ],
        "sort" : [  < string > , ... ],
        "filters" :  < string > ,
        "start-index" :  < integer > ,
        "max-results" :  < integer > 
    },
    "itemsPerPage" :  < integer > ,
    "totalResults" :  < integer > ,
    "columnHeaders" : [ {
        "name" :  < string > ,
        "columnType" :  < string > ,
        "dataType" :  < string > 
    }, ... ],
    "totalsForAllResults" : {
        "key_1" :  < string > ,
        "key_2" : ...
    },
    "rows" : [ [  < string > , ... ], ... ]
}
Parameters Description
kind Displays resource type. Parameter always has the value analytics#gaData.
id Displays request ID.
containsSampledData Determines whether to use sampling during data collection. If used, takes the value true.
sampleSize Displays the size of requesting data, used to generate request results with sampling.
sampleSpace Displays the overall volume of data, available for the implementation of requesting data while sampling.
query Includes all of the parameters transferred in the request.
itemsPerPage Displays the amount of data which is displayed on the page. By default the maximum amount equals 1000.
totalResults Displays overall number of results.
columnHeaders Displays column headers, containing a list of dimensions and metrics. The total number of these columns is the total number of dimensions and metrics used in the request.
totalsForAllResults Displays overall values of requested metrics, presented in the form of pairs: the metric name and its values.
rows Displays a list of rows, each of which contains dimensions and metrics. The order of the data corresponds to the order specified in the query.
query
start-date Displays start date of reporting period.
end-date Displays end date of reporting period.
dimensions Displays a list of dimensions of a request.
metrics Displays a list of request metrics.
sort Displays a list of metrics and dimensions, for which data is sorted.
filters Displays list of filters by metrics and dimensions.
start-index Displays index of first record from request.
max-results Displays the maximum number of rows on a page.
columnHeaders
name Contains name of dimension or metric
columnType Contains attribute type. Accepts values: dimension or metric.
dataType Contains type of data. This parameter always takes the value STRING for columns with dimensions.