GetBannerPhrasesFilter (Live)

Возвращает информацию о фразах и позволяет ограничить состав возвращаемых данных.

Внимание.

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

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

Новое в версии Live 4

Добавлен результирующий параметр StatusPaused.

Добавлены результирующие параметры ContextClicks и ContextShows.

Добавлен входной параметр Currrency и результирующий параметр Currency (см. также раздел Реальные валюты вместо у. е.).

Добавлен результирующий параметр AdGroupID.

Добавлен результирующий параметр AuctionBids.

Ограничения

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

Внимание. Метод поддерживает только текстово-графические объявления. Для работы с ключевыми фразами объявлений всех типов используйте сервис Keywords API версии 5.

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

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

{
   "method": "GetBannerPhrasesFilter",
   "param": {
      /* BannerPhrasesFilterRequestInfo */
      "BannerIDS": [
         (long)
         ...
      ],
      "FieldsNames": [
         (string)
         ...
      ],
      "ConsiderTimeTarget": (string),
      "RequestPrices": (string),
      "Currency": (string)
   }
}

Ниже приведено описание параметров.

Параметр Описание Требуется
Объект BannerPhrasesFilterRequestInfo
BannerIDS Массив идентификаторов объявлений (не более 1000). Да
FieldsNames

Массив, содержащий названия параметров, возвращаемых в ответе. Если не задан, возвращаются все предусмотренные параметры.

Всегда возвращаются параметры CampaignID, BannerID, PhraseID.

 Нет
RequestPrices

Возвращать статистику и цены — Yes/No. Предустановленное значение Yes.

Статистика и цены возвращаются в параметрах ContextPrice, Clicks, Shows, Min, Max, PremiumMin, PremiumMax, LowCTRWarning, LowCTR, ContextLowCTR, Coverage, ContextCoverage, Prices, CurrentOnSearch, MinPrice. Их названия можно указать в массиве FieldsNames.

 Нет
ConsiderTimeTarget

Рассчитывать цены позиций показа без учета ставок в остановленных объявлениях конкурентов (остановлены в соответствии с расписанием), — Yes/No. Предустановленное значение — No (учитываются все объявления).

 Нет
Currency

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

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

Если параметр отсутствует или равен NULL, подразумеваются условные единицы (у. е.). В этом случае, если кампания ведется в реальной валюте, возвращаемые значения конвертируются из валюты кампании в у. е. (см. раздел Реальные валюты вместо у. е.).

Если значение отлично от NULL и не совпадает с валютой кампании (одной из кампаний), возвращается ошибка с кодом 245.

 Нет
Параметр Описание Требуется
Объект BannerPhrasesFilterRequestInfo
BannerIDS Массив идентификаторов объявлений (не более 1000). Да
FieldsNames

Массив, содержащий названия параметров, возвращаемых в ответе. Если не задан, возвращаются все предусмотренные параметры.

Всегда возвращаются параметры CampaignID, BannerID, PhraseID.

 Нет
RequestPrices

Возвращать статистику и цены — Yes/No. Предустановленное значение Yes.

Статистика и цены возвращаются в параметрах ContextPrice, Clicks, Shows, Min, Max, PremiumMin, PremiumMax, LowCTRWarning, LowCTR, ContextLowCTR, Coverage, ContextCoverage, Prices, CurrentOnSearch, MinPrice. Их названия можно указать в массиве FieldsNames.

 Нет
ConsiderTimeTarget

Рассчитывать цены позиций показа без учета ставок в остановленных объявлениях конкурентов (остановлены в соответствии с расписанием), — Yes/No. Предустановленное значение — No (учитываются все объявления).

 Нет
Currency

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

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

Если параметр отсутствует или равен NULL, подразумеваются условные единицы (у. е.). В этом случае, если кампания ведется в реальной валюте, возвращаемые значения конвертируются из валюты кампании в у. е. (см. раздел Реальные валюты вместо у. е.).

Если значение отлично от NULL и не совпадает с валютой кампании (одной из кампаний), возвращается ошибка с кодом 245.

 Нет

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

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

{
   "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
BannerID

Идентификатор объявления.
CampaignID

Идентификатор кампании.
AdGroupID Идентификатор группы объявлений.
PhraseID

Идентификатор фразы.
Phrase

Ключевая фраза.

Может содержать минус-слова, которые указывают со знаком минус перед словом, например [молния -гром -дождь]. Общие для нескольких фраз минус-слова предпочтительно задавать в параметре группы объявлений MinusKeywords.

Длина ключевой фразы — не более 4096 символов. Оператор «!» перед минус-словом не учитывается в длине фразы (последовательность «-!» считается как один символ).

Не более 7 слов во фразе, без учета стоп-слов и минус-слов. Каждое слово и минус-слово — не более 35 символов, без учета минуса перед минус-словом.
IsRubric

Признак того, что фраза является рубрикой Яндекс Каталога. Всегда содержит значение No.
Price

Ставка на поиске Яндекса (в валюте, указанной в параметре Currency) 1 . Используется, только если для кампании выбрана стратегия с ручным управлением ставками.

ContextPrice

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

Параметр доступен для изменения в следующих случаях:

  1. Для Рекламной сети выбрана стратегия MaximumCoverage.

  2. Для Рекламной сети выбрана стратегия Default и фраза отключена на поиске за низкий CTR.

    Для новых фраз данное условие не актуально, поскольку фразы больше не отключаются за низкий CTR.
AutoBroker

Признак включенного автоброкера. Всегда содержит значение Yes.
UserParams

Объект PhraseUserParams. Содержит значения подстановочных переменных для формирования ссылки на сайт (см. раздел Ссылки на сайт).
StatusPhraseModerate

Результат проверки фразы:

  • New — фраза не проверена;
  • Yes — принята;
  • No — отклонена;
AutoBudgetPriority

Приоритет фразы при использовании автоматических стратегий. Возможные значения:

  • Low — низкий приоритет;
  • Medium — средний приоритет;
  • High — высокий приоритет.
Clicks

Количество кликов по всем объявлениям группы, показанным на поиске по данной фразе. Рассчитывается за 28 дней от текущей даты. Для расчета отбираются дни, в течение которых был хотя бы один клик по объявлению.
Shows

Количество показов всех объявлений группы по данной фразе на поиске. Рассчитывается за 28 дней от текущей даты. Для расчета отбираются дни, в течение которых был хотя бы один показ объявления по данной фразе.
ContextClicks

Количество кликов по всем объявлениям группы, показанным в Рекламной сети Яндекса по данной фразе. Рассчитывается за 28 дней от текущей даты. Для расчета отбираются дни, в течение которых был хотя бы один клик по объявлению.
ContextShows

Количество показов всех объявлений группы по данной фразе в Рекламной сети Яндекса. Рассчитывается за 28 дней от текущей даты. Для расчета отбираются дни, в течение которых был хотя бы один показ объявления по данной фразе.
Min Цена (в валюте, указанной в параметре Currency) 2 , обеспечивающая для большинства объявлений группы показ в блоке гарантированных показов.
Max Цена (в валюте, указанной в параметре Currency) 2 , обеспечивающая для большинства объявлений группы показ на первом месте в блоке гарантированных показов.
PremiumMin

Цена (в валюте, указанной в параметре Currency) 2 , обеспечивающая для большинства объявлений группы показ в спецразмещении.
PremiumMax Цена (в валюте, указанной в параметре Currency) 2 , обеспечивающая для большинства объявлений группы показ на первом месте в спецразмещении.
LowCTRWarning

Фраза имеет низкий CTR и может быть вскоре отключена — Yes/No.

Ограничение.

Параметр утратил актуальность для новых фраз, поскольку фразы больше не отключаются за низкий CTR.
LowCTR

Фраза отключена на поиске за низкий CTR — Yes/No.

Ограничение.

Параметр утратил актуальность для новых фраз, поскольку фразы больше не отключаются за низкий CTR.
ContextLowCTR

Фраза отключена на сайтах Рекламной сети Яндекса за низкий CTR — Yes/No.

Ограничение.

Параметр утратил актуальность для новых фраз, поскольку фразы больше не отключаются за низкий CTR.
Coverage

Массив объектов CoverageInfo, которые указывают прогнозируемый охват аудитории на поиске.

Ограничение.

Параметр утратил актуальность, использовать его для подбора ставок не следует.
ContextCoverage

Массив объектов CoverageInfo, которые указывают прогнозируемый охват аудитории в Рекламной сети Яндекса.

Параметр полезен для подбора ставок к фразам.
Prices

Массив минимальных ставок за все позиции в спецразмещении и в блоке гарантированных показов (в валюте, указанной в параметре Currency) 2 .
CurrentOnSearch

Конечная цена клика c учетом автоброкера (в валюте, указанной в параметре Currency) 2 .

Если по фразе не осуществляется показ объявления на поиске или фраза отключена на поиске за низкий CTR, в параметре возвращается значение NULL.
MinPrice

Минимальная цена, назначаемая индивидуально для каждого рекламодателя (в валюте, указанной в параметре Currency) 2 .

StatusPaused

Показы по фразе остановлены — Yes/No. Останавливать и возобновлять показы можно методом Keyword (Live).
Currency

Валюта, в которой выражены ставки.

Возможные значения: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN. Если параметр отсутствует или равен NULL, подразумеваются условные единицы (у. е.).
AuctionBids Массив объектов PhraseAuctionBids, содержащий результаты торгов по фразе: ставку за каждую позицию в спецразмещении и в нижнем блоке, а также списываемую цену для каждой позиции.
Объект CoverageInfo
Probability

Частота показа при ставке из параметра Price.

В массиве ContextCoverage указывается в процентах от 0 до 100. Используется для подбора ставок.
Price Ставка (в валюте, указанной в параметре Currency) 2 , для которой параметр Probability содержит частоту показа.
Объект PhraseUserParams
Param1

Значение подстановочной переменной {param1}. Не более 255 байт.
Param2

Значение подстановочной переменной {param2}. Не более 255 байт.
Объект PhraseAuctionBids
Position Позиция показа: Pmn, где
  • m — номер блока (1 — спецразмещение, 2 — блок гарантированных показов);
  • n — номер позиции в рамках блока.

Например, P12 — второе место в спецразмещении, P21 — первое место в блоке гарантированных показов.
Bid Минимальная ставка за указанную позицию (в валюте, указанной в параметре Currency) 2 .
Price Списываемая цена для указанной позиции (в валюте, указанной в параметре Currency) 2 .
Примечания

  1. Если возвращаемые ставки конвертируются из валюты кампании в у. е., то они округляются по математическим правилам с точностью до второго знака после запятой (для всех валют, в том числе тенге).

  2. Если возвращаемые параметры торгов (цены позиций показа и охвата аудитории, ставки конкурентов) конвертируются из валюты кампании в у. е., то они округляются вверх с точностью до шага торгов (0,01 у. е., см. также раздел Реальные валюты вместо у. е.).

  3. В редких случаях цены позиций показа и некоторые другие параметры, связанные с результатами аукциона, могут иметь значение NULL, что говорит об ошибке получения данных на стороне API. Рекомендуется повторить вызов метода через некоторое время.
Параметр Описание
Объект BannerPhraseInfo
BannerID

Идентификатор объявления.
CampaignID

Идентификатор кампании.
AdGroupID Идентификатор группы объявлений.
PhraseID

Идентификатор фразы.
Phrase

Ключевая фраза.

Может содержать минус-слова, которые указывают со знаком минус перед словом, например [молния -гром -дождь]. Общие для нескольких фраз минус-слова предпочтительно задавать в параметре группы объявлений MinusKeywords.

Длина ключевой фразы — не более 4096 символов. Оператор «!» перед минус-словом не учитывается в длине фразы (последовательность «-!» считается как один символ).

Не более 7 слов во фразе, без учета стоп-слов и минус-слов. Каждое слово и минус-слово — не более 35 символов, без учета минуса перед минус-словом.
IsRubric

Признак того, что фраза является рубрикой Яндекс Каталога. Всегда содержит значение No.
Price

Ставка на поиске Яндекса (в валюте, указанной в параметре Currency) 1 . Используется, только если для кампании выбрана стратегия с ручным управлением ставками.

ContextPrice

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

Параметр доступен для изменения в следующих случаях:

  1. Для Рекламной сети выбрана стратегия MaximumCoverage.

  2. Для Рекламной сети выбрана стратегия Default и фраза отключена на поиске за низкий CTR.

    Для новых фраз данное условие не актуально, поскольку фразы больше не отключаются за низкий CTR.
AutoBroker

Признак включенного автоброкера. Всегда содержит значение Yes.
UserParams

Объект PhraseUserParams. Содержит значения подстановочных переменных для формирования ссылки на сайт (см. раздел Ссылки на сайт).
StatusPhraseModerate

Результат проверки фразы:

  • New — фраза не проверена;
  • Yes — принята;
  • No — отклонена;
AutoBudgetPriority

Приоритет фразы при использовании автоматических стратегий. Возможные значения:

  • Low — низкий приоритет;
  • Medium — средний приоритет;
  • High — высокий приоритет.
Clicks

Количество кликов по всем объявлениям группы, показанным на поиске по данной фразе. Рассчитывается за 28 дней от текущей даты. Для расчета отбираются дни, в течение которых был хотя бы один клик по объявлению.
Shows

Количество показов всех объявлений группы по данной фразе на поиске. Рассчитывается за 28 дней от текущей даты. Для расчета отбираются дни, в течение которых был хотя бы один показ объявления по данной фразе.
ContextClicks

Количество кликов по всем объявлениям группы, показанным в Рекламной сети Яндекса по данной фразе. Рассчитывается за 28 дней от текущей даты. Для расчета отбираются дни, в течение которых был хотя бы один клик по объявлению.
ContextShows

Количество показов всех объявлений группы по данной фразе в Рекламной сети Яндекса. Рассчитывается за 28 дней от текущей даты. Для расчета отбираются дни, в течение которых был хотя бы один показ объявления по данной фразе.
Min Цена (в валюте, указанной в параметре Currency) 2 , обеспечивающая для большинства объявлений группы показ в блоке гарантированных показов.
Max Цена (в валюте, указанной в параметре Currency) 2 , обеспечивающая для большинства объявлений группы показ на первом месте в блоке гарантированных показов.
PremiumMin

Цена (в валюте, указанной в параметре Currency) 2 , обеспечивающая для большинства объявлений группы показ в спецразмещении.
PremiumMax Цена (в валюте, указанной в параметре Currency) 2 , обеспечивающая для большинства объявлений группы показ на первом месте в спецразмещении.
LowCTRWarning

Фраза имеет низкий CTR и может быть вскоре отключена — Yes/No.

Ограничение.

Параметр утратил актуальность для новых фраз, поскольку фразы больше не отключаются за низкий CTR.
LowCTR

Фраза отключена на поиске за низкий CTR — Yes/No.

Ограничение.

Параметр утратил актуальность для новых фраз, поскольку фразы больше не отключаются за низкий CTR.
ContextLowCTR

Фраза отключена на сайтах Рекламной сети Яндекса за низкий CTR — Yes/No.

Ограничение.

Параметр утратил актуальность для новых фраз, поскольку фразы больше не отключаются за низкий CTR.
Coverage

Массив объектов CoverageInfo, которые указывают прогнозируемый охват аудитории на поиске.

Ограничение.

Параметр утратил актуальность, использовать его для подбора ставок не следует.
ContextCoverage

Массив объектов CoverageInfo, которые указывают прогнозируемый охват аудитории в Рекламной сети Яндекса.

Параметр полезен для подбора ставок к фразам.
Prices

Массив минимальных ставок за все позиции в спецразмещении и в блоке гарантированных показов (в валюте, указанной в параметре Currency) 2 .
CurrentOnSearch

Конечная цена клика c учетом автоброкера (в валюте, указанной в параметре Currency) 2 .

Если по фразе не осуществляется показ объявления на поиске или фраза отключена на поиске за низкий CTR, в параметре возвращается значение NULL.
MinPrice

Минимальная цена, назначаемая индивидуально для каждого рекламодателя (в валюте, указанной в параметре Currency) 2 .

StatusPaused

Показы по фразе остановлены — Yes/No. Останавливать и возобновлять показы можно методом Keyword (Live).
Currency

Валюта, в которой выражены ставки.

Возможные значения: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN. Если параметр отсутствует или равен NULL, подразумеваются условные единицы (у. е.).
AuctionBids Массив объектов PhraseAuctionBids, содержащий результаты торгов по фразе: ставку за каждую позицию в спецразмещении и в нижнем блоке, а также списываемую цену для каждой позиции.
Объект CoverageInfo
Probability

Частота показа при ставке из параметра Price.

В массиве ContextCoverage указывается в процентах от 0 до 100. Используется для подбора ставок.
Price Ставка (в валюте, указанной в параметре Currency) 2 , для которой параметр Probability содержит частоту показа.
Объект PhraseUserParams
Param1

Значение подстановочной переменной {param1}. Не более 255 байт.
Param2

Значение подстановочной переменной {param2}. Не более 255 байт.
Объект PhraseAuctionBids
Position Позиция показа: Pmn, где
  • m — номер блока (1 — спецразмещение, 2 — блок гарантированных показов);
  • n — номер позиции в рамках блока.

Например, P12 — второе место в спецразмещении, P21 — первое место в блоке гарантированных показов.
Bid Минимальная ставка за указанную позицию (в валюте, указанной в параметре Currency) 2 .
Price Списываемая цена для указанной позиции (в валюте, указанной в параметре Currency) 2 .
Примечания

  1. Если возвращаемые ставки конвертируются из валюты кампании в у. е., то они округляются по математическим правилам с точностью до второго знака после запятой (для всех валют, в том числе тенге).

  2. Если возвращаемые параметры торгов (цены позиций показа и охвата аудитории, ставки конкурентов) конвертируются из валюты кампании в у. е., то они округляются вверх с точностью до шага торгов (0,01 у. е., см. также раздел Реальные валюты вместо у. е.).

  3. В редких случаях цены позиций показа и некоторые другие параметры, связанные с результатами аукциона, могут иметь значение NULL, что говорит об ошибке получения данных на стороне API. Рекомендуется повторить вызов метода через некоторое время.

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

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