How to create a report

To create a report:

Request the statistics tree

To get the statistics tree, use the Statistics tree resource. The response will contain the statistics levels and fields for each level.

Request example:

curl -i -X GET 'https://partner2.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 block level",
                  "type" : "tree"
               },
               {
                  "category" : 14,
                  "category_name" : "Product",
                  "id" : "page_level",
                  "index" : 5,
                  "label" : "Product level",
                  "type" : "tree"
               },
               {
                  "category" : 12,
                  "category_name" : "Site",
                  "id" : "page_id",
                  "index" : 11,
                  "label" : "Page ID",
                  "type" : "publicid"
               },
               {
                  "category" : 12,
                  "category_name" : "Site",
                  "id" : "page_caption",
                  "index" : 12,
                  "label" : "Page name",
                  "type" : "text"
               },
               {
                  "category" : 10,
                  "category_name" : "Block",
                  "id" : "complex_block_id",
                  "index" : 14,
                  "label" : "Block ID",
                  "type" : "publicid"
               },
               {
                  "category" : 10,
                  "category_name" : "Block",
                  "id" : "block_caption",
                  "index" : 15,
                  "label" : "Block name",
                  "type" : "text"
               },
               {
                  "category" : 10,
                  "category_name" : "Block",
                  "id" : "tag_id",
                  "index" : 16,
                  "label" : "Cross-section ID",
                  "type" : "publicid"
               },
               {
                  "category" : 9,
                  "category_name" : "ADFOX",
                  "id" : "adfox_block",
                  "index" : 17,
                  "label" : "ADFOX block",
                  "type" : "boolean"
               },
               {
                  "category" : 9,
                  "category_name" : "ADFOX",
                  "id" : "deal_id",
                  "index" : 18,
                  "label" : "Deal ID",
                  "type" : "publicid"
               },
               {
                  "category" : 9,
                  "category_name" : "ADFOX",
                  "id" : "deal_caption",
                  "index" : 19,
                  "label" : "Deal 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" : "Indicators for recommendations",
                  "id" : "RecommendationWidgetCTR",
                  "index" : 58,
                  "title" : "CTR of recommendation widget",
                  "type" : "text"
               }
            ],
            "has_product" : "",
            "has_raw_stat" : "",
            "id" : "payment",
            "title" : "Rewards"
         }
      ]
   },
   "result" : "ok"
}

Use the statistics tree to choose the fields for building the report

There are three categories of fields:

Indicator fields

These are fields that display statistical information, such as ad impressions in blocks or ad requests from blocks.

Required (Yes/No)

The report must contain at least one field from this group.

Where to find a list of fields

The list of acceptable fields is output in the fields structure from the Statistics tree resource. Example:

{
  ...
  "fields":
  [
    {
      "category" : 1,
      "category_name" : "Source data",
      "id" : "shows",
      "index" : 30,
      "title" : "Ad impressions in blocks",
      "type" : "text"
    },
    {
      "category" : 1,
      "category_name" : "Source data",
      "id" : "hits",
      "index" : 36,
      "title" : "Ad requests in blocks",
      "type" : "text"
    }
  ]
  ...
}
How to add data to the report

Fields are added as values of the field parameter from the Statistics report resource. To add fields, use the field IDs.

Note

To add multiple fields to the report, specify the parameter multiple times:

field=shows&field=hits

Grouping fields

These are fields you can use to group other data in the report.

There are two types of groupings:

  • Grouping by fields that don't belong to a specific product at the current level (like grouping by period, currency, or field from another product).
  • Grouping by other fields (like IDs or names).
Required (Yes/No)

The grouping fields may be omitted in the report.

Where to find a list of fields

The list of acceptable grouping fields is output in the structures dimension_fields and entity_fields from the Statistics tree resource.

Example:

...
  "dimension_fields":
  [
    {
      "id" : "date",
      "title" : "Period",
      "type" : "select",
      "values" : [
        [
          "day",
          "Group by day"
        ],
        [
          "week",
          "Group by week"
        ],
        [
          "month",
          "Group by month"
        ],
        [
          "year",
          "Group by year"
        ]
      ]
    }, 
    {
      "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"
    }
  ]
...
How to add data to the report

The fields are added as values of the dimension_field and entity_field parameters from the Statistics report resource.

Note

To group the data by multiple fields, specify the field IDs as follows:

entity_field=domain&entity_field=page_id

Filtering fields

These fields are used to filter the data. Filtering occurs when creating the report.

SQL statements are applied to the fields and a report is generated based on the input criteria.

Required (Yes/No)

Filtering fields may be omitted in the report.

Where to find a list of fields

The list of acceptable fields for filtering data when creating the report is output in the structure entity_filter_fields from the Statistics tree resource. Example:

...
  "entity_filter_fields":
  {
    "multistate" : 
    {
      "label" : "Status",
      "type" : "multistate",
      "values" : 
      {
        "need_approve" : "Needs approval",
        "rejected" : "Rejected by the moderator",
        "stopped" : "Stopped",
        "testing" : "Testing",
        "working" : "Working"
      }
    },
    "page_id" :
   {
     "label" : "Page ID",
     "type" : "number"
   }
...
How to add data to the report

Fields are added as string values of the filter parameter from the Statistics report resource.

Restrictions apply to the use of SQL statements. Such restrictions apply to the data types used in the fields:

"=" operator (equal to)

Used for scalar values.

Operator value

Creates a report based on the specified field value.

Types of fields accepted by the operator:

  • boolean
  • contractnumber
  • dictionary
  • domain_mirror
  • login
  • multistate
  • number
  • publicid
  • straight_number
  • text
  • tree

Usage example

Filter data for content sites that have the "Active" status:

filter=["multistate","=","working"]

where multistate is the field name and working is the field value.

Result

The report shows the requested data filtered by active content sites.

"<>" operator (not equal to)

Used for scalar values.

Operator value

The specified field value is excluded from the report.

Types of fields accepted by the operator:

  • dictionary
  • domain_mirror
  • login
  • multistate
  • number
  • publicid
  • straight_number
  • text
  • tree

Usage example

Filter data for content sites, excluding sites that have the "Active" status:

filter=["multistate","<>","working"]

where multistate is the field name and working is the field value.

Result

The report shows the requested data filtered by the site status. The data on active sites will be excluded from the report.

"IN" operator (matching a list)

Used for arrays.

Operator value

Creates a report for the specified field values.

Types of fields accepted by the operator:

  • contractnumber
  • domain_mirror
  • login
  • number
  • publicid
  • straight_number
  • text

Usage example

Filter the data based on the IDs of the content sites in the 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 IDs of the listed sites.

">" operator (greater than)

Used for scalar values.

Operator value

Creates a report for the field values that are greater than the specified value.

Types of fields accepted by the operator:

  • number
  • straight_number

Usage example

Filter the data according to the content site 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.

"<" operator (less than)

Used for scalar values.

Operator value

Creates a report for the field values that are less than the specified value.

Types of fields accepted by the operator:

  • number
  • straight_number

Usage example

Filter the data according to the content site IDs 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.

">=" operator (greater than or equal to)

Used for scalar values.

Operator value

Creates a report for the field values that are greater than or equal to the specified value.

Types of fields accepted by the operator:

  • number
  • straight_number

Usage example

Filter the data by content site 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.

Operator value

Creates a report for the field values that are less than or equal to the specified value.

Types of fields accepted by the operator:

  • number
  • straight_number

Usage example

Filter the data according to the content site IDs 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 matching a list)

Used for arrays.

Operator value

Generates the report for the field values that are not in the specified list.

Types of fields accepted by the operator:

  • domain_mirror
  • login
  • number
  • publicid
  • straight_number
  • text

Usage example

Filter the data based on the content site IDs that are not in the 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. The data for the specified site IDs will be excluded from the report.

The "LIKE" operator (matches the specified substring)

Used for scalar values.

Operator value

Creates the report for the field values that match the specified substring.

Types of fields accepted by the operator:

  • domain_mirror
  • login
  • text

Usage example

Filter the data by a site name that matches the specified value:

filter=["domain","LIKE","aliexpress"]

where domain is the field name and aliexpress is the field value.

Result

The report shows the queried data filtered by the site names that match the specified value.

The "NOT LIKE" operator (does not match the specified substring)

Used for scalar values.

Operator value

Creates a report for the field values that don't match the specified substring.

Types of fields accepted by the operator:

  • domain_mirror
  • login
  • text

Usage example

Filter the data by a site name that doesn't match 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. The data for the specified site name will be excluded from the report.

"AND" operator

Operator value

Used for combining filters.

Usage example

Filter the data both by the site name and content site ID. You have two filters:

filter=["domain","=","aliexpress"]

filter=["page_id","=","53100"]

Combine two filters into one:

filter=["AND",[["domain","=","aliexpress"],["page_id","=","53100"]]]

Result

The report shows the requested data filtered by the site name and ID of a content site.

"OR" operator

Operator value

Used for matching at least one of the listed filters.

Usage example

Filter the data either by the site name or the content site ID. You have two filters:

filter=["domain","=","aliexpress"]

filter=["page_id","=","53100"]

Combine two filters into one:

filter=["OR",[["domain","=","aliexpress"],["page_id","=","53100"]]]

Result

The report shows the requested data filtered by the site name or the content site ID.

Build a request to create a report

Select the fields for the report. As an example, let's select the fields:

  • Indicator fields. Let's output the data for the following indicators: ad requests from ad blocks (hits), renderings of ads in ad blocks (hits_render), and ad impressions in ad blocks (shows).
  • Grouping fields. Let's group the data by the following fields: period by day (period|day) and site ID (page_id).
  • Filtering fields. Let's filter the data for the site 458472 ("page_id","=","458472").

The syntax for the query is defined in the Statistics report resource. Let's build a report based on the following parameters:

  1. Select the response language

  2. Set the time interval for the report

    period=thismonth

  3. Format the response so it's easy to read

    pretty=1

  4. Pass the indicator fields that you want to see in the report

    field=shows&field=hits_render&field=hits

  5. Group the data in the report by day

    dimension_field=date|day

  6. Group the data by site

    entity_field=page_id

  7. Filter the data by site. Get the report containing data only for the specified site

    filter=["page_id","=","458472"]'

The final request:

curl -g -X GET 'https://partner2.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 (partial):

{
   "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 blocks",
            "type" : "number",
            "unit" : "count"
         },
         "hits_render" : {
            "index" : 4,
            "title" : "Ad renderings in blocks",
            "type" : "number",
            "unit" : "count"
         },
         "shows" : {
            "index" : 3,
            "title" : "Ad impressions in blocks",
            "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 01.12.2020 - 15.12.2020",
      "total_rows" : 5,
      "totals" : {
         "2" : [
            {
               "hits" : 254,
               "hits_render" : 254,
               "shows" : 43
            }
         ]
      }
   },
   "result" : "ok"
}
Previous
Error messages
Next
How to get data about Mobile mediation
In this article: