Getting data by time
Used to get data broken down by time period (for example, by day, week, or month). Use this request type to create charts and track statistics over time.
See an example with this request.
Request syntax
https://api-metrika.yandex.net/stat/v1/data/bytime
? ids=<int,int,...>
& metrics=<string>
& [accuracy=<string>]
& [annotation_groups=<list>]
& [callback=<string>]
& [date1=<string>]
& [date2=<string>]
& [dimensions=<string>]
& [direct_client_logins=<string,_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>]
ids * | Comma-separated list of counter IDs. Used instead of the id parameter. |
metrics * | Comma-separated list of metrics. Limit: 20 metrics per request. |
accuracy | Sample size for the report. Use it to control the sampling rate (the number of sessions used for calculating results). Default value: medium |
annotation_groups | Groups 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 tag. Acceptable values:
|
callback | Callback function that processes the API response. |
date1 | Start date of the sample period in YYYY-MM-DD format. You can also use the values: Default value: |
date2 | End date of the sample period in YYYY-MM-DD format. You can also use the values: Default value: |
dimensions | Comma-separated list of dimensions. Limit: 10 dimensions per request. |
direct_client_logins | Comma-separated usernames of Yandex Direct clients. They can be used for generating the Yandex Direct — costs report. |
filters | Limits: up to 10 unique dimensions and metrics; up to 20 separate filters; up to 10,000 characters per filter row; and up to 100 values per filtering condition. |
group | Grouping data by time. Default value: week Acceptable values:
|
id | Tag ID. Obsolete. Use ids . |
include_annotations | Used to include comments in the response. Disabled by default. Default value: false |
include_undefined | Outputs rows that don't have defined dimension values. This only affects the first dimension. Disabled by default. |
lang | Language. |
preset | Report presets. |
pretty | Specifies the formatting for results. To use formatting, set the value to true .Default value: |
proposed_accuracy | If the parameter is set to true, the API has the right to automatically increase the "accuracy" parameter to the recommended value. This can help you obtain meaningful results when a request is sent to a small table with very small sampling. |
row_ids | Row selection for creating charts. Contains listing of key lists. |
timezone | Time zone in ±hh:mm format within the range of [-23:59; +23:59] (the plus sign should be denoted as |
top_keys | Sets the number of rows of results if the Default value: 7 |
ids * | Comma-separated list of counter IDs. Used instead of the id parameter. |
metrics * | Comma-separated list of metrics. Limit: 20 metrics per request. |
accuracy | Sample size for the report. Use it to control the sampling rate (the number of sessions used for calculating results). Default value: medium |
annotation_groups | Groups 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 tag. Acceptable values:
|
callback | Callback function that processes the API response. |
date1 | Start date of the sample period in YYYY-MM-DD format. You can also use the values: Default value: |
date2 | End date of the sample period in YYYY-MM-DD format. You can also use the values: Default value: |
dimensions | Comma-separated list of dimensions. Limit: 10 dimensions per request. |
direct_client_logins | Comma-separated usernames of Yandex Direct clients. They can be used for generating the Yandex Direct — costs report. |
filters | Limits: up to 10 unique dimensions and metrics; up to 20 separate filters; up to 10,000 characters per filter row; and up to 100 values per filtering condition. |
group | Grouping data by time. Default value: week Acceptable values:
|
id | Tag ID. Obsolete. Use ids . |
include_annotations | Used to include comments in the response. Disabled by default. Default value: false |
include_undefined | Outputs rows that don't have defined dimension values. This only affects the first dimension. Disabled by default. |
lang | Language. |
preset | Report presets. |
pretty | Specifies the formatting for results. To use formatting, set the value to true .Default value: |
proposed_accuracy | If the parameter is set to true, the API has the right to automatically increase the "accuracy" parameter to the recommended value. This can help you obtain meaningful results when a request is sent to a small table with very small sampling. |
row_ids | Row selection for creating charts. Contains listing of key lists. |
timezone | Time zone in ±hh:mm format within the range of [-23:59; +23:59] (the plus sign should be denoted as |
top_keys | Sets the number of rows of results if the Default value: 7 |
* Required
Sample request
https://api-metrika.yandex.net/stat/v1/data/bytime?ids=44147844%2C2215573&metrics=ym%3As%3Apageviews
Response format
{
"total_rows" : < long > ,
"total_rows_rounded" : < boolean > ,
"sampled" : < boolean > ,
"contains_sensitive_data" : < boolean > ,
"sample_share" : < double > ,
"sample_size" : < long > ,
"sample_space" : < long > ,
"data_lag" : < int > ,
"query" : {
"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" : [ [ {
"id" : < int > ,
"date" : < local_date > ,
"time" : < local_time > ,
"title" : < string > ,
"message" : < string > ,
"group" : < chart_annotation_group >
}, ... ], ... ]
}
Parameters | Description |
---|---|
total_rows | The total number of rows in the response for the entire dataset (after filtering). |
total_rows_rounded | Indicates that the total number of rows was rounded. |
sampled | Sampling flag. Indicates whether sampling was applied. Possible values: true , false . |
contains_sensitive_data | Indicates whether sensitive data can be omitted from the response. This includes data calculated by Yandex algorithms: demographic data (gender, age, and other), login page addresses, search phrases, and robot information. If the value is Possible values: |
sample_share | Percentage of data used for the calculation. Available values range from 0 to 1. |
sample_size | Number of rows in the requested data. |
sample_space | Number of data rows. |
data_lag | Delay in updating data, in seconds. |
query | Original request. Contains the request parameters, including detailed parameters from the template and parameters for attribute parametrization. |
data | Response rows. An array in which each item is a single row of the result. |
totals | Total results for metrics across the entire dataset (with filtration). |
annotations | Comments. |
query | |
timezone | Time zone of the sample period in ±hh:mm format. |
preset | Report preset. |
dimensions | Array of dimensions. |
metrics | Array of metrics. |
sort | Array of sortings. |
date1 | Start date of the sample period in YYYY-MM-DD format. |
date2 | End date of the sample period in YYYY-MM-DD format. |
filters | Segmentation filter. |
data | |
dimensions | Array of dimension values for this row. Each dimension value is an object. It must have the name field, which is a text value. But it can also have additional fields, such as id . |
metrics | Array of arrays of metric values for this row. The outer array lists metrics, and the inner arrays list values of a specific metric for each time group. |
annotations | |
id | Comment ID. |
date | Date. |
time | Time. |
title | Title. |
message | Description. |
group | The group. Possible values:
|
Parameters | Description |
---|---|
total_rows | The total number of rows in the response for the entire dataset (after filtering). |
total_rows_rounded | Indicates that the total number of rows was rounded. |
sampled | Sampling flag. Indicates whether sampling was applied. Possible values: true , false . |
contains_sensitive_data | Indicates whether sensitive data can be omitted from the response. This includes data calculated by Yandex algorithms: demographic data (gender, age, and other), login page addresses, search phrases, and robot information. If the value is Possible values: |
sample_share | Percentage of data used for the calculation. Available values range from 0 to 1. |
sample_size | Number of rows in the requested data. |
sample_space | Number of data rows. |
data_lag | Delay in updating data, in seconds. |
query | Original request. Contains the request parameters, including detailed parameters from the template and parameters for attribute parametrization. |
data | Response rows. An array in which each item is a single row of the result. |
totals | Total results for metrics across the entire dataset (with filtration). |
annotations | Comments. |
query | |
timezone | Time zone of the sample period in ±hh:mm format. |
preset | Report preset. |
dimensions | Array of dimensions. |
metrics | Array of metrics. |
sort | Array of sortings. |
date1 | Start date of the sample period in YYYY-MM-DD format. |
date2 | End date of the sample period in YYYY-MM-DD format. |
filters | Segmentation filter. |
data | |
dimensions | Array of dimension values for this row. Each dimension value is an object. It must have the name field, which is a text value. But it can also have additional fields, such as id . |
metrics | Array of arrays of metric values for this row. The outer array lists metrics, and the inner arrays list values of a specific metric for each time group. |
annotations | |
id | Comment ID. |
date | Date. |
time | Time. |
title | Title. |
message | Description. |
group | The group. Possible values:
|