--- metadata: - name: generator content: Diplodoc Platform v5.52.0 alternate: - https://yandex.com/dev/direct/doc/dg-v4/en/reference/CreateNewReport.md - https://yandex.com/dev/direct/doc/dg-v4/ru/reference/CreateNewReport.md - href: ru/reference/CreateNewReport.md type: text/markdown title: Markdown version - href: ../llms.txt type: text/markdown title: llms.txt --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.com/dev/direct/doc/dg-v4/ru/llms.txt # CreateNewReport Запускает на сервере формирование отчета о статистике кампании. Для метода существует версия [CreateNewReport (Live)](https://yandex.ru/dev/direct/doc/dg-v4/live/CreateNewReport.html). Вместо формирования отчета, предпочтительно получать статистику с помощью методов [GetSummaryStat](GetSummaryStat.html) и [GetBannersStat (Live)](https://yandex.ru/dev/direct/doc/dg-v4/live/GetBannersStat.html), если предлагаемый ими объем данных достаточен. Метод возвращает идентификатор будущего отчета. По идентификатору можно узнать о готовности отчета и получить ссылку для скачивания файла с отчетом (метод [GetReportList](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/GetReportList.md)). Среднее время формирования отчета — одна-две минуты. ## Ограничения {#restrictions} Для одной кампании возможно не более 300 вызовов метода `CreateNewReport` в сутки. Для одного пользователя на сервере хранится не более пяти отчетов. При попытке сформировать шестой отчет возвращается сообщение об ошибке с кодом [31](https://yandex.ru/dev/direct/doc/dg-v4/reference/ErrorCodes.html#ErrorCode31). Отчеты хранятся в течение пяти часов, а затем автоматически удаляются. С помощью метода [DeleteReport](https://yandex.ru/dev/direct/doc/dg-v4/reference/DeleteReport.html) можно удалить отчет вручную. **Отчетный период**   Отчетный период, заданный параметрами `StartDate` и `EndDate`, не должен превышать: - 367 дней — для отчета с группировкой данных по объявлениям (clBanner), фразам (clPhrase), типу показа (clImage) и/или по дням; - 31 день — для отчета с любой другой группировкой. Если указан более длительный отчетный период, возвращается сообщение об ошибке с кодом [5](https://yandex.ru/dev/direct/doc/dg-v4/reference/ErrorCodes.html#ErrorCode5). **Цели и конверсии**   Для получения данных о поведении посетителей на сайте (показатели `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` дополнительно требуется, чтобы для счетчика были настроены [цели](https://yandex.ru/support/metrika/general/goals.xml), для показателей `revenue`, `roi` — чтобы код счетчика передавал [стоимость заказа](https://yandex.ru/support/metrika/data/e-commerce.xml). **Средняя позиция**   Данные по средней позиции объявления доступны начиная с 01.11.2014. **Тип устройства**   Данные по типу устройства доступны начиная с 01.11.2014. **Пол и возрастная группа пользователя**   Данные по полу и возрасту доступны начиная с 22.07.2015. **Тип операционной системы и тип связи**   Данные по типу операционной системы доступны начиная с 15.09.2015. Данные по типу связи доступны начиная с 16.10.2015. **Корректировка ставок**   Данные по условию ретаргетинга, в соответствии с которым была применена корректировка ставок для посетивших сайт, доступны начиная с 22.07.2015. ## Входные данные {#input} Ниже показана структура входных данных в формате JSON. ```javascript { "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` (см. [Цели и конверсии](#goals-data)); - clGoalConversionsNum — данные Яндекс Метрики: количество целевых визитов `goal_conversions_num` (см. [Цели и конверсии](#goals-data)). Рекомендуется указывать данное значение вместе с clStatGoals; - clPositionType — позиция показа `position_type`; - clImage — формат показа объявления `stat_type`, а также идентификатор объявления `bannerID` (значение clBanner автоматически добавляется к входным данным); - clAveragePosition — средняя позиция показов объявления `shows_average_position` и средняя позиция кликов по объявлению `clicks_average_position`. Чтобы получить эти показатели для каждого объявления в отдельности, следует указывать значение clAveragePosition вместе с clBanner; - clDeviceType — тип устройства, на котором показано объявление; - clROI — доход `revenue` и рентабельность `roi` (см. [Цели и конверсии](#goals-data)); - clDemographics — возрастная группа `age` и пол `gender` пользователя; - clMobilePlatform — тип операционной системы `mobile_plaform` (показатель доступен только для кампаний с типом “Реклама мобильных приложений”“Ads for mobile apps”); - clCarrierType — тип связи `carrier_type` (показатель доступен только для кампаний с типом “Реклама мобильных приложений”“Ads for mobile apps”); - clAdjustment — идентификатор условия ретаргетинга `rl_adjustment_id`, в соответствии с которым применена корректировка ставок (показатель доступен только для кампаний с типом “Текстово-графические объявления”“Text & Image Ads” или “Реклама мобильных приложений”“Ads for mobile apps”). | Нет || || `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` | Массив строк. Отбираются записи о показе объявлений по тем ключевым фразам, которые содержат любую из указанных строк в качестве подстроки (без учета регистра символов). {% note info %} - Параметр можно указывать только для кампаний с типом “Текстово-графические объявления”“Text & Image Ads” и “Реклама мобильных приложений”“Ads for mobile apps”. - Параметр игнорируется, если в параметре `GroupByColumns` отсутствует значение clPhrase. {% endnote %} | Нет || || `PageName` | Массив названий сайтов. Отбираются записи о показе объявлений на указанных сайтах. Поисковый сайт Яндекса имеет название “Яндекс”. Для других сайтов указываются домены, зарегистрированные в Яндекс Директе, например “mail.ru”, “nigma.ru”. | Нет || || `StatGoals` | Идентификатор цели Яндекс Метрики (указывается как элемент массива). Не допускается указывать более одного идентификатора. Если не задан, то показатели из Яндекс Метрики в отчете содержат агрегированные данные по всем целям. Список целей можно получить с помощью метода [GetStatGoals (Live)](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/GetStatGoals.md). | Нет || || `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. Фильтрация по типу операционной системы доступна только для кампаний с типом “Реклама мобильных приложений”“Ads for mobile apps”. | Нет || || `CarrierType` | Отбирать записи о показах объявлений по указанному типу связи. В массиве могут присутствовать следующие значения: CELLULAR (мобильная связь), STATIONARY (wi-fi), CARRIER_TYPE_UNKNOWN. Фильтрация по типу связи доступна только для кампаний с типом “Реклама мобильных приложений”“Ads for mobile apps”. | Нет || |# ## Результирующие данные {#output} Метод возвращает идентификатор будущего отчета, как показано в следующем примере. ```javascript { "data": 137456 } ``` ## Примеры входных данных {#example} ## Python ```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 ```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 ```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 } ``` ## Пример отчета {#example-report} Ниже показан пример отчета в формате XML. ```xml 1234 1234567 2013-05-01 2013-05-31 ``` Ниже приведено описание элементов отчета. #| || **Элемент/атрибут** | **Описание** | **Условие вывода** || || **Элемент 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 | Идентификатор [ретаргетинга](https://yandex.ru/dev/direct/doc/dg-v4/concepts/retargeting.html#ret-params) в отчете. Существует только внутри отчета и не совпадает с идентификатором ретаргетинга в Директе. Служит для нормализации данных в отчете и связывает элементы `phrase` и `row`. || || value | Текст фразы, или номер рубрики Яндекс Каталога, или описание ретаргетинга в отчете. || || **Элемент stat** || || row | Статистика по фразе за один день отчетного периода. || || sum | Стоимость кликов, списанная с баланса кампании. || || shows | Количество показов. || || clicks | Количество кликов. || || 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](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/CreateNewReport.md#NewReportInfo-GroupByDate) имеет значение “week” или “month”, указывается первая дата недели или месяца соответственно. | В массиве [GroupByColumns](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/CreateNewReport.md#NewReportInfo-GroupByColumns) присутствует значение “clDate”. || || sum_search | Стоимость кликов на поиске. | Входной параметр [PageType](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/CreateNewReport.md#NewReportFilterInfo-PageType) не задан или имеет значение “all”. || || sum_context | Стоимость кликов в Рекламной сети Яндекса. || || shows_search | Количество показов на поиске. || || shows_context | Количество показов в Рекламной сети Яндекса. || || clicks_search | Количество кликов на поиске. || || clicks_context | Количество кликов в Рекламной сети Яндекса. || || regionID | Идентификатор региона показов. | В массиве [GroupByColumns](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/CreateNewReport.md#NewReportInfo-GroupByColumns) присутствует значение “clGeo”. || || placeName | Название площадки показов. | В массиве [GroupByColumns](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/CreateNewReport.md#NewReportInfo-GroupByColumns) присутствует значение “clPage”. || || placeType | Тип площадки показов: “search” — поисковая площадка (включая поиск Яндекса и поисковые площадки в Рекламной сети Яндекса), “context” — сайт в Рекламной сети Яндекса. || || goal_id | Идентификатор [цели](https://yandex.ru/support/metrika/general/goals.xml)[цели](https://yandex.com/support/metrica/general/goals.xml) в Яндекс Метрике, если он был передан во входном параметре `StatGoals`. 0 — если идентификатор не был передан. В этом случае остальные показатели из Яндекс Метрики содержат агрегированные данные по всем целям. | В массиве [GroupByColumns](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/CreateNewReport.md#NewReportInfo-GroupByColumns) присутствует значение “clStatGoals”. || || goal_conversion | Доля целевых визитов в общем числе визитов, в процентах. || || goal_cost | Средняя цена целевого визита: отношение выручки к количеству целевых визитов. || || session_depth | Глубина просмотра сайта. || || goal_conversions_num | Количество целевых визитов (конверсий). | В массиве [GroupByColumns](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/CreateNewReport.md#NewReportInfo-GroupByColumns) присутствует значение “clGoalConversionsNum”. || || position_type | Блок показа объявления: “premium” — спецразмещение, “other” — другие блоки. | В массиве [GroupByColumns](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/CreateNewReport.md#NewReportInfo-GroupByColumns) присутствует значение “clPositionType”. || || stat_type | Тип показа объявления: с изображением или без. Возможные значения: Image/Text. | В массиве [GroupByColumns](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/CreateNewReport.md#NewReportInfo-GroupByColumns) присутствует значение “clImage”. || || shows_average_position | Средняя позиция показа объявления. При расчете учитываются только показы на первой странице результатов поиска Яндекса. Наивысшая позиция имеет номер 1. | В массиве [GroupByColumns](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/CreateNewReport.md#NewReportInfo-GroupByColumns) присутствует значение “clAveragePosition”. || || clicks_average_position | Средняя позиция, на которой произошел клик по объявлению. При расчете учитываются только клики на первой странице результатов поиска Яндекса. || || **Примечания** || || 1. Значения параметров `sum`, `shows`, `clicks` зависят от входного параметра [PageType](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/CreateNewReport.md#NewReportFilterInfo-PageType): - при значении “all” или отсутствии `PageType` приводятся суммарные данные по поиску и Рекламной сети Яндекса. При этом данные отдельно по поиску и отдельно по Рекламной сети приводятся в параметрах `sum_search`, `shows_search`, `clicks_search`, `sum_context`, `shows_context`, `clicks_context`); - при значении “search” приводятся данные по поиску и поисковым площадкам в Рекламной сети Яндекса; - при значении “context” приводятся данные по сайтам в Рекламной сети Яндекса, кроме поисковых площадок. || |#