Как построить отчет

Чтобы построить отчет:

Запросите дерево статистики

Чтобы получить дерево статистики, используйте ресурс Дерево статистики. В результате будут получены уровни статистики и поля для каждого уровня.

Пример запроса:

curl -i -X GET 'https://partner2.yandex.ru/api/statistics2/tree.json?lang=ru&pretty=1' \
-H 'Authorization: OAuth 123qwe456a...'

Пример фрагмента ответа:

{
   "data" : {
      "tree" : [
         {
            "conflict_fields" : [],
            "dimension_fields" : [
               {
                  "id" : "date",
                  "title" : "Дата",
                  "type" : "select",
                  "values" : [
                     [
                        "month",
                        "по месяцам"
                     ],
                     [
                        "week",
                        "по неделям"
                     ],
                     [
                        "day",
                        "по дням"
                     ],
                     [
                        "year",
                        "по годам"
                     ]
                  ]
               },
               {
                  "id" : "geo",
                  "title" : "География",
                  "type" : "select",
                  "values" : [
                     [
                        "country",
                        "по странам"
                     ],
                     [
                        "city",
                        "по городам"
                     ],
                     [
                        "area",
                        "по областям"
                     ]
                  ]
               }
            ],
            "entity_fields" : [
               {
                  "category" : 14,
                  "category_name" : "Продукт",
                  "id" : "block_level",
                  "index" : 4,
                  "label" : "Блочный уровень продукта",
                  "type" : "tree"
               },
               {
                  "category" : 14,
                  "category_name" : "Продукт",
                  "id" : "page_level",
                  "index" : 5,
                  "label" : "Уровень продукта",
                  "type" : "tree"
               },
               {
                  "category" : 12,
                  "category_name" : "Площадка",
                  "id" : "page_id",
                  "index" : 11,
                  "label" : "Page ID",
                  "type" : "publicid"
               },
               {
                  "category" : 12,
                  "category_name" : "Площадка",
                  "id" : "page_caption",
                  "index" : 12,
                  "label" : "Название пейджа",
                  "type" : "text"
               },
               {
                  "category" : 10,
                  "category_name" : "Блок",
                  "id" : "complex_block_id",
                  "index" : 14,
                  "label" : "ID Блока",
                  "type" : "publicid"
               },
               {
                  "category" : 10,
                  "category_name" : "Блок",
                  "id" : "block_caption",
                  "index" : 15,
                  "label" : "Название блока",
                  "type" : "text"
               },
               {
                  "category" : 10,
                  "category_name" : "Блок",
                  "id" : "tag_id",
                  "index" : 16,
                  "label" : "ID Среза",
                  "type" : "publicid"
               },
               {
                  "category" : 9,
                  "category_name" : "ADFOX",
                  "id" : "adfox_block",
                  "index" : 17,
                  "label" : "Блок ADFOX",
                  "type" : "boolean"
               },
               {
                  "category" : 9,
                  "category_name" : "ADFOX",
                  "id" : "deal_id",
                  "index" : 18,
                  "label" : "ID сделки",
                  "type" : "publicid"
               },
               {
                  "category" : 9,
                  "category_name" : "ADFOX",
                  "id" : "deal_caption",
                  "index" : 19,
                  "label" : "Название сделки",
                  "type" : "text"
               },
               {
                  "id" : "business_rule_id",
                  "index" : 20,
                  "label" : "ID правила",
                  "type" : "publicid"
               },
               {
                  "id" : "business_rule_title",
                  "index" : 21,
                  "label" : "Название правила",
                  "type" : "text"
               },
               {
                  "category" : 7,
                  "category_name" : "Трафик",
                  "id" : "os",
                  "index" : 22,
                  "label" : "Операционная система",
                  "type" : "publicid"
               },
               {
                  "category" : 7,
                  "category_name" : "Трафик",
                  "id" : "browser",
                  "index" : 23,
                  "label" : "Браузер",
                  "type" : "publicid"
               },
...
               {
                  "category" : 6,
                  "category_name" : "Показатели по рекомендациям",
                  "id" : "RecommendationWidgetCTR",
                  "index" : 58,
                  "title" : "CTR рекомендательного виджета",
                  "type" : "text"
               }
            ],
            "has_product" : "",
            "has_raw_stat" : "",
            "id" : "payment",
            "title" : "Вознаграждения"
         }
      ]
   },
   "result" : "ok"
}

Выберите из дерева статистики поля для построения отчета

Поля можно условно разделить на три группы:

Поля-показатели

Это поля, которые выводят какую-либо статистическую информацию, например, показы рекламы в блоках, запросы рекламы в блоках.

Обязательность

В отчете должно присутствовать хотя бы одно поле данной группы.

Где найти список полей

Список допустимых полей выводится в структуре fields, ресурс Дерево статистики. Пример:

{
  ...
  "fields":
  [
    {
      "category" : 1,
      "category_name" : "Исходные данные",
      "id" : "shows",
      "index" : 30,
      "title" : "Показы рекламы в блоках",
      "type" : "text"
    },
    {
      "category" : 1,
      "category_name" : "Исходные данные",
      "id" : "hits",
      "index" : 36,
      "title" : "Запросы рекламы в блоках",
      "type" : "text"
    }
  ]
  ...
}
Как добавить в отчет

Поля добавляются в качестве значений параметра field, ресурс Отчет по статистике. Для добавления используются идентификаторы выбранных полей.

Примечание

Чтобы добавить в отчет несколько полей, укажите параметр несколько раз:

field=shows&field=hits

Поля-группировки

Это поля, по которым можно группировать остальные данные в отчете.

Группировки могут быть двух видов:

  • группировка по полям, которые не принадлежат конкретному продукту на текущем уровне (например, группировка по периоду, валюте или полю из другого продукта);
  • группировка по остальным полям (например, идентификаторы, названия).
Обязательность

Поля-группировки могут отсутствовать в отчете.

Где найти список полей

Список допустимых полей, которые отвечают за группировки, выводится в структуре dimension_fields и в структуре entity_fields, ресурс Дерево статистики.

Пример:

...
  "dimension_fields":
  [
    {
      "id" : "date",
      "title" : "Период",
      "type" : "select",
      "values" : [
        [
          "day",
          "Группировать по дням"
        ],
        [
          "week",
          "Группировать по неделям"
        ],
        [
          "month",
          "Группировать по месяцам"
        ],
        [
          "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" : "Валюта",
      "type" : "dictionary"
    },
    {
      ...
    }
  ]
...
...
  "entity_fields":
  [
    {
      "id" : "page_id",
      "label" : "Page ID",
      "type" : "page_id"
    },
    {
      "id" : "domain",
      "label" : "Домен",
      "type" : "text"
    }
  ]
...
Как добавить в отчет

Поля добавляются в качестве значений параметров dimension_field и entity_field, ресурс Отчет по статистике.

Примечание

Чтобы произвести группировку по нескольким полям, укажите идентификаторы полей следующим образом:

entity_field=domain&entity_field=page_id

Поля-фильтры

Поля используют для фильтрации данных. Фильтрация происходит во время построения отчета.

К полям применяют операторы SQL и в зависимости от входных условий строится отчет.

Обязательность

Поля-фильтры могут отсутствовать в отчете.

Где найти список полей

Список допустимых полей, которые отвечают за фильтрацию данных при формировании отчета, выводится в структуре entity_filter_fields, ресурс Дерево статистики. Пример:

...
  "entity_filter_fields":
  {
    "multistate" : 
    {
      "label" : "Статус",
      "type" : "multistate",
      "values" : 
      {
        "need_approve" : "Необходимо утвердить",
        "rejected" : "Отклонена модератором",
        "stopped" : "Остановлена",
        "testing" : "Тестирование",
        "working" : "Работает"
      }
    },
    "page_id" :
   {
     "label" : "Page ID",
     "type" : "number"
   }
...
Как добавить в отчет

Поля добавляются в виде строки-значения параметра filter, ресурс Отчет по статистике.

По использованию операторов SQL есть ограничения. Эти ограничения связаны с типами данных, которые используются в полях:

Оператор "=" (равно)

Используется для скалярных значений.

Значение оператора

Формирует отчет по указанному значению поля.

Типы полей, с которыми работает оператор:

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

Пример записи

Необходимо отфильтровать данные по тематическим площадкам, которые находятся в статусе «Работает»:

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

где multistate — название поля, working — значение поля.

Результат

В отчете показываются запрашиваемые данные, отфильтрованные по работающим тематическим площадкам.

Оператор "<>" (не равно)

Используется для скалярных значений.

Значение оператора

Из отчета исключается заданное значение поля.

Типы полей, с которыми работает оператор:

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

Пример записи

Необходимо отфильтровать данные по тематическим площадкам, исключая площадки, которые находятся в статусе «Работает»:

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

где multistate — название поля, working — значение поля.

Результат

В отчете показываются запрашиваемые данные, отфильтрованные по статусу работы площадок. Данные по работающим площадкам будут исключены из отчета.

Оператор "IN" (входит в)

Используется для массивов.

Значение оператора

Формирует отчет по указанным значениям поля.

Типы полей, с которыми работает оператор:

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

Пример записи

Необходимо отфильтровать данные по идентификаторам тематических площадок, которые входят в указанный список:

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

где page_id — название поля, 53100, 53101 — значения поля.

Результат

В отчете показываются запрашиваемые данные, отфильтрованные по идентификаторам площадок из списка.

Оператор ">" (больше)

Используется для скалярных значений.

Значение оператора

Формирует отчет по значениям поля, которые больше указанного.

Типы полей, с которыми работает оператор:

  • number;
  • straight_number.

Пример записи

Необходимо отфильтровать данные по идентификаторам тематических площадок, которые больше указанного значения:

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

где page_id — название поля, 53100 — значение поля.

Результат

В отчете показываются запрашиваемые данные, отфильтрованные по всем идентификаторам площадок. Идентификаторы площадок будут больше указанного значения.

Оператор "<" (меньше)

Используется для скалярных значений.

Значение оператора

Формирует отчет по значениям поля, которые меньше указанного.

Типы полей, с которыми работает оператор:

  • number;
  • straight_number.

Пример записи

Необходимо отфильтровать данные по идентификаторам тематических площадок, которые меньше указанного значения:

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

где page_id — название поля, 53100 — значение поля.

Результат

В отчете показываются запрашиваемые данные, отфильтрованные по всем идентификаторам площадок. Идентификаторы площадок будут меньше указанного значения.

Оператор ">=" (больше или равно)

Используется для скалярных значений.

Значение оператора

Формирует отчет по значениям поля, которые больше указанного значения или равны ему.

Типы полей, с которыми работает оператор:

  • number;
  • straight_number.

Пример записи

Необходимо отфильтровать данные по идентификаторам тематических площадок, которые больше указанного значения или равны ему:

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

где page_id — название поля, 53100 — значение поля.

Результат

В отчете показываются запрашиваемые данные, отфильтрованные по всем идентификаторам площадок. Идентификаторы площадок будут больше или равны указанному значению.

Оператор "<=" (меньше или равно)

Используется для скалярных значений.

Значение оператора

Формирует отчет по значениям поля, которые меньше указанного значения или равны ему.

Типы полей, с которыми работает оператор:

  • number;
  • straight_number.

Пример записи

Необходимо отфильтровать данные по идентификаторам тематических площадок, которые меньше указанного значения или равны ему:

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

где page_id — название поля, 53100 — значение поля.

Результат

В отчете показываются запрашиваемые данные, отфильтрованные по всем идентификаторам площадок. Идентификаторы площадок будут меньше или равны указанному значению.

Оператор "NOT IN" (не входит в)

Используется для массивов.

Значение оператора

Формирует отчет по значениям поля, которые не входят в указанный список.

Типы полей, с которыми работает оператор:

  • domain_mirror;
  • login;
  • number;
  • publicid;
  • straight_number;
  • text.

Пример записи

Необходимо отфильтровать данные по идентификаторам тематических площадок, которые не входят в указанный список:

filter=["page_id","NOT IN",["53100","53101"]]

где page_id — название поля, 53100, 53101 — значения поля.

Результат

В отчете показываются запрашиваемые данные, отфильтрованные по всем идентификаторам площадок. Данные по указанным идентификаторам площадок будут исключены из отчета.

Оператор "LIKE" (входит в указанную подстроку)

Используется для скалярных значений.

Значение оператора

Формирует отчет по значениям поля, которые входят в указанную подстроку.

Типы полей, с которыми работает оператор:

  • domain_mirror;
  • login;
  • text.

Пример записи

Необходимо отфильтровать данные по названию сайта, которое входит в указанное значение:

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

где domain — название поля, aliexpress — значение поля.

Результат

В отчете показываются запрашиваемые данные, отфильтрованные по названиям сайтов, которые входят в указанное значение.

Оператор "NOT LIKE" (не входит в указанную подстроку)

Используется для скалярных значений.

Значение оператора

Формирует отчет по значениям поля, которые не входят в указанную подстроку.

Типы полей, с которыми работает оператор:

  • domain_mirror;
  • login;
  • text.

Пример записи

Необходимо отфильтровать данные по названию сайта, которое не входит в указанное значение:

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

где domain — название поля, aliexpress — значение поля.

Результат

В отчете показываются запрашиваемые данные, отфильтрованные по названиям сайтов. Данные по указанному названию сайта будут исключены из отчета.

Оператор "AND" (и)

Значение оператора

Используется для объединения фильтров.

Пример записи

Необходимо отфильтровать данные по названию сайта и по идентификатору тематической площадки. У нас есть два фильтра:

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

Объединяем два фильтра в один:

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

Результат

В отчете показываются запрашиваемые данные, отфильтрованные по названию сайта и по идентификатору тематической площадки.

Оператор "OR" (или)

Значение оператора

Используется для выполнения хотя бы одного из перечисленных фильтров.

Пример записи

Необходимо отфильтровать данные по названию сайта или по идентификатору тематической площадки. У нас есть два фильтра:

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

Объединяем два фильтра в один:

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

Результат

В отчете показываются запрашиваемые данные, отфильтрованные по названию сайта или по идентификатору тематической площадки.

Составьте запрос для построения отчета

Выберите поля для построения отчета. В качестве примера выберем поля:

  • Поля-показатели. Выводим данные по следующим показателям: запросы рекламы в блоках (hits), отрисовки рекламы в блоках (hits_render), показы рекламы в блоках (shows).
  • Поля-группировки. Сгруппируем данные по следующим полям: период по дням (period|day), идентификатор площадки (page_id).
  • Поля-фильтры. Отфильтруем данные по площадке 458472 ("page_id","=","458472").

Синтаксис составления запроса описан в ресурсе Отчет по статистике. Построим отчет с учетом следующих параметров:

  1. Выбираем язык ответа

  2. Задаем интервал времени, за который требуется получить отчет

    period=thismonth
    
  3. Форматируем ответ для удобства чтения

    pretty=1
    
  4. Передаем поля-показатели, которые хотим увидеть в отчете

    field=shows&field=hits_render&field=hits
    
  5. Группируем данные в отчете по дням

    dimension_field=date|day
    
  6. Группируем данные по площадке

    entity_field=page_id
    
  7. Фильтруем данные по площадке. Получаем отчет, который содержит данные только по указанной площадке

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

Итоговый вид запроса:

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...'

Фрагмент ответа:

{
   "data" : {
      "currencies" : [
         {
            "code" : "USD",
            "id" : "1"
         },
         {
            "code" : "RUB",
            "id" : "2"
         },
         {
            "code" : "EUR",
            "id" : "3"
         }
      ],
      "dimensions" : {
         "date" : {
            "index" : 1,
            "title" : "Дата",
            "type" : "date"
         },
         "page_id" : {
            "index" : 2,
            "title" : "Page ID",
            "type" : "page_id"
         }
      },
      "is_last_page" : true,
      "measures" : {
         "hits" : {
            "index" : 5,
            "title" : "Запросы рекламы в блоках",
            "type" : "number",
            "unit" : "count"
         },
         "hits_render" : {
            "index" : 4,
            "title" : "Отрисовки рекламы в блоках",
            "type" : "number",
            "unit" : "count"
         },
         "shows" : {
            "index" : 3,
            "title" : "Показы рекламы в блоках",
            "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" : "Отчет за период 01.12.2020 - 15.12.2020",
      "total_rows" : 5,
      "totals" : {
         "2" : [
            {
               "hits" : 254,
               "hits_render" : 254,
               "shows" : 43
            }
         ]
      }
   },
   "result" : "ok"
}