API request

Below are parameters you can enter in an API request. The response is sent as a UTF-8–encoded JSON file.

  1. Request syntax
  2. Response format

Request syntax

https://api-metrika.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>]
end-date

End date of the reporting period.

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

idsID of the tag whose data you want to obtain. You must specify the prefix ga: in front of the tag ID.
metrics

Yandex Metrica allows getting data on session statistics and user activity on the site.

If you don't specify a dimension in the request, then the API returns a total metric value for the selected time interval without breaking it up into any groups.

Please note the following features:

  • A single request can include no 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 within a single request.
start-date

Start date of the reporting period.

You can specify the date in YYYY-MM-DD format 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 certain 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 the user's browser and the city during the session.

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

Please note the following limitations:

  • A single request can include no more than 7 dimensions.
  • A request cannot be made entirely from dimensions, but must contain at least one metric.
  • Not all dimensions can be combined with each other as part of one request.
filters

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

Please note the following features:

  • Filtration by a dimension is performed before using dimensions. The resulting metric thus represents the total value only for data satisfying the condition of the dimension.
  • Filtration by a metric is performed after the metric is applied.
  • You can filter using the dimensions and metrics which were not entered as part of your request.
max-results

Maximum number of rows which will be shown in report.

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

The default setting of the value is 100. The maximum number of rows is 10,000.

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

samplingLevelUse this parameter for indicating the level of sampling (number of sessions used in the calculation of the total value).

Default value: DEFAULT

Acceptable values:

  • HIGHER_PRECISION: Shows the most precise value possible using the largest possible sample. In this mode more time may be required to process your data request.
  • FASTER: Shows quick results based on a limited sample.
  • DEFAULT: Shows results based on a sample that equally balances between speed and data accuracy.
sort

A list of metrics and dimensions can be used for sorting the 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.

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

start-index

By default, this parameter has the value 1.

Use this parameter in combination with the max-results parameter when the number of elements in the totalResults list exceeds, for example, 10,000, while you need to get 10,001 values.

Note.

The index of the start-index parameter is 1-based, not 0-based.

Default value: 1

end-date

End date of the reporting period.

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

idsID of the tag whose data you want to obtain. You must specify the prefix ga: in front of the tag ID.
metrics

Yandex Metrica allows getting data on session statistics and user activity on the site.

If you don't specify a dimension in the request, then the API returns a total metric value for the selected time interval without breaking it up into any groups.

Please note the following features:

  • A single request can include no 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 within a single request.
start-date

Start date of the reporting period.

You can specify the date in YYYY-MM-DD format 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 certain 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 the user's browser and the city during the session.

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

Please note the following limitations:

  • A single request can include no more than 7 dimensions.
  • A request cannot be made entirely from dimensions, but must contain at least one metric.
  • Not all dimensions can be combined with each other as part of one request.
filters

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

Please note the following features:

  • Filtration by a dimension is performed before using dimensions. The resulting metric thus represents the total value only for data satisfying the condition of the dimension.
  • Filtration by a metric is performed after the metric is applied.
  • You can filter using the dimensions and metrics which were not entered as part of your request.
max-results

Maximum number of rows which will be shown in report.

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

The default setting of the value is 100. The maximum number of rows is 10,000.

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

samplingLevelUse this parameter for indicating the level of sampling (number of sessions used in the calculation of the total value).

Default value: DEFAULT

Acceptable values:

  • HIGHER_PRECISION: Shows the most precise value possible using the largest possible sample. In this mode more time may be required to process your data request.
  • FASTER: Shows quick results based on a limited sample.
  • DEFAULT: Shows results based on a sample that equally balances between speed and data accuracy.
sort

A list of metrics and dimensions can be used for sorting the 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.

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

start-index

By default, this parameter has the value 1.

Use this parameter in combination with the max-results parameter when the number of elements in the totalResults list exceeds, for example, 10,000, while you need to get 10,001 values.

Note.

The index of the start-index parameter is 1-based, not 0-based.

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 takes the value analytics#gaData.
id Displays request ID.
containsSampledData Determines whether to use sampling during data collection. If sampling was used, takes the value true.
sampleSize Displays the size of the sample used to gets the results of a request with sampling.
sampleSpace Displays the overall volume of data available for the implementation of the sample when using sampling.
query Includes all of the parameters transmitted in the request.
itemsPerPage Displays the amount of data displayed on the page. By default, the maximum amount is 1000.
totalResults Displays the total number of results.
columnHeaders Displays column headers containing a list of dimensions and metrics. The total number of these columns is the total amount of dimensions and metrics used in the request.
totalsForAllResults Displays the resulting values of requested metrics presented as pairs: the metric name and its value.
rows Displays a list of rows, each of which contains dimensions and metrics. The order of data corresponds to the order specified in the request.
query
start-date Displays start date of the reporting period.
end-date Displays end date of the reporting period.
dimensions Displays a list of dimensions in the request.
metrics Displays a list of metrics in the request.
sort Displays a list of metrics and dimensions used to sort data.
filters Displays a list of filters by metrics and dimensions.
start-index Displays the index of the first entry in the request.
max-results Displays the maximum number of rows on the page.
columnHeaders
name Contains the name of a dimension or metric
columnType Contains the attribute type Accepts the values dimension or metric.
dataType Contains the data type. This parameter always takes the value STRING for columns with dimensions.
Parameters Description
kind Displays resource type. Parameter always takes the value analytics#gaData.
id Displays request ID.
containsSampledData Determines whether to use sampling during data collection. If sampling was used, takes the value true.
sampleSize Displays the size of the sample used to gets the results of a request with sampling.
sampleSpace Displays the overall volume of data available for the implementation of the sample when using sampling.
query Includes all of the parameters transmitted in the request.
itemsPerPage Displays the amount of data displayed on the page. By default, the maximum amount is 1000.
totalResults Displays the total number of results.
columnHeaders Displays column headers containing a list of dimensions and metrics. The total number of these columns is the total amount of dimensions and metrics used in the request.
totalsForAllResults Displays the resulting values of requested metrics presented as pairs: the metric name and its value.
rows Displays a list of rows, each of which contains dimensions and metrics. The order of data corresponds to the order specified in the request.
query
start-date Displays start date of the reporting period.
end-date Displays end date of the reporting period.
dimensions Displays a list of dimensions in the request.
metrics Displays a list of metrics in the request.
sort Displays a list of metrics and dimensions used to sort data.
filters Displays a list of filters by metrics and dimensions.
start-index Displays the index of the first entry in the request.
max-results Displays the maximum number of rows on the page.
columnHeaders
name Contains the name of a dimension or metric
columnType Contains the attribute type Accepts the values dimension or metric.
dataType Contains the data type. This parameter always takes the value STRING for columns with dimensions.