GetBannerPhrasesFilter (Live)
Возвращает информацию о фразах и позволяет ограничить состав возвращаемых данных.
Новое в версии Live 4
Добавлен результирующий параметр StatusPaused.
Добавлены результирующие параметры ContextClicks и ContextShows.
Добавлен входной параметр Currrency и результирующий параметр Currency (см. также раздел Real currencies instead of Yandex units).
Добавлен результирующий параметр AdGroupID.
Добавлен результирующий параметр AuctionBids.
Ограничения
Получение фраз из архивных кампаний недоступно.
Alert
Метод поддерживает только текстово-графические объявления. Для работы с ключевыми фразами объявлений всех типов используйте сервис {#T} API версии 5.
Входные данные
Ниже показана структура входных данных в формате JSON.
{
"method": "GetBannerPhrasesFilter",
"param": {
/* BannerPhrasesFilterRequestInfo */
"BannerIDS": [
(long)
...
],
"FieldsNames": [
(string)
...
],
"ConsiderTimeTarget": (string),
"RequestPrices": (string),
"Currency": (string)
}
}
Ниже приведено описание параметров.
|
Параметр |
Описание |
Требуется |
|
Объект BannerPhrasesFilterRequestInfo |
||
|
|
Массив идентификаторов объявлений (не более 1000). |
Да |
|
|
Массив, содержащий названия параметров, возвращаемых в ответе. Если не задан, возвращаются все предусмотренные параметры. Всегда возвращаются параметры |
Нет |
|
|
Возвращать статистику и цены — Yes/No. Предустановленное значение Yes. Статистика и цены возвращаются в параметрах |
Нет |
|
|
Рассчитывать цены позиций показа без учета ставок в остановленных объявлениях конкурентов (остановлены в соответствии с расписанием), — Yes/No. Предустановленное значение — No (учитываются все объявления). |
Нет |
|
|
Валюта, в которой должны быть выражены ставки в ответе. Возможные значения: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN. Значение должно совпадать с валютой кампании. Если параметр отсутствует или равен NULL, подразумеваются условные единицы (у. е.). В этом случае, если кампания ведется в реальной валюте, возвращаемые значения конвертируются из валюты кампании в у. е. (см. раздел Real currencies instead of Yandex units). Если значение отлично от NULL и не совпадает с валютой кампании (одной из кампаний), возвращается ошибка с кодом 245. |
Нет |
Результирующие данные
Метод возвращает массив объектов BannerPhraseInfo с информацией о фразах. Ниже показана структура результирующих данных в формате JSON.
Note
Следующие параметры есть в WSDL, но возвращаются только в ответе метода GetForecast: FirstPlaceClicks: (int), PremiumClicks: (int), CTR: (float), FirstPlaceCTR: (float), PremiumCTR: (float)
{
"data": [
{ /* BannerPhraseInfo */
"BannerID": (long),
"CampaignID": (int),
"AdGroupID": (long),
"PhraseID": (long),
"Phrase": (string),
"IsRubric": (string),
"Price": (float),
"ContextPrice": (float),
"AutoBroker": (string),
"UserParams": {
/* PhraseUserParams */
"Param1": (string),
"Param2": (string)
}
"StatusPhraseModerate": (string),
"AutoBudgetPriority": (string),
"Clicks": (int),
"Shows": (int),
"ContextClicks": (int),
"ContextShows": (int),
"Min": (float),
"Max": (float),
"PremiumMin": (float),
"PremiumMax": (float),
"LowCTRWarning": (string),
"LowCTR": (string),
"ContextLowCTR": (string),
"Coverage": [
{ /* CoverageInfo */
"Probability": (float),
"Price": (float)
}
...
],
"ContextCoverage": [
{ /* CoverageInfo */
"Probability": (float),
"Price": (float)
}
...
],
"Prices": [
(float)
...
],
"CurrentOnSearch": (float),
"MinPrice": (float),
"StatusPaused": (string),
"Currency": (string),
"AuctionBids": [
{ /* PhraseAuctionBids */
"Position": (string),
"Bid": (float),
"Price": (float)
}
...
]
}
...
]
}
Ниже приведено описание параметров.
|
Параметр |
Описание |
|
Объект BannerPhraseInfo |
|
|
|
Идентификатор объявления. |
|
|
Идентификатор кампании. |
|
|
Идентификатор группы объявлений. |
|
|
Идентификатор фразы. |
|
|
Ключевая фраза. Может содержать минус-слова, которые указывают со знаком минус перед словом, например [молния -гром -дождь]. Общие для нескольких фраз минус-слова предпочтительно задавать в параметре группы объявлений Длина ключевой фразы — не более 4096 символов. Оператор “!” перед минус-словом не учитывается в длине фразы (последовательность “-!” считается как один символ). Не более 7 слов во фразе, без учета стоп-слов и минус-слов. Каждое слово и минус-слово — не более 35 символов, без учета минуса перед минус-словом. |
|
|
Признак того, что фраза является рубрикой Яндекс Каталога. Всегда содержит значение No. |
|
|
Ставка на поиске Яндекса (в валюте, указанной в параметре |
|
Стратегия на поиске. Ниже перечислены возможные значения.
Стратегии с ручным управлением ставками на поиске:
Автоматические стратегии на поиске:
|
](* |
|
-Стратегия-на-поиске.-Ниже-перечислены-возможные-значения.----ShowsDisabled-—-выключить-показ-объявлений-на-поиске.-Это-необходимо-для-использования-автоматической-стратегии-в-Рекламной-сети-Яндекса.-Показ-на-поиске-невозможно-выключить,-если-для-Рекламной-сети-применяется-стратегия-Default.--Стратегии-с-ручным-управлением-ставками-на-поиске:----HighestPosition-—-стратегия-“Наивысшая-доступная-позиция”“Highest-available-position”;---LowestCost-—-стратегия-“Показ-в-блоке-по-минимальной-цене”“Cheapest-position-in-ad-block”;---LowestCostPremium-—-стратегия-“Показ-в-блоке-по-минимальной-цене”“Cheapest-position-in-ad-block”,-но-объявления-показываются-только-в-спецразмещении;---LowestCostGuarantee-—-стратегия-“Показ-под-результатами-поиска”“Impressions-below-search-results”-(в-нижнем-блоке-по-наименьшей-цене);---RightBlockHighest-—-стратегия-“Показ-под-результатами-поиска”“Impressions-below-search-results”-(в-нижнем-блоке-на-наивысшей-позиции,-доступной-при-указанной-ставке).--Автоматические-стратегии-на-поиске:----WeeklyBudget-—-стратегия-“Недельный-бюджет:-максимум-кликов”“Weekly-budget:-maximum-clicks”-(обязательный-параметр- |
) с ручным управлением ставками. |
|
|
Ставка в Рекламной сети Яндекса (в валюте, указанной в параметре Параметр доступен для изменения в следующих случаях:
|
|
|
Признак включенного автоброкера. Всегда содержит значение Yes. |
|
|
Объект |
|
|
Результат проверки фразы:
|
|
|
Приоритет фразы при использовании автоматических стратегий. Возможные значения:
|
|
|
Количество кликов по всем объявлениям группы, показанным на поиске по данной фразе. Рассчитывается за 28 дней от текущей даты. Для расчета отбираются дни, в течение которых был хотя бы один клик по объявлению. |
|
|
Количество показов всех объявлений группы по данной фразе на поиске. Рассчитывается за 28 дней от текущей даты. Для расчета отбираются дни, в течение которых был хотя бы один показ объявления по данной фразе. |
|
|
Количество кликов по всем объявлениям группы, показанным в Рекламной сети Яндекса по данной фразе. Рассчитывается за 28 дней от текущей даты. Для расчета отбираются дни, в течение которых был хотя бы один клик по объявлению. |
|
|
Количество показов всех объявлений группы по данной фразе в Рекламной сети Яндекса. Рассчитывается за 28 дней от текущей даты. Для расчета отбираются дни, в течение которых был хотя бы один показ объявления по данной фразе. |
|
|
Цена (в валюте, указанной в параметре |
|
|
Цена (в валюте, указанной в параметре |
|
|
Цена (в валюте, указанной в параметре |
|
|
Цена (в валюте, указанной в параметре |
|
|
Фраза имеет низкий CTR и может быть вскоре отключена — Yes/No. Alert Параметр утратил актуальность для новых фраз, поскольку фразы больше не отключаются за низкий CTR. |
|
|
Фраза отключена на поиске за низкий CTR — Yes/No. Alert Параметр утратил актуальность для новых фраз, поскольку фразы больше не отключаются за низкий CTR. |
|
|
Фраза отключена на сайтах Рекламной сети Яндекса за низкий CTR — Yes/No. Alert Параметр утратил актуальность для новых фраз, поскольку фразы больше не отключаются за низкий CTR. |
|
|
Массив объектов Alert Параметр утратил актуальность, использовать его для подбора ставок не следует. |
|
|
Массив объектов Параметр полезен для подбора ставок к фразам. |
|
|
Массив минимальных ставок за все позиции в спецразмещении и в блоке гарантированных показов (в валюте, указанной в параметре |
|
|
Конечная цена клика c учетом автоброкера (в валюте, указанной в параметре Если по фразе не осуществляется показ объявления на поиске или фраза отключена на поиске за низкий CTR, в параметре возвращается значение NULL. |
|
|
Минимальная цена, назначаемая индивидуально для каждого рекламодателя (в валюте, указанной в параметре |
|
|
Показы по фразе остановлены — Yes/No. Останавливать и возобновлять показы можно методом Keyword (Live). |
|
|
Валюта, в которой выражены ставки. Возможные значения: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN. Если параметр отсутствует или равен NULL, подразумеваются условные единицы (у. е.). |
|
|
Массив объектов |
|
Объект CoverageInfo |
|
|
|
Частота показа при ставке из параметра В массиве |
|
|
Ставка (в валюте, указанной в параметре |
|
Объект PhraseUserParams |
|
|
|
Значение подстановочной переменной |
|
|
Значение подстановочной переменной |
|
Объект PhraseAuctionBids |
|
|
|
Позиция показа: P_mn_, где
Например, P12 — второе место в спецразмещении, P21 — первое место в блоке гарантированных показов. |
|
|
Минимальная ставка за указанную позицию (в валюте, указанной в параметре |
|
|
Списываемая цена для указанной позиции (в валюте, указанной в параметре |
|
Примечания |
|
|
Примеры входных данных
Python
{
'BannerIDS': [20155899],
'FieldsNames': ['Phrase','Price','Phrase','MinPrice','Clicks'],
'RequestPrices': 'Yes',
'ConsiderTimeTarget': 'Yes'
}
PHP
array(
'BannerIDS' => array(20155899),
'FieldsNames' => array('Phrase','Price','Phrase','MinPrice','Clicks'),
'RequestPrices' => 'Yes',
'ConsiderTimeTarget' ='Yes'
)
Perl
{
'BannerIDS' => [20155899],
'FieldsNames' => ['Phrase','Price','Phrase','MinPrice','Clicks'],
'RequestPrices' => 'Yes',
'ConsiderTimeTarget' ='Yes'
}