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 | Начальная дата отчетного периода, | Да |
EndDate | Конечная дата отчетного периода, | Да |
GroupByColumns | Названия полей, выводимых в отчет дополнительно к статистическим данным. Возможные значения:
| Нет |
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 | Начальная дата отчетного периода, | Да |
EndDate | Конечная дата отчетного периода, | Да |
GroupByColumns | Названия полей, выводимых в отчет дополнительно к статистическим данным. Возможные значения:
| Нет |
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 | Начальная дата отчетного периода, |
EndDate | Конечная дата отчетного периода, |
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 | Рентабельность инвестиций в рекламу (до двух знаков после запятой): |
Примечания | |
|
Параметр | Описание |
Объект GetBannersStatResponse | |
---|---|
CampaignID | Идентификатор кампании. |
StartDate | Начальная дата отчетного периода, |
EndDate | Конечная дата отчетного периода, |
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 | Рентабельность инвестиций в рекламу (до двух знаков после запятой): |
Примечания | |
|
Примеры входных данных
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']
}