--- metadata: - name: generator content: Diplodoc Platform v5.50.2 alternate: - https://yandex.com/dev/direct/doc/dg-v4/en/reference/GetBannerPhrasesFilter.md - https://yandex.com/dev/direct/doc/dg-v4/ru/reference/GetBannerPhrasesFilter.md --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.com/dev/direct/doc/dg-v4/ru/llms.txt # GetBannerPhrasesFilter Возвращает информацию о фразах и позволяет ограничить состав возвращаемых данных. Для метода существует версия [GetBannerPhrasesFilter (Live)](https://yandex.ru/dev/direct/doc/dg-v4/live/GetBannerPhrasesFilter.html). ## Ограничения {#phrases-from-arch} Получение фраз из архивных кампаний недоступно. {% note alert %} Метод поддерживает только текстово-графические объявления. Для работы с ключевыми фразами объявлений всех типов используйте сервис [Keywords](https://yandex.ru/dev/direct/doc/ru/keywords/keywords) API версии 5. {% endnote %} ## Входные данные {#input} Ниже показана структура входных данных в формате JSON. ```javascript { "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`. | Нет || |# ## Результирующие данные {#output} Метод возвращает массив объектов `BannerPhraseInfo` с информацией о фразах. Ниже показана структура результирующих данных в формате JSON. ```javascript { "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` | Ставка в Рекламной сети Яндекса (у. е.). Ставку можно задавать в следующих случаях: 1. На поиске используется стратегия IndependentControl. Эту стратегию можно выбрать только через веб-интерфейс Директа. 1. На поиске используется любая ручная стратегия и фраза отключена за низкий CTR. Для новых фраз данное условие не актуально, поскольку фразы больше не отключаются за низкий CTR. || || `AutoBroker` | Признак включенного автоброкера. Всегда содержит значение Yes. || || `UserParams` | Объект `PhraseUserParams`. Содержит значения подстановочных переменных для формирования ссылки на сайт. || || `StatusPhraseModerate` | Результат проверки фразы: - New — фраза не проверена; - Yes — принята; - No — отклонена; || || `AutoBudgetPriority` | Приоритет фразы при использовании автоматических стратегий. Возможные значения: - Low — низкий приоритет; - Medium — средний приоритет; - High — высокий приоритет. || || `Clicks` | Количество кликов по объявлению, показанному на поиске по данной фразе. Рассчитывается за 28 дней от текущей даты. Для расчета отбираются дни, в течение которых был хотя бы один клик по объявлению. || || `Shows` | Количество показов объявления по данной фразе на поиске. Рассчитывается за 28 дней от текущей даты. Для расчета отбираются дни, в течение которых был хотя бы один показ объявления по данной фразе. || || `Min` | Минимальная ставка за вход в блок гарантированных показов. || || `Max` | Минимальная ставка за 1-ю позицию в блоке гарантированных показов. || || `PremiumMin` | Минимальная ставка за вход в спецразмещение. || || `PremiumMax` | Минимальная ставка за 1-ю позицию в спецразмещении. || || `LowCTRWarning` | Фраза имеет низкий CTR и может быть вскоре отключена — Yes/No. {% note alert %} Параметр утратил актуальность для новых фраз, поскольку фразы больше не отключаются за низкий CTR. {% endnote %} || || `LowCTR` | Фраза отключена на поиске за низкий CTR — Yes/No. {% note alert %} Параметр утратил актуальность для новых фраз, поскольку фразы больше не отключаются за низкий CTR. {% endnote %} || || `ContextLowCTR` | Фраза отключена на сайтах Рекламной сети Яндекса за низкий CTR — Yes/No. {% note alert %} Параметр утратил актуальность для новых фраз, поскольку фразы больше не отключаются за низкий CTR. {% endnote %} || || `Coverage` | Массив объектов `CoverageInfo`, которые указывают прогнозируемый охват аудитории на поиске. {% note alert %} Параметр утратил актуальность, использовать его для подбора ставок не следует. {% endnote %} || || `ContextCoverage` | Массив объектов `CoverageInfo`, которые указывают прогнозируемый охват аудитории в Рекламной сети Яндекса. Параметр полезен для [подбора ставок](https://yandex.ru/dev/direct/doc/dg-v4/concepts/choice-rates.html) к фразам. || || `Prices` | Массив ставок за все позиции в спецразмещении и в блоке гарантированных показов. || || `CurrentOnSearch` | Конечная цена клика c учетом автоброкера. Если по фразе не осуществляется показ объявления на поиске или фраза отключена на поиске за низкий CTR, в параметре возвращается значение NULL. || || `MinPrice` | [Минимальная цена](https://yandex.ru/dev/direct/doc/dg-v4/concepts/prices.html#min-price), назначаемая индивидуально для каждого рекламодателя. || || **Объект CoverageInfo** || || `Probability` | Частота показа при ставке из параметра `Price`. В массиве `ContextCoverage` указывается в процентах от 0 до 100. Используется для [подбора ставок](https://yandex.ru/dev/direct/doc/dg-v4/concepts/choice-rates.html). || || `Price` | Ставка, для которой параметр `Probability` содержит частоту показа. || || **Объект PhraseUserParams** || || `Param1` | Значение подстановочной переменной `{param1}`. Не более 255 байт. || || `Param2` | Значение подстановочной переменной `{param2}`. Не более 255 байт. || || **Примечания** || || 1. В редких случаях цены позиций показа и некоторые другие параметры, связанные с результатами аукциона, могут иметь значение NULL, что говорит об ошибке получения данных на стороне API. Рекомендуется повторить вызов метода через некоторое время. || |# ## Примеры входных данных {#example} ## Python ```python { 'BannerIDS': [20155899], 'FieldsNames': ['Phrase','Price','Phrase','MinPrice','Clicks'], 'RequestPrices': 'Yes', 'ConsiderTimeTarget': 'Yes' } ``` ## PHP ```php array( 'BannerIDS' => array(20155899), 'FieldsNames' => array('Phrase','Price','Phrase','MinPrice','Clicks'), 'RequestPrices' => 'Yes', 'ConsiderTimeTarget' ='Yes' ) ``` ## Perl ```perl { 'BannerIDS' => [20155899], 'FieldsNames' => ['Phrase','Price','Phrase','MinPrice','Clicks'], 'RequestPrices' => 'Yes', 'ConsiderTimeTarget' ='Yes' } ```