--- metadata: - name: generator content: Diplodoc Platform v5.50.2 alternate: - https://yandex.com/dev/direct/doc/dg-v4/en/live/GetBannersStat.md - https://yandex.com/dev/direct/doc/dg-v4/ru/live/GetBannersStat.md --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.com/dev/direct/doc/dg-v4/ru/llms.txt # GetBannersStat (Live) Возвращает статистику указанной кампании за период не более семи дней. ## Ограничения {#restrictions} Для одной кампании возможно не более 300 вызовов метода в сутки. Статистика доступна за последние три года от текущего месяца: например, 15 сентября 2016 года можно получить данные начиная с 1 сентября 2013 года. Данные по средней позиции объявления доступны начиная с 01.11.2014. Данные по типу устройства доступны начиная с 01.11.2014. ## Новое в версии Live 4 Входной параметр Currency стал обязательным для кампаний в реальной валюте. Добавлен результирующий параметр RetargetingID. Добавлен результирующий параметр StatType. Добавлены входные параметры Currency, IncludeVAT, IncludeDiscount. Добавлен результирующий параметр DeviceType. Для входного параметра GroupByColumns добавлено значение clDeviceType. Добавлены результирующие параметры ShowsAveragePosition и ClicksAveragePosition. Для входного параметра GroupByColumns добавлено значение clAveragePosition. Добавлены результирующие параметры Revenue и ROI. Для входного параметра GroupByColumns добавлено значение clROI. Добавлен результирующий параметр WebpageID. Для результирующего параметра StatType добавлено значение Video. ## Входные данные {#input} Ниже показана структура входных данных в формате JSON. ```javascript { "method": "GetBannersStat", "param": { /* NewReportInfo */ "CampaignID": (int), "StartDate": (date), "EndDate": (date), "GroupByColumns": [ (string) ... ], "Limit": (int), "Offset": (int), "OrderBy": [ (string) ... ], "Currency": (string), "IncludeVAT": (string), "IncludeDiscount": (string) } } ``` Ниже приведено описание параметров. #| || **Параметр** | **Описание** | **Требуется** || || **Объект NewReportInfo** || || `CampaignID` | Идентификатор кампании, для которой формируется отчет. | Да || || `StartDate` | Начальная дата отчетного периода, `YYYY-MM-DD`. Период не должен превышать семь дней. | Да || || `EndDate` | Конечная дата отчетного периода, `YYYY-MM-DD`. Период не должен превышать семь дней. | Да || || `GroupByColumns` | Названия полей, выводимых в отчет дополнительно к статистическим данным. Возможные значения: - clDate — дата сбора статистики `statDate`. - clPhrase — идентификатор фразы, или рубрики Яндекс Каталога, или ретаргетинга, или источника данных для генерации динамических объявлений. - clBanner — идентификатор объявления. Значение clBanner не требуется указывать, поскольку оно автоматически добавляется к входным данным, чтобы идентификаторы объявлений всегда выводились в отчет. Значение может использоваться в параметре `OrderBy` для сортировки строк в отчете. - clImage — формат показа объявления: с изображением, с видео или текстовый. - clDeviceType — тип устройства, на котором показано объявление. - clAveragePosition — средняя позиция показов объявления `ShowsAveragePosition` и средняя позиция кликов по объявлению `СlicksAveragePosition`; - clROI — доход `Revenue` и рентабельность `ROI`. {% note info %} Для получения значений дохода и рентабельности необходимо, чтобы: - на сайте был установлен счетчик Яндекс Метрики; - счетчик был привязан к рекламной кампании в Директе: необходимо указать номер счетчика в параметре кампании AdditionalMetrikaCounters; - для счетчика были настроены [цели](https://yandex.ru/support/metrika/general/goals.html)[цели](https://yandex.com/support/metrica/general/goals.html); - код счетчика передавал [стоимость заказа](https://yandex.ru/support/metrika/reports/e-commerce.html)[стоимость заказа](https://yandex.com/support/metrica/reports/e-commerce.html). {% endnote %} | Нет || || `Limit` | Количество записей, отбираемых из базы данных в отчет. Если не указано, выбираются все записи. Параметры `Limit` и `Offset` служат для постраничной выборки записей. | Нет || || `Offset` | Номер записи, с которой начинается выборка. Если не указано, подразумевается 0. Параметры `Limit` и `Offset` служат для постраничной выборки записей. | Если задан параметр `Limit` || || `OrderBy` | Названия полей, по которым сортируются записи в отчете. Возможные значения: clDate, clPhrase, clBanner, clImage. | Нет || || `Currency` | Валюта, в которой должны быть выражены суммы в ответе. Возможные значения: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN. Значение должно совпадать с валютой кампании, в противном случае возвращается ошибка с кодом [245](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/ErrorCodes.md#BadCurrency). Для кампаний в у. е. не указывайте параметр или передайте NULL. | Для кампаний в реальной валюте || || `IncludeVAT` | Учитывать НДС для стоимости кликов в валюте — Yes/No. При значении Yes суммы в отчете будут включать НДС. Если не задано, подразумевается Yes. Если параметр `Currency` не задан, то параметр `IncludeVAT` игнорируется. | Нет || || `IncludeDiscount` | Учитывать скидку для стоимости кликов в валюте — Yes/No. При значении Yes в отчете будут приведены суммы за вычетом скидки (то есть суммы, фактически списанные с баланса кампании). При значении No в отчете будут приведены суммы до применения скидки. Если не задано, подразумевается Yes. {% note info %} Для кампаний, которые ведутся в валюте, скидка применяется в момент списания стоимости клика. {% endnote %} Если параметр `Currency` не задан, то используется значение No. | Нет || |# ## Результирующие данные {#output} Ниже показана структура результирующих данных в формате JSON. ```javascript { "data": { /* GetBannersStatResponse */ "CampaignID": (int), "StartDate": (date), "EndDate": (date), "Stat": [ { /* BannersStatItem */ "StatDate": (date), "BannerID": (long), "PhraseID": (long), "RubricID": (int), "RetargetingID": (int), "WebpageID": (int), "Phrase": (string), "Sum": (float), "SumSearch": (float), "SumContext": (float), "Clicks": (int), "ClicksSearch": (int), "ClicksContext": (int), "Shows": (int), "ShowsSearch": (int), "ShowsContext": (int), "StatType": (string), "DeviceType": (string), "ShowsAveragePosition": (float), "ClicksAveragePosition": (float), "Revenue": (float), "ROI": (float) } ... ] } } ``` Ниже приведено описание параметров. #| || **Параметр** | **Описание** || || **Объект GetBannersStatResponse** || || `CampaignID` | Идентификатор кампании. || || `StartDate` | Начальная дата отчетного периода, `YYYY-MM-DD`. || || `EndDate` | Конечная дата отчетного периода, `YYYY-MM-DD`. || || `Stat` | Массив объектов `BannersStatItem`. Каждый объект содержит статистику по одной фразе за один день отчетного периода. || || **Объект BannersStatItem** || || `StatDate` | Дата, за которую приведена статистика. Выводится в отчет, если во входном параметре `GroupByColumns` указано значение “clDate”. || || `BannerID` | Идентификатор объявления. || || `PhraseID` | Идентификатор фразы или автотаргетинга. Выводится в отчет, если во входном параметре `GroupByColumns` указано значение “clPhrase” и запись содержит информацию о фразе или рубрике Яндекс Каталога (но не о ретаргетинге). NULL — для [дополнительных релевантных фраз](https://yandex.ru/support/direct/keywords/related-keywords.html)[дополнительных релевантных фраз](https://yandex.com/support/direct/keywords/related-keywords.html). {% note info %} Рекомендуется выполнять группировку по `PhraseID` на стороне приложения, так как в некоторых случаях ответ метода может содержать в массиве `Stat` несколько объектов с одинаковым значением `PhraseID`. {% endnote %} || || `RubricID` | Идентификатор рубрики Яндекс Каталога. Выводится в отчет, если во входном параметре `GroupByColumns` указано значение “clPhrase” и запись содержит информацию о рубрике Яндекс Каталога. || || `RetargetingID` | Идентификатор [ретаргетинга](https://yandex.com/dev/direct/doc/dg-v4/ru/concepts/retargeting.md#ret-params). Выводится в отчет, если во входном параметре `GroupByColumns` указано значение “clPhrase” и запись содержит информацию о ретаргетинге. || || `WebpageID` | Идентификатор источника данных для генерации динамических объявлений: - идентификатор [условия нацеливания](https://yandex.ru/dev/direct/doc/dg/objects/dynamictextadtarget.md) для динамических объявлений, если источником данных являются страницы сайта; - идентификатор фильтра, если источником данных является фид — файл с товарными предложениями. Управление фильтрами в настоящее время доступно только в веб-интерфейсе. Выводится в отчет, если во входном параметре `GroupByColumns` указано значение “clPhrase” и запись содержит информацию об источнике данных для генерации динамических объявлений. || || `Phrase` | Текст фразы, или название рубрики Яндекс Каталога, или название [условия ретаргетинга](https://yandex.com/dev/direct/doc/dg-v4/ru/concepts/retargeting.md#ret-condition), или название интереса к категории мобильных приложений, или название условия нацеливания для динамических объявлений, или название фильтра, или значение “Автоматически добавленные фразы” (для [дополнительных релевантных фраз](https://yandex.ru/support/direct/keywords/related-keywords.html)[дополнительных релевантных фраз](https://yandex.com/support/direct/keywords/related-keywords.html)). Выводится в отчет, если во входном параметре `GroupByColumns` указано значение “clPhrase”. || || `Sum` | Стоимость кликов суммарно на поиске и в Рекламной сети Яндекса (в валюте, указанной во входном параметре `Currency`). См. [Примечания](#recalc) ниже. || || `SumSearch` | Стоимость кликов на поиске (в валюте, указанной во входном параметре `Currency`). См. [Примечания](./#recalc) ниже. || || `SumContext` | Стоимость кликов в Рекламной сети Яндекса (в валюте, указанной во входном параметре `Currency`). См. [Примечания](./#recalc) ниже. || || `Clicks` | Клики суммарно на поиске и в Рекламной сети Яндекса. || || `ClicksSearch` | Клики на поиске. || || `ClicksContext` | Клики в Рекламной сети Яндекса. || || `Shows` | Показы суммарно на поиске и в Рекламной сети Яндекса. || || `ShowsSearch` | Показы на поиске. || || `ShowsContext` | Показы в Рекламной сети Яндекса. || || `StatType` | Формат показа объявления. Возможные значения: Text (текстовый), Image (с изображением), Video (с видео). Выводится в отчет, если во входном параметре `GroupByColumns` указано значение “clImage”. || || `DeviceType` | Тип устройства, на котором показано объявление. Возможные значения: desktop/mobile/tablet. Выводится в отчет, если во входном параметре `GroupByColumns` указано значение “clDeviceType”. || || `ShowsAveragePosition` | [Средняя позиция](https://yandex.ru/support/direct-tooltips/average-position.html)[Средняя позиция](https://yandex.com/support/direct-tooltips/average-position.html) показа объявления. При расчете учитываются только показы на первой странице результатов поиска Яндекса. Наивысшая позиция имеет номер 1. Выводится в отчет, если во входном параметре `GroupByColumns` указано значение “clAveragePosition”. || || `ClicksAveragePosition` | [Средняя позиция](https://yandex.ru/support/direct-tooltips/average-position.html)[Средняя позиция](https://yandex.com/support/direct-tooltips/average-position.html), на которой произошел клик по объявлению. При расчете учитываются только клики на первой странице результатов поиска Яндекса. Выводится в отчет, если во входном параметре `GroupByColumns` указано значение “clAveragePosition”. || || `Revenue` | Доход (до двух знаков после запятой) — сумма показателей стоимости заказа, переданных счетчиком Яндекс Метрики. || || `ROI` | Рентабельность инвестиций в рекламу (до двух знаков после запятой): ![](../_assets/roi-formula.png) || || **Примечания** || || 1. {% include [example-report-stat-note-li-2](../_includes/live/CreateNewReport/id-example-report/stat-note-li-2.md) %} 1. {% include [example-report-stat-note-li-3](../_includes/live/CreateNewReport/id-example-report/stat-note-li-3.md) %} 1. Если кампания велась в у. е., суммы возвращаются “как есть”, без каких-либо преобразований. || |# ## Примеры входных данных {#example} ## Python ```python { 'CampaignID': 1234567, 'StartDate': '2013-02-15', 'EndDate': '2013-02-21', 'GroupByColumns': ['clDate', 'clPhrase'], 'Limit': 10, 'Offset': 0, 'OrderBy': ['clDate', 'clBanner'] } ``` ## PHP ```php array( 'CampaignID' => 1234567, 'StartDate' => '2013-02-15', 'EndDate' => '2013-02-21', 'GroupByColumns' => array('clDate', 'clPhrase'), 'Limit' => 10, 'Offset' => 0, 'OrderBy' => array('clDate', 'clBanner') ) ``` ## Perl ```perl { 'CampaignID' => 1234567, 'StartDate' => '2013-02-15', 'EndDate' => '2013-02-21', 'GroupByColumns' => ['clDate', 'clPhrase'], 'Limit' => 10, 'Offset' => 0, 'OrderBy' => ['clDate', 'clBanner'] } ``` {% included (../_includes/live/CreateNewReport/id-example-report/stat-note-li-2.md) %} Стоимость кликов, выраженная в валюте, может включать или не включать НДС в зависимости от значения входного параметра [|| `IncludeVAT` | Учитывать НДС для стоимости кликов в валюте — Yes/No. При значении Yes суммы в отчете будут включать НДС. Если не задано, подразумевается Yes. Если параметр `Currency` не задан, то параметр `IncludeVAT` игнорируется. | Нет ||](*||-`IncludeVAT`-|-Учитывать-НДС-для-стоимости-кликов-в-валюте-—-Yes/No.-При-значении-Yes-суммы-в-отчете-будут-включать-НДС.-Если-не-задано,-подразумевается-Yes.--Если-параметр-`Currency`-не-задан,-то-параметр-`IncludeVAT`-игнорируется.-|-Нет-||). _Стоимость кликов с учетом НДС_ = _Стоимость кликов без учета НДС_ × (1 + _Ставка НДС_) {% endincluded %} {% included (../_includes/live/CreateNewReport/id-example-report/stat-note-li-3.md) %} Стоимость кликов, выраженная в валюте, может учитывать или не учитывать скидку в зависимости от значения входного параметра [|| `IncludeDiscount` | Учитывать скидку для стоимости кликов в валюте — Yes/No. При значении Yes в отчете будут приведены суммы за вычетом скидки (то есть суммы, фактически списанные с баланса кампании). При значении No в отчете будут приведены суммы до применения скидки. Если не задано, подразумевается Yes. {% note info %} Для кампаний, которые ведутся в валюте, скидка применяется в момент списания стоимости клика. {% endnote %} Если параметр `Currency` не задан, то используется значение No. | Нет ||](*||-`IncludeDiscount`-|-Учитывать-скидку-для-стоимости-кликов-в-валюте-—-Yes/No.--При-значении-Yes-в-отчете-будут-приведены-суммы-за-вычетом-скидки-(то-есть-суммы,-фактически-списанные-с-баланса-кампании).-При-значении-No-в-отчете-будут-приведены-суммы-до-применения-скидки.-Если-не-задано,-подразумевается-Yes.---{%-note-info-%}--Для-кампаний,-которые-ведутся-в-валюте,-скидка-применяется-в-момент-списания-стоимости-клика.--{%-endnote-%}---Если-параметр-`Currency`-не-задан,-то-используется-значение-No.-|-Нет-||). _Стоимость кликов до применения скидки_ = _Стоимость кликов, фактически списанная с баланса_ / (1 – _Cкидка_) {% note info %} Для кампаний, которые ведутся в валюте, скидка применяется в момент списания стоимости клика. {% endnote %} {% endincluded %}