GetBannersStat (Live)

Возвращает статистику указанной кампании за период не более семи дней.

Внимание.

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

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

Ограничения

Для одной кампании возможно не более 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.

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

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

{
   "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.
    Примечание. Для получения значений дохода и рентабельности необходимо, чтобы:
    • на сайте был установлен счетчик Яндекс.Метрики;
    • счетчик был привязан к рекламной кампании в Директе: необходимо указать номер счетчика в параметре кампании AdditionalMetrikaCounters;
    • для счетчика были настроены цели;
    • код счетчика передавал стоимость заказа.
Нет
Limit

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

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

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

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

Если задан параметр Limit
OrderBy

Названия полей, по которым сортируются записи в отчете. Возможные значения: clDate, clPhrase, clBanner, clImage.

Нет
Currency

Валюта, в которой должны быть выражены суммы в ответе.

Возможные значения: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN. Значение должно совпадать с валютой кампании, в противном случае возвращается ошибка с кодом 245.

Для кампаний в у. е. не указывайте параметр или передайте NULL.

Для кампаний в реальной валюте
IncludeVAT

Учитывать НДС для стоимости кликов в валюте — Yes/No. При значении Yes суммы в отчете будут включать НДС. Если не задано, подразумевается Yes.

Если параметр Currency не задан, то параметр IncludeVAT игнорируется.

Нет
IncludeDiscount

Учитывать скидку для стоимости кликов в валюте — Yes/No.

При значении Yes в отчете будут приведены суммы за вычетом скидки (то есть суммы, фактически списанные с баланса кампании). При значении No в отчете будут приведены суммы до применения скидки. Если не задано, подразумевается Yes.

Примечание. Для кампаний, которые ведутся в валюте, скидка применяется в момент списания стоимости клика.

Если параметр Currency не задан, то используется значение No.

Нет

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

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

{
   "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 — для дополнительных релевантных фраз.

Примечание. Рекомендуется выполнять группировку по PhraseID на стороне приложения, так как в некоторых случаях ответ метода может содержать в массиве Stat несколько объектов с одинаковым значением PhraseID.
RubricID

Идентификатор рубрики Яндекс.Каталога.

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

RetargetingID

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

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

WebpageID
Идентификатор источника данных для генерации динамических объявлений:
  • идентификатор условия нацеливания для динамических объявлений, если источником данных являются страницы сайта;

  • идентификатор фильтра, если источником данных является фид — файл с товарными предложениями. Управление фильтрами в настоящее время доступно только в веб-интерфейсе.

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

Phrase

Текст фразы, или название рубрики Яндекс.Каталога, или название условия ретаргетинга, или название интереса к категории мобильных приложений, или название условия нацеливания для динамических объявлений, или название фильтра, или значение «Автоматически добавленные фразы» (для дополнительных релевантных фраз).

Выводится в отчет, если во входном параметре GroupByColumns указано значение «clPhrase».
Sum

Стоимость кликов суммарно на поиске и в Рекламной сети Яндекса (в валюте, указанной во входном параметре Currency).

См. Примечания ниже.

SumSearch

Стоимость кликов на поиске (в валюте, указанной во входном параметре Currency).

См. Примечания ниже.

SumContext

Стоимость кликов в Рекламной сети Яндекса (в валюте, указанной во входном параметре Currency).

См. Примечания ниже.

Clicks

Клики суммарно на поиске и в Рекламной сети Яндекса.

ClicksSearch

Клики на поиске.

ClicksContext

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

Shows

Показы суммарно на поиске и в Рекламной сети Яндекса.

ShowsSearch

Показы на поиске.

ShowsContext

Показы в Рекламной сети Яндекса.

StatType

Формат показа объявления. Возможные значения: Text (текстовый), Image (с изображением), Video (с видео).

Выводится в отчет, если во входном параметре GroupByColumns указано значение «clImage».

DeviceType

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

Выводится в отчет, если во входном параметре GroupByColumns указано значение «clDeviceType».

ShowsAveragePosition

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

Выводится в отчет, если во входном параметре GroupByColumns указано значение «clAveragePosition».

ClicksAveragePosition

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

Выводится в отчет, если во входном параметре GroupByColumns указано значение «clAveragePosition».

Revenue Доход (до двух знаков после запятой) — сумма показателей стоимости заказа, переданных счетчиком Яндекс.Метрики.
ROI

Рентабельность инвестиций в рекламу (до двух знаков после запятой):

Примечания
  1. Стоимость кликов, выраженная в валюте, может включать или не включать НДС в зависимости от значения входного параметра IncludeVAT.

    Стоимость кликов с учетом НДС = Стоимость кликов без учета НДС × (1 + Ставка НДС)

  2. Стоимость кликов, выраженная в валюте, может учитывать или не учитывать скидку в зависимости от значения входного параметра IncludeDiscount.

    Стоимость кликов до применения скидки = Стоимость кликов, фактически списанная с баланса / (1 – Cкидка)

    Примечание. Для кампаний, которые ведутся в валюте, скидка применяется в момент списания стоимости клика.
  3. Если кампания велась в у. е., суммы возвращаются «как есть», без каких-либо преобразований.

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

Python

{
   'CampaignID': 1234567,
   'StartDate': '2013-02-15',
   'EndDate': '2013-02-21',
   'GroupByColumns': ['clDate', 'clPhrase'],
   'Limit': 10,
   'Offset': 0,
   'OrderBy': ['clDate', 'clBanner']
}

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

{
   'CampaignID' => 1234567,
   'StartDate' => '2013-02-15',
   'EndDate' => '2013-02-21',
   'GroupByColumns' => ['clDate', 'clPhrase'],
   'Limit' => 10,
   'Offset' => 0,
   'OrderBy' => ['clDate', 'clBanner']
}