CreateNewReport
Запускает на сервере формирование отчета о статистике кампании.
Для метода существует версия CreateNewReport (Live).
Вместо формирования отчета, предпочтительно получать статистику с помощью методов GetSummaryStat и GetBannersStat (Live), если предлагаемый ими объем данных достаточен.
Метод возвращает идентификатор будущего отчета. По идентификатору можно узнать о готовности отчета и получить ссылку для скачивания файла с отчетом (метод GetReportList). Среднее время формирования отчета — одна-две минуты.
Ограничения
Для одной кампании возможно не более 300 вызовов метода CreateNewReport
в сутки.
Для одного пользователя на сервере хранится не более пяти отчетов. При попытке сформировать шестой отчет возвращается сообщение об ошибке с кодом 31. Отчеты хранятся в течение пяти часов, а затем автоматически удаляются. С помощью метода DeleteReport можно удалить отчет вручную.
Отчетный период
Отчетный период, заданный параметрами StartDate
и EndDate
, не должен превышать:
- 367 дней — для отчета с группировкой данных по объявлениям (clBanner), фразам (clPhrase), типу показа (clImage) и/или по дням;
- 31 день — для отчета с любой другой группировкой.
Если указан более длительный отчетный период, возвращается сообщение об ошибке с кодом 5.
Цели и конверсии
Для получения данных о поведении посетителей на сайте (показатели 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 |
||
|
Идентификатор кампании, для которой формируется отчет. |
Да |
|
Начальная дата отчетного периода, |
Да |
|
Конечная дата отчетного периода, |
Да |
|
Названия показателей, выводимых в отчет дополнительно к статистическим данным. Возможные значения:
|
Нет |
|
Рассчитывать суммарную статистику по периодам времени:
Параметр имеет смысл указывать, если в массиве |
Нет |
|
Названия показателей, по которым сортируются записи в отчете. Возможные значения приведены в описании параметра |
Нет |
|
Количество записей, отбираемых из базы данных в отчет (больше нуля). |
Нет |
|
Номер записи, с которой начинается выборка (нумерация с нуля). Параметры |
Если задан параметр |
|
Формат отчета. В настоящее время используется только значение “xml”. |
Нет |
|
Метод сжатия отчета:
|
Нет |
|
Объект |
Нет |
Объект NewReportFilterInfo |
||
|
Отбирать записи по типам сайтов, на которых показаны объявления:
|
Нет |
|
Отбирать записи по блоку показа:
|
Нет |
|
Массив идентификаторов объявлений. Отбираются записи о показе указанных объявлений. |
Нет |
|
Массив идентификаторов регионов. Отбираются записи о показе объявлений в указанных регионах. |
Нет |
|
Массив строк. Отбираются записи о показе объявлений по тем ключевым фразам, которые содержат любую из указанных строк в качестве подстроки (без учета регистра символов). Примечание
|
Нет |
|
Массив названий сайтов. Отбираются записи о показе объявлений на указанных сайтах. Поисковый сайт Яндекса имеет название “Яндекс”. Для других сайтов указываются домены, зарегистрированные в Яндекс Директе, например “mail.ru”, “nigma.ru”. |
Нет |
|
Идентификатор цели Яндекс Метрики (указывается как элемент массива). Не допускается указывать более одного идентификатора. Если не задан, то показатели из Яндекс Метрики в отчете содержат агрегированные данные по всем целям. Список целей можно получить с помощью метода GetStatGoals (Live). |
Нет |
|
Отбирать записи о показах объявлений с изображениями или без. Возможные значения: yes — с изображениями, no — текстовые, both — все (текстовые, с изображениями и с видео). |
Нет |
|
Отбирать записи о показах объявлений на конкретном типе устройств. Возможные значения: desktop/mobile/tablet. |
Нет |
|
Отбирать записи о показах объявлений пользователям указанных возрастных групп. В массиве могут присутствовать следующие значения: AGE_0_17, AGE_18_24, AGE_25_34, AGE_35_44, AGE_45, AGE_UNKNOWN. |
Нет |
|
Отбирать записи о показах объявлений пользователям указанного пола. В массиве могут присутствовать следующие значения: GENDER_MALE, GENDER_FEMALE, GENDER_UNKNOWN. |
Нет |
|
Отбирать записи о показах объявлений на устройствах с указанными типами операционных систем. В массиве могут присутствовать следующие значения: ANDROID, IOS, OS_TYPE_UNKNOWN. Фильтрация по типу операционной системы доступна только для кампаний с типом “Реклама мобильных приложений”“Ads for mobile apps”. |
Нет |
|
Отбирать записи о показах объявлений по указанному типу связи. В массиве могут присутствовать следующие значения: CELLULAR (мобильная связь), STATIONARY (wi-fi), CARRIER_TYPE_UNKNOWN. Фильтрация по типу связи доступна только для кампаний с типом “Реклама мобильных приложений”“Ads for mobile apps”. |
Нет |
Результирующие данные
Метод возвращает идентификатор будущего отчета, как показано в следующем примере.
{
"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 |
Начальная дата отчетного периода, |
|
endDate |
Конечная дата отчетного периода, |
|
phrasesDict |
Словарь фраз. Содержит информацию об объектах в отчете: фразах, рубриках Яндекс Каталога, ретаргетингах, условиях нацеливания для динамических текстовых объявлений. |
|
stat |
Статистические данные. |
|
Элемент phrasesDict |
||
phrase |
Информация о фразе, рубрике или ретаргетинге в атрибутах |
|
|
Содержит значение “phrase” в записях о фразах, или “rubric” в записях о рубриках Яндекс Каталога, или “retargeting” в записях о ретаргетингах. |
|
|
Идентификатор фразы в отчете. Идентификатор |
|
|
Идентификатор рубрики в отчете. Существует только внутри отчета и не совпадает с идентификатором рубрики в Директе. Служит для нормализации данных в отчете и связывает элементы |
|
|
Идентификатор ретаргетинга в отчете. Существует только внутри отчета и не совпадает с идентификатором ретаргетинга в Директе. Служит для нормализации данных в отчете и связывает элементы |
|
|
Текст фразы, или номер рубрики Яндекс Каталога, или описание ретаргетинга в отчете. |
|
Элемент stat |
||
row |
Статистика по фразе за один день отчетного периода. |
|
|
Стоимость кликов, списанная с баланса кампании. |
|
|
Количество показов. |
|
|
Количество кликов. |
|
|
Идентификатор объявления. |
Во входном параметре |
|
Идентификатор фразы в отчете (см. элемент Идентификатор |
Во входном параметре |
|
Идентификатор рубрики Яндекс Каталога в отчете (см. элемент Существует только внутри отчета и не совпадает с идентификатором рубрики в Директе. Служит для нормализации данных в отчете и связывает элементы |
Во входном параметре |
|
Идентификатор ретаргетинга в отчете (см. элемент Существует только внутри отчета и не совпадает с идентификатором ретаргетинга в Директе. Служит для нормализации данных в отчете и связывает элементы |
Во входном параметре |
|
Идентификатор ретаргетинга в Директе. |
Во входном параметре |
|
Дата, за которую приведена статистика. Если входной параметр GroupByDate имеет значение “week” или “month”, указывается первая дата недели или месяца соответственно. |
В массиве GroupByColumns присутствует значение “clDate”. |
|
Стоимость кликов на поиске. |
Входной параметр PageType не задан или имеет значение “all”. |
|
Стоимость кликов в Рекламной сети Яндекса. |
|
|
Количество показов на поиске. |
|
|
Количество показов в Рекламной сети Яндекса. |
|
|
Количество кликов на поиске. |
|
|
Количество кликов в Рекламной сети Яндекса. |
|
|
Идентификатор региона показов. |
В массиве GroupByColumns присутствует значение “clGeo”. |
|
Название площадки показов. |
В массиве GroupByColumns присутствует значение “clPage”. |
|
Тип площадки показов: “search” — поисковая площадка (включая поиск Яндекса и поисковые площадки в Рекламной сети Яндекса), “context” — сайт в Рекламной сети Яндекса. |
|
|
Идентификатор целицели в Яндекс Метрике, если он был передан во входном параметре 0 — если идентификатор не был передан. В этом случае остальные показатели из Яндекс Метрики содержат агрегированные данные по всем целям. |
В массиве GroupByColumns присутствует значение “clStatGoals”. |
|
Доля целевых визитов в общем числе визитов, в процентах. |
|
|
Средняя цена целевого визита: отношение выручки к количеству целевых визитов. |
|
|
Глубина просмотра сайта. |
|
|
Количество целевых визитов (конверсий). |
В массиве GroupByColumns присутствует значение “clGoalConversionsNum”. |
|
Блок показа объявления: “premium” — спецразмещение, “other” — другие блоки. |
В массиве GroupByColumns присутствует значение “clPositionType”. |
|
Тип показа объявления: с изображением или без. Возможные значения: Image/Text. |
В массиве GroupByColumns присутствует значение “clImage”. |
|
Средняя позиция показа объявления. При расчете учитываются только показы на первой странице результатов поиска Яндекса. Наивысшая позиция имеет номер 1. |
В массиве GroupByColumns присутствует значение “clAveragePosition”. |
|
Средняя позиция, на которой произошел клик по объявлению. При расчете учитываются только клики на первой странице результатов поиска Яндекса. |
|
Примечания |
||
|