Receiving data by time

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.

Provides data broken down by time (for example by day, week, month). Use this type of request for making graphs or tracking dynamics.

See how uses this request in the example.

  1. Request syntax
  2. Response format

Request syntax

https://api-metrica.yandex.net/stat/v1/data/bytime
 ? [direct_client_logins=<string,_string,...>]
 & [ids=<int,int,...>]
 & [metrics=<string>]
 & [accuracy=<string>]
 & [annotation_groups=<list>]
 & [callback=<string>]
 & [date1=<string>]
 & [date2=<string>]
 & [dimensions=<string>]
 & [filters=<string>]
 & [group=<group_type>]
 & [id=<integer>]
 & [include_annotations=<boolean>]
 & [include_undefined=<boolean>]
 & [lang=<string>]
 & [preset=<string>]
 & [pretty=<boolean>]
 & [proposed_accuracy=<boolean>]
 & [row_ids=<list>]
 & [timezone=<string>]
 & [top_keys=<integer>]
Query parameters
direct_client_loginsComma-separated logins of Yandex.Direct clients. Used for generating the Yandex.Direct - costs report.
idsCounter IDs, separated by commas. Used instead of id parameter.
metrics

List of metrics, separated by commas.

Limit: 20 metrics in request.

accuracyAccuracy of the result. Use it to control the sampling rate (the number of sessions used for calculating results).

Default value: medium

annotation_groupsGroups of comma-separated comments to return in the response. Transmitted if the include_annotations parameter is set to true. If the annotation_groups parameter is omitted, the response returns all the comments that were created for this counter.
callbackCallback function which returns an API response.
date1

Start date of requesting data period in the format YYYY-MM-DD. Also use values: today, yesterday, ndaysAgo.

Default value: 6daysAgo

date2

End date of requesting data period in the format YYYY-MM-DD. Also uses values: today, yesterday, ndaysAgo.

Default value: today

dimensions

List of dimensions, separated by commas.

Limit: 10 dimensions in request.

filters

Segmentation filter.

Limit: number of unique dimensions and metrics — up to 10, number of separate filters — up to 20, row length in filter — up to 10 000 characters.

groupGroup data by time.

Default value: week

Allowed values:

  • all — time interval is not broken down.
  • hours — time interval is broken down into intervals of several hours.
  • auto — interval is set taking into account the selected reporting period and amount of data required for this period.
  • week — time interval is broken down into weeks.
  • month — time interval is broken down into months.
  • hour — time interval is broken down into one-hour intervals.
  • year — time interval is broken down into years.
  • minutes — time interval is broken down into intervals of several minutes.
  • day — time interval is broken down into days.
  • dekaminute — time interval is broken down into 10-minute intervals.
  • quarter — time interval is broken down into quarters.
  • minute — time interval is broken down into minute intervals.
idCounter ID. Outdated, use ids.
include_annotationsWhether to include comments in the response. Disabled by default.

Default value: false

include_undefinedEnabled in response row, for which values of dimensions are not defined. This only affects the first dimension. Disabled by default.
langLanguage.
presetPreset.
prettySpecifies the formatting of results. To use formatting, enter the value true.

Default value: false

proposed_accuracyIf parameter is set to true, the API has the right to automatically increase accuracy to the recommended value. This parameter can help you obtain meaningful results when a request is sent to a small table with very small sampling.
row_idsRow selection for construction of graphs. Contains listing of key lists.
timezone

Time zone in ±hh:mm format within range of [-23:59; +23:59] (the plus sign should be denoted as %2B); this time zone is used to calculate the query selection period as well as the date- and time-specific dimensions. By default, the counter's time zone is used.

top_keys

Sets the number of rows of results if the row_ids parameter is not set.

Default value: 7

Response format


{
    "total_rows" :  < long > ,
    "total_rows_rounded" :  < boolean > ,
    "sampled" :  < boolean > ,
    "sample_share" :  < double > ,
    "sample_size" :  < long > ,
    "sample_space" :  < long > ,
    "data_lag" :  < int > ,
    "query" : {
        "ids" : [  < int > , ... ],
        "timezone" :  < string > ,
        "preset" :  < string > ,
        "dimensions" : [  < string > , ... ],
        "metrics" : [  < string > , ... ],
        "sort" : [  < string > , ... ],
        "date1" :  < string > ,
        "date2" :  < string > ,
        "filters" :  < string > 
    },
    "data" : [ {
        "dimensions" : [ {
            "key_1" :  < string > ,
            "key_2" : ...
        }, ... ],
        "metrics" : [ [  < double > , ... ], ... ]
    }, ... ],
    "totals" : [ [  < double > , ... ], ... ],
    "annotations" : [ [  < _metrika_chart_annotation > , ... ], ... ]
}
ParametersDescription
total_rowsThe total number of rows in the response for the entire data set (after filtering).
total_rows_roundedSign that the total number of rows was rounded.
sampledIndication of sampling. Shows whether sampling was applied. Possible values: true, false.
sample_shareShare of processed data, for which a calculation was carried out. Available values range from 0 to 1.
sample_sizeNumber of rows in requesting data.
sample_spaceNumber of rows of data.
data_lagDelay in updating data, in seconds.
queryOriginal request. Contains request parameters, including detailed parameters from template and parameters for parametrization attributes scheme.
dataRows of response. Is an array, each element of which is one row of a result.
totalsTotal results for metrics across all data (taking into account filter).
annotationsComments.
query
idsIDs of counters.
timezoneTime zone of the selection period in ±hh:mm format.
presetPreset of report.
dimensionsArray of dimensions.
metricsArray of metrics.
sortArray of sortings.
date1Start date of requesting data period in the format YYYY-MM-DD.
date2End date of requesting data period in the format YYYY-MM-DD.
filtersSegmentation filter.
data
dimensionsArray of dimension values for this row. Every dimension value represents an object, which contains the field name, a text value. Additional fields may be present, for example ID id.
metricsArray of arrays of metric values for this row. The outer array lists metrics, whereas the inner arrays list concrete metric values for every time group.