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.	Нет


_{Объект 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`	Рентабельность инвестиций в рекламу (до двух знаков после запятой):
Примечания
Стоимость кликов, выраженная в валюте, может включать или не включать НДС в зависимости от значения входного параметра IncludeVAT. Стоимость кликов с учетом НДС = Стоимость кликов без учета НДС × (1 + Ставка НДС) Стоимость кликов, выраженная в валюте, может учитывать или не учитывать скидку в зависимости от значения входного параметра IncludeDiscount. Стоимость кликов до применения скидки = Стоимость кликов, фактически списанная с баланса / (1 – Cкидка) Примечание. Для кампаний, которые ведутся в валюте, скидка применяется в момент списания стоимости клика. Если кампания велась в у. е., суммы возвращаются «как есть», без каких-либо преобразований.


_{Объект 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`	Рентабельность инвестиций в рекламу (до двух знаков после запятой):
Примечания
Стоимость кликов, выраженная в валюте, может включать или не включать НДС в зависимости от значения входного параметра IncludeVAT. Стоимость кликов с учетом НДС = Стоимость кликов без учета НДС × (1 + Ставка НДС) Стоимость кликов, выраженная в валюте, может учитывать или не учитывать скидку в зависимости от значения входного параметра IncludeDiscount. Стоимость кликов до применения скидки = Стоимость кликов, фактически списанная с баланса / (1 – Cкидка) Примечание. Для кампаний, которые ведутся в валюте, скидка применяется в момент списания стоимости клика. Если кампания велась в у. е., суммы возвращаются «как есть», без каких-либо преобразований.

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

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']
}

Была ли статья полезна?

Расскажите, что вам не понравилось в статье:

GetBalance (Live) (disabled)

GetSummaryStat (disabled)

GetBalance (Live) (disabled)

GetSummaryStat (disabled)