GetBannerPhrasesFilter

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

Ограничения

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

Alert

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

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

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

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

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

^{Параметр}	^{Описание}	^{Требуется}
_{Объект BannerPhrasesFilterRequestInfo}
`BannerIDS`	Массив идентификаторов объявлений (не более 1000).	Да
`FieldsNames`	Массив, содержащий названия параметров, возвращаемых в ответе. Если не задан, возвращаются все предусмотренные параметры. Всегда возвращаются параметры `CampaignID`, `BannerID`, `PhraseID`. Дополнительно могут возвращаться параметры `AutoBroker`, `StatusPhraseModerate`, `IsRubric`, `Price`, `Phrase`. Их названия можно указывать в массиве `FieldsNames`. Чтобы вернуть все параметры, массив не задают.	Нет
`RequestPrices`	Возвращать статистику и цены — Yes/No. Предустановленное значение Yes. Статистика и цены возвращаются в параметрах `ContextPrice`, `Clicks`, `Shows`, `Min`, `Max`, `PremiumMin`, `PremiumMax`, `LowCTRWarning`, `LowCTR`, `ContextLowCTR`, `Coverage`, `ContextCoverage`, `Prices`, `CurrentOnSearch`, `MinPrice`. Названия этих параметров можно указать в массиве `FieldsNames`.	Нет

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

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

{
   "data": [
      {  /* BannerPhraseInfo */
         "BannerID": (long),
         "CampaignID": (int),
         "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),
         "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),
      }
      ...
   ]
}

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

^{Параметр}	^{Описание}
_{Объект BannerPhraseInfo}
`CampaignID`	Идентификатор кампании.
`BannerID`	Идентификатор объявления.
`PhraseID`	Идентификатор фразы.
`Phrase`	Ключевая фраза. Может содержать минус-слова, которые указывают со знаком минус перед словом, например [молния -гром -дождь]. Общие для нескольких фраз минус-слова предпочтительно задавать в параметре группы объявлений `MinusKeywords`. Длина ключевой фразы — не более 4096 символов. Оператор “!” перед минус-словом не учитывается в длине фразы (последовательность “-!” считается как один символ). Не более 7 слов во фразе, без учета стоп-слов и минус-слов. Каждое слово и минус-слово — не более 35 символов, без учета минуса перед минус-словом.
`IsRubric`	Признак того, что фраза является рубрикой Яндекс Каталога. Всегда содержит значение No.
`Price`	Ставка на поиске Яндекса (у. е.). Предустановленное ограничение — 50 у. е. Требуется, только если для кампании выбрана с ручным управлением ставками.
`ContextPrice`	Ставка в Рекламной сети Яндекса (у. е.). Ставку можно задавать в следующих случаях: На поиске используется стратегия IndependentControl. Эту стратегию можно выбрать только через веб-интерфейс Директа. На поиске используется любая ручная стратегия и фраза отключена за низкий CTR. Для новых фраз данное условие не актуально, поскольку фразы больше не отключаются за низкий CTR.
`AutoBroker`	Признак включенного автоброкера. Всегда содержит значение Yes.
`UserParams`	Объект `PhraseUserParams`. Содержит значения подстановочных переменных для формирования ссылки на сайт (см. раздел {#T}).
`StatusPhraseModerate`	Результат проверки фразы: New — фраза не проверена; Yes — принята; No — отклонена;
`AutoBudgetPriority`	Приоритет фразы при использовании автоматических стратегий. Возможные значения: Low — низкий приоритет; Medium — средний приоритет; High — высокий приоритет.
`Clicks`	Количество кликов по объявлению, показанному на поиске по данной фразе. Рассчитывается за 28 дней от текущей даты. Для расчета отбираются дни, в течение которых был хотя бы один клик по объявлению.
`Shows`	Количество показов объявления по данной фразе на поиске. Рассчитывается за 28 дней от текущей даты. Для расчета отбираются дни, в течение которых был хотя бы один показ объявления по данной фразе.
`Min`	Минимальная ставка за вход в блок гарантированных показов.
`Max`	Минимальная ставка за 1-ю позицию в блоке гарантированных показов.
`PremiumMin`	Минимальная ставка за вход в спецразмещение.
`PremiumMax`	Минимальная ставка за 1-ю позицию в спецразмещении.
`LowCTRWarning`	Фраза имеет низкий CTR и может быть вскоре отключена — Yes/No. Alert Параметр утратил актуальность для новых фраз, поскольку фразы больше не отключаются за низкий CTR.
`LowCTR`	Фраза отключена на поиске за низкий CTR — Yes/No. Alert Параметр утратил актуальность для новых фраз, поскольку фразы больше не отключаются за низкий CTR.
`ContextLowCTR`	Фраза отключена на сайтах Рекламной сети Яндекса за низкий CTR — Yes/No. Alert Параметр утратил актуальность для новых фраз, поскольку фразы больше не отключаются за низкий CTR.
`Coverage`	Массив объектов `CoverageInfo`, которые указывают прогнозируемый охват аудитории на поиске. Alert Параметр утратил актуальность, использовать его для подбора ставок не следует.
`ContextCoverage`	Массив объектов `CoverageInfo`, которые указывают прогнозируемый охват аудитории в Рекламной сети Яндекса. Параметр полезен для подбора ставок к фразам.
`Prices`	Массив ставок за все позиции в спецразмещении и в блоке гарантированных показов.
`CurrentOnSearch`	Конечная цена клика c учетом автоброкера. Если по фразе не осуществляется показ объявления на поиске или фраза отключена на поиске за низкий CTR, в параметре возвращается значение NULL.
`MinPrice`	Минимальная цена, назначаемая индивидуально для каждого рекламодателя.
_{Объект CoverageInfo}
`Probability`	Частота показа при ставке из параметра `Price`. В массиве `ContextCoverage` указывается в процентах от 0 до 100. Используется для подбора ставок.
`Price`	Ставка, для которой параметр `Probability` содержит частоту показа.
_{Объект PhraseUserParams}
`Param1`	Значение подстановочной переменной `{param1}`. Не более 255 байт.
`Param2`	Значение подстановочной переменной `{param2}`. Не более 255 байт.
Примечания
В редких случаях цены позиций показа и некоторые другие параметры, связанные с результатами аукциона, могут иметь значение 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'
}