CreateNewReport

Запускает на сервере формирование отчета о статистике кампании.

Внимание.

Метод отключен. Используйте API версии 5.

Информацию о соответствии методов в версиях 4 и 5 см. в Руководстве по переходу.

Для метода существует версия CreateNewReport (Live).

Вместо формирования отчета, предпочтительно получать статистику с помощью методов GetSummaryStat и GetBannersStat (Live), если предлагаемый ими объем данных достаточен.

Метод возвращает идентификатор будущего отчета. По идентификатору можно узнать о готовности отчета и получить ссылку для скачивания файла с отчетом (метод GetReportList). Среднее время формирования отчета — одна-две минуты.

Ограничения

Для одной кампании возможно не более 300 вызовов метода CreateNewReport в сутки.

Для одного пользователя на сервере хранится не более пяти отчетов. При попытке сформировать шестой отчет возвращается сообщение об ошибке с кодом 31. Отчеты хранятся в течение пяти часов, а затем автоматически удаляются. С помощью метода DeleteReport можно удалить отчет вручную.

Отчетный период

Отчетный период, заданный параметрами StartDate и EndDate, не должен превышать:

  • 367 дней — для отчета с группировкой данных по объявлениям (clBanner), фразам (clPhrase), типу показа (clImage) и/или по дням;
  • 31 день — для отчета с любой другой группировкой.

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

Статистика доступна за последние три года от текущего месяца: например, 15 сентября 2016 года можно получить данные начиная с 1 сентября 2013 года.

Цели и конверсии

Для получения данных о поведении посетителей на сайте (показатели goal_id, session_depth, goal_conversion, goal_cost, goal_conversions_num, revenue, roi) необходимо, чтобы на сайте рекламодателя был установлен счетчик Яндекс.Метрики. Номер счетчика необходимо указать в параметре кампании AdditionalMetrikaCounters.

Для показателей goal_id, goal_conversion, goal_cost, goal_conversions_num, revenue, roi дополнительно требуется, чтобы для счетчика были настроены цели, для показателей revenue, roi — чтобы код счетчика передавал стоимость заказа.

Средняя позиция

Данные по средней позиции объявления доступны начиная с 01.11.2014.

Тип устройства

Данные по типу устройства доступны начиная с 01.11.2014.

Пол и возрастная группа пользователя

Данные по полу и возрасту доступны начиная с 22.07.2015.

Тип операционной системы и тип связи

Данные по типу операционной системы доступны начиная с 15.09.2015.

Данные по типу связи доступны начиная с 16.10.2015.

Корректировка ставок

Данные по условию ретаргетинга, в соответствии с которым была применена корректировка ставок для посетивших сайт, доступны начиная с 22.07.2015.

Входные данные

Ниже показана структура входных данных в формате JSON.

{
   "method": "CreateNewReport",
   "param": {
      /* NewReportInfo */
      "CampaignID": (int),
      "StartDate": (date),
      "EndDate": (date),
      "GroupByColumns": [
         (string)
         ...
      ],
      "Limit": (int),
      "Offset": (int),
      "GroupByDate": (string),
      "OrderBy": [
         (string)
         ...
      ],
      "TypeResultReport": (string),
      "CompressReport": (int),
      "Filter": {
         /* NewReportFilterInfo */
         "PageType": (string),
         "PositionType": (string),
         "Banner": [
            (long)
            ...
         ],
         "Geo": [
            (int)
            ...
         ],
         "Phrase": [
            (string)
            ...
         ],
         "PageName": [
            (string)
            ...
         ],
         "StatGoals": [
            (int)
            ...
         ],
         "WithImage": (string)
      }
   }
}

Ниже приведено описание параметров.

Параметр Описание Требуется
Объект NewReportInfo
CampaignID

Идентификатор кампании, для которой формируется отчет.

Да
StartDate

Начальная дата отчетного периода, YYYY-MM-DD.

Да
EndDate

Конечная дата отчетного периода, YYYY-MM-DD.

Да
GroupByColumns

Названия показателей, выводимых в отчет дополнительно к статистическим данным. Возможные значения:

  • clBanner — идентификатор объявления bannerID;
  • clDate — дата сбора статистики statDate;
  • clPage — данные о площадке показов: placeName, placeType;
  • clGeo — идентификатор региона показов regionID;
  • clPhrase — идентификатор фразы phraseID, или идентификатор рубрики Яндекс.Каталога rubricID, или идентификатор ретаргетинга DictID, или идентификатор источника данных для генерации динамических объявлений WebpageID;
  • clStatGoals — данные Яндекс.Метрики: goal_id, session_depth, goal_conversion, goal_cost (см. Цели и конверсии);
  • clGoalConversionsNum — данные Яндекс.Метрики: количество целевых визитов goal_conversions_num (см. Цели и конверсии). Рекомендуется указывать данное значение вместе с clStatGoals;
  • clPositionType — позиция показа position_type;
  • clImage — формат показа объявления stat_type, а также идентификатор объявления bannerID (значение clBanner автоматически добавляется к входным данным);
  • clAveragePosition — средняя позиция показов объявления shows_average_position и средняя позиция кликов по объявлению clicks_average_position. Чтобы получить эти показатели для каждого объявления в отдельности, следует указывать значение clAveragePosition вместе с clBanner;
  • clDeviceType — тип устройства, на котором показано объявление;
  • clROI — доход revenue и рентабельность roi (см. Цели и конверсии);
  • clDemographics — возрастная группа age и пол gender пользователя;
  • clMobilePlatform — тип операционной системы mobile_plaform (показатель доступен только для кампаний с типом «Реклама мобильных приложений»);
  • clCarrierType — тип связи carrier_type (показатель доступен только для кампаний с типом «Реклама мобильных приложений»);
  • clAdjustment — идентификатор условия ретаргетинга rl_adjustment_id, в соответствии с которым применена корректировка ставок (показатель доступен только для кампаний с типом «Текстово-графические объявления» или «Реклама мобильных приложений»).
Нет
GroupByDate

Рассчитывать суммарную статистику по периодам времени:

  • day — по дням (исходное значение);
  • week — по неделям;
  • month — по месяцам.

Параметр имеет смысл указывать, если в массиве GroupByColumns указано значение clDate, в противном случае параметр игнорируется.

Нет
OrderBy

Названия показателей, по которым сортируются записи в отчете. Возможные значения приведены в описании параметра GroupByColumns.

Нет
Limit

Количество записей, отбираемых из базы данных в отчет (больше нуля).

Параметры Limit и Offset служат для постраничной выборки записей.
Нет
Offset

Номер записи, с которой начинается выборка (нумерация с нуля).

Параметры Limit и Offset служат для постраничной выборки записей.

Если задан параметр Limit
TypeResultReport Формат отчета. В настоящее время используется только значение «xml». Нет
CompressReport

Метод сжатия отчета:

  • 0 или отсутствие параметра — не сжимать;
  • 1 — сжимать методом gzip.
Нет
Filter Объект NewReportFilterInfo с параметрами фильтрации записей для отчета. Если не задан, фильтрация не выполняется. Нет
Объект NewReportFilterInfo
PageType

Отбирать записи по типам сайтов, на которых показаны объявления:

  • search — на поиске Яндекса и на поисковых площадках в Рекламной сети Яндекса;
  • context — на сайтах в Рекламной сети Яндекса, кроме поисковых площадок;
  • all или отсутствие параметра — на всех типах сайтов.
Нет
PositionType

Отбирать записи по блоку показа:

  • premium — в спецразмещении;
  • other — везде, кроме спецразмещения.
Нет
Banner Массив идентификаторов объявлений. Отбираются записи о показе указанных объявлений. Нет
Geo Массив идентификаторов регионов. Отбираются записи о показе объявлений в указанных регионах. Нет
Phrase

Массив строк. Отбираются записи о показе объявлений по тем ключевым фразам, которые содержат любую из указанных строк в качестве подстроки (без учета регистра символов).

Примечание.
  • Параметр можно указывать только для кампаний с типом «Текстово-графические объявления» и «Реклама мобильных приложений».

  • Параметр игнорируется, если в параметре GroupByColumns отсутствует значение clPhrase.
Нет
PageName

Массив названий сайтов. Отбираются записи о показе объявлений на указанных сайтах.

Поисковый сайт Яндекса имеет название «Яндекс». Для других сайтов указываются домены, зарегистрированные в Яндекс.Директе, например «mail.ru», «nigma.ru».

Нет
StatGoals

Идентификатор цели Яндекс.Метрики (указывается как элемент массива). Не допускается указывать более одного идентификатора.

Если не задан, то показатели из Яндекс.Метрики в отчете содержат агрегированные данные по всем целям.

Список целей можно получить с помощью метода GetStatGoals (Live).

Нет
WithImage Отбирать записи о показах объявлений с изображениями или без. Возможные значения: yes — с изображениями, no — текстовые, both — все (текстовые, с изображениями и с видео). Нет
DeviceType

Отбирать записи о показах объявлений на конкретном типе устройств. Возможные значения: desktop/mobile/tablet.

Нет
Age Отбирать записи о показах объявлений пользователям указанных возрастных групп. В массиве могут присутствовать следующие значения: AGE_0_17, AGE_18_24, AGE_25_34, AGE_35_44, AGE_45, AGE_UNKNOWN. Нет
Gender Отбирать записи о показах объявлений пользователям указанного пола. В массиве могут присутствовать следующие значения: GENDER_MALE, GENDER_FEMALE, GENDER_UNKNOWN. Нет
MobilePlatform

Отбирать записи о показах объявлений на устройствах с указанными типами операционных систем. В массиве могут присутствовать следующие значения: ANDROID, IOS, OS_TYPE_UNKNOWN.

Фильтрация по типу операционной системы доступна только для кампаний с типом «Реклама мобильных приложений».

Нет
CarrierType

Отбирать записи о показах объявлений по указанному типу связи. В массиве могут присутствовать следующие значения: CELLULAR (мобильная связь), STATIONARY (wi-fi), CARRIER_TYPE_UNKNOWN.

Фильтрация по типу связи доступна только для кампаний с типом «Реклама мобильных приложений».

Нет

Результирующие данные

Метод возвращает идентификатор будущего отчета, как показано в следующем примере.

{
   "data": 137456
}

Примеры входных данных

Python

{
   'CampaignID': 1327944,
   'StartDate': '2013-05-01',
   'EndDate': '2013-05-31',
   'GroupByColumns': [
      'clBanner',
      'clStatGoals',
      'clGoalConversionsNum',
      'clAveragePosition',
      'clROI'
   ],
   'Filter': {
      'PageType': 'search',
      'PositionType': 'other',
      'Banner': [1974642, 20920155, 20155899, 64654],
      'Geo': [213],
      'Phrase': [u'холодильник'],
      'PageName': [u'Яндекс','nigma.ru'],
      'StatGoals': [18565]
   },
   'Limit': 5000,
   'Offset': 30000,
   'GroupByDate': 'week',
   'OrderBy': ['clBanner'],
   'TypeResultReport': 'xml',
   'CompressReport': 1
}

PHP

array(
   'CampaignID' => 1327944,
   'StartDate' => '2013-05-01',
   'EndDate' => '2013-05-31',
   'GroupByColumns' => array(
      'clBanner',
      'clStatGoals',
      'clGoalConversionsNum',
      'clAveragePosition',
      'clROI'
   ),
   'Filter' => array(
      'PageType' => 'search',
      'PositionType' => 'other',
      'Banner' => array(1974642, 20920155, 20155899, 64654),
      'Geo' => array(213),
      'Phrase' => array('холодильник'),
      'PageName' => array('Яндекс','nigma.ru'),
      'StatGoals' => array(18565)
   ),
   'Limit' => 5000,
   'Offset' => 30000,
   'GroupByDate' => 'week',
   'OrderBy' => array('clBanner'),
   'TypeResultReport' => 'xml',
   'CompressReport' => 1
)

Perl

{
   'CampaignID' => 1327944,
   'StartDate' => '2013-05-01',
   'EndDate' => '2013-05-31',
   'GroupByColumns' => [
      'clBanner',
      'clStatGoals',
      'clGoalConversionsNum',
      'clAveragePosition',
      'clROI'
   ],
   'Filter' => {
      'PageType' => 'search',
      'PositionType' => 'other',
      'Banner' => [1974642, 20920155, 20155899, 64654],
      'Geo' => [213],
      'Phrase' => ['холодильник'],
      'PageName' => ['Яндекс','nigma.ru'],
      'StatGoals' => [18565]
   },
   'Limit' => 5000,
   'Offset' => 30000,
   'GroupByDate' => 'week',
   'OrderBy' => ['clBanner'],
   'TypeResultReport' => 'xml',
   'CompressReport' => 1
}

Пример отчета

Ниже показан пример отчета в формате XML.

<?xml version="1.0" encoding="UTF-8" ?>
<report> 
   <reportID>1234</reportID>
   <campaignID>1234567</campaignID>
   <startDate>2013-05-01</startDate>
   <endDate>2013-05-31</endDate>
   <phrasesDict>
      <phrase type="phrase" phraseID="2" value="морозильное оборудование" />
      <phrase type="retargeting" DictID="912" value="ретаргетинг: незавершенный заказ" />
   </phrasesDict>
   <stat>
      <row bannerID="123456"
           phraseID{stat}="2"
           statDate="2013-05-15"
           sum_search="10"
           sum_context="2"
           shows_search="1000"
           shows_context="123"
           clicks_search="100"
           clicks_context="23"
           sum="12"
           shows="1234"
           clicks="123"
           regionID="1"
           placeName="Яндекс"
           placeType="search"
           goal_id="18565"
           goal_conversion="25.91"
           goal_cost="1.54"
           session_depth="9.35"
           goal_conversions_num="28"  
           position_type="premium"
           stat_type="Text"
           shows_average_position="4.87"
           clicks_average_position="4.95"/>
      <row bannerID="123457"
           DictID{stat}="912"
           RetargetingID="3097"  
           statDate="2013-05-25"
           sum_search="0"
           sum_context="96.35"
           shows_search="0"
           shows_context="755"
           clicks_search="0"
           clicks_context="57"
           sum="96.35"
           shows="755"
           clicks="57"
           regionID="1"
           placeName="catalog.tut.by"
           placeType="context"
           goal_id="18777"
           goal_conversion="28.88"
           session_depth="9.39"
           position_type="other"
           stat_type="Image"/>
   </stat>
</report>

Ниже приведено описание элементов отчета.

Элемент/атрибут Описание Условие вывода
Элемент report
reportID Идентификатор отчета.
campaignID Идентификатор кампании.
startDate Начальная дата отчетного периода, YYYY-MM-DD.
endDate Конечная дата отчетного периода, YYYY-MM-DD.
phrasesDict Словарь фраз. Содержит информацию об объектах в отчете: фразах, рубриках Яндекс.Каталога, ретаргетингах, условиях нацеливания для динамических текстовых объявлений.
stat Статистические данные.
Элемент phrasesDict
phrase Информация о фразе, рубрике или ретаргетинге в атрибутах type, phraseID, DictID, value.
type Содержит значение «phrase» в записях о фразах, или «rubric» в записях о рубриках Яндекс.Каталога, или «retargeting» в записях о ретаргетингах.
phraseID

Идентификатор фразы в отчете.

Идентификатор phraseID существует только внутри отчета и не совпадает с идентификатором фразы в Директе. Он служит для нормализации данных в отчете и связывает элементы phrase и row.

rubricID

Идентификатор рубрики в отчете.

Существует только внутри отчета и не совпадает с идентификатором рубрики в Директе. Служит для нормализации данных в отчете и связывает элементы phrase и row.

DictID

Идентификатор ретаргетинга в отчете.

Существует только внутри отчета и не совпадает с идентификатором ретаргетинга в Директе. Служит для нормализации данных в отчете и связывает элементы phrase и row.

value Текст фразы, или номер рубрики Яндекс.Каталога, или описание ретаргетинга в отчете.
Элемент stat
row Статистика по фразе за один день отчетного периода.
sum

Стоимость кликов, списанная с баланса кампании 1 .

shows Количество показов 1 .
clicks Количество кликов 1 .
bannerID Идентификатор объявления. Во входном параметре GroupByColumns указано значение «clBanner» или «clImage».
phraseID

Идентификатор фразы в отчете (см. элемент phrasesDict).

Идентификатор phraseID существует только внутри отчета и не совпадает с идентификатором фразы в Директе. Он служит для нормализации данных в отчете и связывает элементы phrase и row.

Во входном параметре GroupByColumns указано значение «clPhrase» и запись содержит информацию о фразе (не о рубрике и не о ретаргетинге).

rubricID

Идентификатор рубрики Яндекс.Каталога в отчете (см. элемент phrasesDict).

Существует только внутри отчета и не совпадает с идентификатором рубрики в Директе. Служит для нормализации данных в отчете и связывает элементы phrase и row.

Во входном параметре GroupByColumns указано значение «clPhrase» и запись содержит информацию о рубрике Яндекс.Каталога.

DictID

Идентификатор ретаргетинга в отчете (см. элемент phrasesDict).

Существует только внутри отчета и не совпадает с идентификатором ретаргетинга в Директе. Служит для нормализации данных в отчете и связывает элементы phrase и row.

Во входном параметре GroupByColumns указано значение «clPhrase» и запись содержит информацию о ретаргетинге.

RetargetingID Идентификатор ретаргетинга в Директе. Во входном параметре GroupByColumns указано значение «clPhrase» и запись содержит информацию о ретаргетинге.
statDate Дата, за которую приведена статистика. Если входной параметр GroupByDate имеет значение «week» или «month», указывается первая дата недели или месяца соответственно. В массиве GroupByColumns присутствует значение «clDate».
sum_search

Стоимость кликов на поиске.

Входной параметр PageType не задан или имеет значение «all».
sum_context

Стоимость кликов в Рекламной сети Яндекса.

shows_search

Количество показов на поиске.

shows_context Количество показов в Рекламной сети Яндекса.
clicks_search Количество кликов на поиске.
clicks_context Количество кликов в Рекламной сети Яндекса.
regionID Идентификатор региона показов. В массиве GroupByColumns присутствует значение «clGeo».
placeName Название площадки показов. В массиве GroupByColumns присутствует значение «clPage».
placeType Тип площадки показов: «search» — поисковая площадка (включая поиск Яндекса и поисковые площадки в Рекламной сети Яндекса), «context» — сайт в Рекламной сети Яндекса.
goal_id

Идентификатор цели в Яндекс.Метрике, если он был передан во входном параметре StatGoals.

0 — если идентификатор не был передан. В этом случае остальные показатели из Яндекс.Метрики содержат агрегированные данные по всем целям.

В массиве GroupByColumns присутствует значение «clStatGoals».

goal_conversion Доля целевых визитов в общем числе визитов, в процентах.
goal_cost Средняя цена целевого визита: отношение выручки к количеству целевых визитов.
session_depth Глубина просмотра сайта.
goal_conversions_num

Количество целевых визитов (конверсий).

В массиве GroupByColumns присутствует значение «clGoalConversionsNum».

position_type

Блок показа объявления: «premium» — спецразмещение, «other» — другие блоки.

В массиве GroupByColumns присутствует значение «clPositionType».
stat_type Тип показа объявления: с изображением или без. Возможные значения: Image/Text. В массиве GroupByColumns присутствует значение «clImage».
shows_average_position

Средняя позиция показа объявления. При расчете учитываются только показы на первой странице результатов поиска Яндекса.

Наивысшая позиция имеет номер 1.

В массиве GroupByColumns присутствует значение «clAveragePosition».
clicks_average_position Средняя позиция, на которой произошел клик по объявлению. При расчете учитываются только клики на первой странице результатов поиска Яндекса.
Примечания
  1. Значения параметров sum, shows, clicks зависят от входного параметра PageType:

    • при значении «all» или отсутствии PageType приводятся суммарные данные по поиску и Рекламной сети Яндекса. При этом данные отдельно по поиску и отдельно по Рекламной сети приводятся в параметрах sum_search, shows_search, clicks_search, sum_context, shows_context, clicks_context);
    • при значении «search» приводятся данные по поиску и поисковым площадкам в Рекламной сети Яндекса;
    • при значении «context» приводятся данные по сайтам в Рекламной сети Яндекса, кроме поисковых площадок.