How to build a report
To build a report:
Request the statistics tree
To get the statistics tree, use the Statistics tree resource. As a result, you get the statistics levels and the fields for each level.
Sample request:
curl -i -X GET 'https://partner.yandex.ru/api/statistics2/tree.json?lang=ru&pretty=1' \
-H 'Authorization: OAuth 123qwe456a...'
Example of part of a response:
{
"data" : {
"tree" : [
{
"conflict_fields" : [],
"dimension_fields" : [
{
"id" : "date",
"title" : "Date",
"type" : "select",
"values" : [
[
"month",
"by month"
],
[
"week",
"by week"
],
[
"day",
"by day"
],
[
"year",
"by year"
]
]
},
{
"id" : "geo",
"title" : "Geography",
"type" : "select",
"values" : [
[
"country",
"by country"
],
[
"city",
"by city"
],
[
"area",
"by region"
]
]
}
],
"entity_fields" : [
{
"category" : 14,
"category_name" : "Product",
"id" : "block_level",
"index" : 4,
"label" : "Product's ad unit level",
"type" : "tree"
},
{
"category" : 14,
"category_name" : "Product",
"id" : "page_level",
"index" : 5,
"label" : "Product level",
"type" : "tree"
},
{
"category" : 12,
"category_name" : "Platform",
"id" : "page_id",
"index" : 11,
"label" : "Page ID",
"type" : "publicid"
},
{
"category" : 12,
"category_name" : "Platform",
"id" : "page_caption",
"index" : 12,
"label" : "Page name",
"type" : "text"
},
{
"category" : 10,
"category_name" : "Ad unit",
"id" : "complex_block_id",
"index" : 14,
"label" : "Ad unit ID",
"type" : "publicid"
},
{
"category" : 10,
"category_name" : "Ad unit",
"id" : "block_caption",
"index" : 15,
"label" : "Ad unit name",
"type" : "text"
},
{
"category" : 10,
"category_name" : "Ad unit",
"id" : "tag_id",
"index" : 16,
"label" : "Cross section ID",
"type" : "publicid"
},
{
"category" : 9,
"category_name" : "ADFOX",
"id" : "adfox_block",
"index" : 17,
"label" : "ADFOX unit",
"type" : "boolean"
},
{
"category" : 9,
"category_name" : "ADFOX",
"id" : "deal_id",
"index" : 18,
"label" : "Transaction ID",
"type" : "publicid"
},
{
"category" : 9,
"category_name" : "ADFOX",
"id" : "deal_caption",
"index" : 19,
"label" : "Transaction name",
"type" : "text"
},
{
"id" : "business_rule_id",
"index" : 20,
"label" : "Rule ID",
"type" : "publicid"
},
{
"id" : "business_rule_title",
"index" : 21,
"label" : "Rule name",
"type" : "text"
},
{
"category" : 7,
"category_name" : "Traffic",
"id" : "os",
"index" : 22,
"label" : "Operating system",
"type" : "publicid"
},
{
"category" : 7,
"category_name" : "Traffic",
"id" : "browser",
"index" : 23,
"label" : "Browser",
"type" : "publicid"
},
...
{
"category" : 6,
"category_name" : "Recommendation metrics",
"id" : "RecommendationWidgetCTR",
"index" : 58,
"title" : "Recommendation widget CTR",
"type" : "text"
}
],
"has_product" : "",
"has_raw_stat" : "",
"id" : "payment",
"title" : "Revenue"
}
]
},
"result" : "ok"
}
Choose fields from the statistics tree for building the report
Fields can be divided into three groups:
Indicator fields
These are fields that output some statistical information, such as ad impressions in blocks or ad requests in blocks.
Mandatory
The report must have at least one field from this group.
Where to find the list of fields
To get the list of available fields, see the fields structure for the Statistics tree resource.
Example:
{
...
"fields":
[
{
"category" : 1,
"category_name" : "Source data",
"id" : "shows",
"index" : 30,
"title" : "Impressions in ad units",
"type" : "text"
},
{
"category" : 1,
"category_name" : "Source data",
"id" : "hits",
"index" : 36,
"title" : "Ad requests in ad units",
"type" : "text"
}
]
...
}
Add to the report
Add fields as values of the field parameter for the Report on statistics level resource. Use the IDs of the chosen fields to add them.
Note
To add multiple fields to the report, specify the parameter multiple times:
field=shows&field=hits
Dimension fields
These are fields that can be used for grouping the rest of the data in the report.
There are two types of dimensions:
- Grouping by fields that do not belong to a particular product at the current level (for example, grouping by a period, currency or field from another product).
- Grouping by the other fields, such as IDs and names.
Mandatory
Dimension fields can be omitted from the report.
Where to find the list of fields
To get the list of available fields for grouping, see the dimension_fields and entity_fields structures for the Statistics tree resource.
Example:
...
"dimension_fields":
[
{
"id" : "date",
"title" : "Period",
"type" : "select",
"values" : [
[
"day",
"Grouping by days"
],
[
"week",
"Grouping by weeks"
],
[
"month",
"Grouping by months"
],
[
"year",
"Grouping by years"
]
]
},
{
"filter_values" : [
{
"id" : "3",
"key" : "id3",
"label" : "EUR"
},
{
"id" : "2",
"key" : "id2",
"label" : "RUB"
},
{
"id" : "1",
"key" : "id1",
"label" : "USD"
}
],
"id" : "currency_id",
"title" : "Currency",
"type" : "dictionary"
},
{
...
}
]
...
...
"entity_fields":
[
{
"id" : "page_id",
"label" : "Page ID",
"type" : "page_id"
},
{
"id" : "domain",
"label" : "Domain",
"type" : "text"
}
]
...
Add to the report
Add fields as values of the dimension_field and entity_field parameters for the Report on statistics level resource.
Note
To group by multiple fields, specify the field IDs as follows:
entity_field=domain&entity_field=page_id
Filter fields
Use these fields for filtering data. Filtering is applied during report generation.
SQL operators are applied to the fields, and the report is built based on the input conditions.
Mandatory
Filter fields can be omitted in a report.
Where to find the list of fields
To get the list of available fields for filtering data when generating the report, see the entity_filter_fields structure for the Statistics tree resource.
Example:
...
"entity_filter_fields":
{
"multistate" :
{
"label" : "Status",
"type" : "multistate",
"values" :
{
"need_approve" : "Needs approval",
"rejected" : "Rejected by moderator",
"stopped" : "Stopped",
"testing" : "Testing",
"working" : "Working"
}
},
"page_id" :
{
"label" : "Page ID",
"type" : "number"
}
...
Add to the report
Add fields as string values of the filter parameter for the Report on statistics level resource.
There are restrictions on using SQL operators. These restrictions are related to the data types that are used in fields:
= (equal to)
Used for scalar values.
Meaning
Generates a report for the specified field value.
This operator works with the following types of fields:
booleancontractnumberdictionarydomain_mirrorloginmultistatenumberpublicidstraight_numbertexttree
Example
You need to filter data by content sites that have the status “Working”:
filter=["multistate","=","working"]
where multistate is the field name and working is the field value.
Result
The report shows the requested data, filtered by working content sites.
<> (not equal to)
Used for scalar values.
Meaning
The specified field value is excluded from the report.
This operator works with the following types of fields:
dictionarydomain_mirrorloginmultistatenumberpublicidstraight_numbertexttree
Example
You need to filter data by content sites, excluding sites that have the status “Working”:
filter=["multistate","<>","working"]
where multistate is the field name and working is the field value.
Result
The report shows the requested data, filtered by sites' working status. Data for working sites will be excluded from the report.
IN (included in)
Used for arrays.
Meaning
Generates a report for the specified values of the field.
This operator works with the following types of fields:
contractnumberdomain_mirrorloginnumberpublicidstraight_numbertext
Example
You need to filter data by the IDs of content sites that are included in the specified list:
filter=["page_id","IN",["53100","53101"]]
where page_id is the field name, and 53100, 53101 are the field values.
Result
The report shows the requested data, filtered by the site IDs from the list.
> (greater than)
Used for scalar values.
Meaning
Generates a report for field values that are greater than the one specified.
This operator works with the following types of fields:
numberstraight_number
Example
You need to filter data by content sites with IDs that are greater than the specified value:
filter=["page_id",">","53100"]
where page_id is the field name and 53100 is the field value.
Result
The report shows the requested data, filtered by all the site IDs. The site IDs will be greater than the specified value.
< (less than)
Used for scalar values.
Meaning
Generates a report for field values that are less than the one specified.
This operator works with the following types of fields:
numberstraight_number
Example
You need to filter data by the IDs of content sites that are less than the specified value:
filter=["page_id","<","53100"]
where page_id is the field name and 53100 is the field value.
Result
The report shows the requested data, filtered by all the site IDs. The site IDs will be less than the specified value.
>= (greater than or equal to)
Used for scalar values.
Meaning
Creates a report on the field values that are greater than or equal to the specified value.
This operator works with the following types of fields:
numberstraight_number
Example
You need to filter data by content sites with IDs that are greater than or equal to the specified value:
filter=["page_id",">=","53100"]
where page_id is the field name and 53100 is the field value.
Result
The report shows the requested data, filtered by all the site IDs. The site IDs will be greater than or equal to the specified value.
<= (less than or equal to)
Used for scalar values.
Meaning
Creates a report on the field values that are less than or equal to the specified value.
This operator works with the following types of fields:
numberstraight_number
Example
You need to filter data by the IDs of content sites that are less than or equal to the specified value:
filter=["page_id","<=","53100"]
where page_id is the field name and 53100 is the field value.
Result
The report shows the requested data, filtered by all the site IDs. The site IDs will be less than or equal to the specified value.
NOT IN" operator (not included in)
Used for arrays.
Meaning
Creates a report on the field values that are not included in the specified list.
This operator works with the following types of fields:
domain_mirrorloginnumberpublicidstraight_numbertext
Example
You need to filter data by the IDs of content sites that are not included in the specified list:
filter=["page_id","NOT IN",["53100","53101"]]
where page_id is the field name, and 53100, 53101 are the field values.
Result
The report shows the requested data, filtered by all the site IDs. Data for the specified site IDs will be omitted from the report.
"LIKE" operator (included in the specified substring)
Used for scalar values.
Meaning
Creates a report on the field values that are included in the specified substring.
This operator works with the following types of fields:
domain_mirrorlogintext
Example
You need to filter data by the name of a site that is included in the specified value:
filter=["domain","LIKE","aliexpress"]
where domain is the field name, and aliexpress is the field value.
Result
The report shows the requested data, filtered by the names of sites that are included in the specified value.
NOT LIKE (not included in the specified substring)
Used for scalar values.
Meaning
Creates a report on the field values that are not included in the specified substring.
This operator works with the following types of fields:
domain_mirrorlogintext
Example
You need to filter data by a website name that is not included in the specified value:
filter=["domain","NOT LIKE","aliexpress"]
where domain is the field name, and aliexpress is the field value.
Result
The report shows the requested data, filtered by site names. Data for the specified site name will be omitted from the report.
"AND" operator (and)
Meaning
Used for combining filters.
Example
You need to filter data by the site name and by the content site ID. You have two filters:
filter=["domain","=","aliexpress"]
filter=["page_id","=","53100"]
You combine the two filters into one:
filter=["AND",[["domain","=","aliexpress"],["page_id","=","53100"]]]
Result
The report shows the requested data, filtered by the site name and by the content site ID.
"OR" (logical or)
Meaning
Used for performing at least one of the listed filters.
Example
You need to filter data by the site name or by the content site ID. You have two filters:
filter=["domain","=","aliexpress"]
filter=["page_id","=","53100"]
You combine the two filters into one:
filter=["OR",[["domain","=","aliexpress"],["page_id","=","53100"]]]
Result
The report shows the requested data, filtered by the site name or by the content site ID.
Form a request for building the report
Choose fields for building the report. As an example, we'll choose these fields:
- Indicator fields. We'll output data for the following indicators: ad requests in ad units (
hits), ads rendered in ad units (hits_render), and impressions in ad units (shows). - Dimension fields. We'll group data by the following fields: period by day (
period|day), and the ad platform ID (page_id). - Filter fields. We'll filter data by the ad platform with the ID 458472 (
"page_id","=","458472").
The request syntax is described in the Statistics report resource. We'll generate a report with the following parameters:
-
Choosing the response language
-
Setting the time interval to get the report for
period=thismonth -
Formatting the response for readability
pretty=1 -
Passing the indicator fields that we want to see in the report
field=shows&field=hits_render&field=hits -
Grouping data in the report by day
dimension_field=date|day -
Grouping data by ad platform
entity_field=page_id -
Filtering data by the site and getting a report that only contains data for the specified ad platform
filter=["page_id","=","458472"]'
Final request:
curl -g -X GET 'https://partner.yandex.ru/api/statistics2/get.json? \
lang=ru&pretty=1 \
&dimension_field=date|day \
&period=thismonth \
&entity_field=page_id \
&field=shows \
&field=hits_render \
&field=hits \
&filter=["page_id","=","458472"]' \
-H 'Authorization: OAuth 123qwe456a...'
Response fragment:
{
"data" : {
"currencies" : [
{
"code" : "USD",
"id" : "1"
},
{
"code" : "RUB",
"id" : "2"
},
{
"code" : "EUR",
"id" : "3"
}
],
"dimensions" : {
"date" : {
"index" : 1,
"title" : "Date",
"type" : "date"
},
"page_id" : {
"index" : 2,
"title" : "Page ID",
"type" : "page_id"
}
},
"is_last_page" : true,
"measures" : {
"hits" : {
"index" : 5,
"title" : "Ad requests in ad units",
"type" : "number",
"unit" : "count"
},
"hits_render" : {
"index" : 4,
"title" : "Ads rendered in ad units",
"type" : "number",
"unit" : "count"
},
"shows" : {
"index" : 3,
"title" : "Impressions in ad units",
"type" : "number",
"unit" : "count"
}
},
"periods" : [
[
"2020-12-01",
"2020-12-15"
]
],
"points" : [
{
"dimensions" : {
"date" : [
"2020-12-02"
],
"page_id" : 458472
},
"measures" : [
{
"hits" : 0,
"hits_render" : 0,
"shows" : 0
}
]
},
{
"dimensions" : {
"date" : [
"2020-12-14"
],
"page_id" : 458472
},
"measures" : [
{
"hits" : 0,
"hits_render" : 0,
"shows" : 0
}
]
},
{
"dimensions" : {
"date" : [
"2020-12-11"
],
"page_id" : 458472
},
"measures" : [
{
"hits" : 254,
"hits_render" : 254,
"shows" : 43
}
]
},
{
"dimensions" : {
"date" : [
"2020-12-15"
],
"page_id" : 458472
},
"measures" : [
{
"hits" : 0,
"hits_render" : 0,
"shows" : 0
}
]
},
{
"dimensions" : {
"date" : [
"2020-12-08"
],
"page_id" : 458472
},
"measures" : [
{
"hits" : 0,
"hits_render" : 0,
"shows" : 0
}
]
}
],
"report_title" : "Report for the period from 01.12.2020 to 15.12.2020",
"total_rows" : 5,
"totals" : {
"2" : [
{
"hits" : 254,
"hits_render" : 254,
"shows" : 43
}
]
}
},
"result" : "ok"
}