--- metadata: - name: generator content: Diplodoc Platform v5.50.2 alternate: - https://yandex.com/dev/direct/doc/dg-v4/en/live/GetBannerPhrasesFilter.md - https://yandex.com/dev/direct/doc/dg-v4/ru/live/GetBannerPhrasesFilter.md --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.com/dev/direct/doc/dg-v4/ru/llms.txt # GetBannerPhrasesFilter (Live) Возвращает информацию о фразах и позволяет ограничить состав возвращаемых данных. ## Новое в версии Live 4 Добавлен результирующий параметр StatusPaused. Добавлены результирующие параметры ContextClicks и ContextShows. Добавлен входной параметр Currrency и результирующий параметр Currency. Добавлен результирующий параметр AdGroupID. Добавлен результирующий параметр AuctionBids. ## Ограничения {#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), "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](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/ErrorCodes.md#BadCurrency). | Нет || |# ## Результирующие данные {#output} Метод возвращает массив объектов `BannerPhraseInfo` с информацией о фразах. Ниже показана структура результирующих данных в формате JSON. {% note info %} Следующие параметры есть в WSDL, но возвращаются только в ответе метода [GetForecast](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/GetForecast.md): FirstPlaceClicks: (int), PremiumClicks: (int), CTR: (float), FirstPlaceCTR: (float), PremiumCTR: (float) {% endnote %} ```javascript { "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`)[ Если возвращаемые ставки конвертируются из валюты кампании в у. е., то они округляются по математическим правилам с точностью до второго знака после запятой (для всех валют, в том числе тенге). ](*-Если-возвращаемые-ставки-конвертируются-из-валюты-кампании-в-у.-е.,-то-они-округляются-по-математическим-правилам-с-точностью-до-второго-знака-после-запятой-(для-всех-валют,-в-том-числе-тенге).-). Используется, только если для кампании выбрана [|| `StrategyName` | [Стратегия](https://yandex.com/dev/direct/doc/dg-v4/ru/concepts/strategy.md) на поиске. Ниже перечислены возможные значения. - 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” (обязательный параметр `WeeklySumLimit`, дополнительный `MaxPrice`); - CPAOptimizer — стратегия “Недельный бюджет: максимальная конверсия”“Weekly budget: maximum conversion rate” (обязательные параметры `WeeklySumLimit` и `GoalID`, дополнительный `MaxPrice`); см. [условия подключения стратегии](https://yandex.ru/support/direct/strategies/weekly-budget.xml)[условия подключения стратегии](https://yandex.com/support/direct/strategies/weekly-budget.xml) в помощи Директа; - AverageClickPrice — стратегия “Средняя цена клика”“Average CPC” (обязательный параметр `AveragePrice`, дополнительный `WeeklySumLimit`); - WeeklyPacketOfClicks — стратегия “Недельный пакет кликов”“Weekly click package” (обязательный параметр `ClicksPerWeek`, дополнительные `MaxPrice` или `AveragePrice`); - AverageCPAOptimization — стратегия “Средняя цена конверсии”“Average CPA” (обязательные параметры `AverageCPA` и `GoalID`, дополнительные `WeeklySumLimit` и `MaxPrice`); см. [условия подключения стратегии](https://yandex.ru/support/direct/strategies/average-cpa.xml)[условия подключения стратегии](https://yandex.com/support/direct/strategies/average-cpa.xml) в помощи Директа; - ROIOptimization — стратегия “Средняя рентабельность инвестиций”“Average ROI” (обязательные параметры `ReserveReturn`, `ROICoef`, `GoalID`, дополнительные `Profitability`, `WeeklySumLimit` и `MaxPrice`); см. [условия подключения стратегии](https://yandex.ru/support/direct/strategies/average-roi.xml)[условия подключения стратегии](https://yandex.com/support/direct/strategies/average-roi.xml) в помощи Директа. | Да ||](*||-`StrategyName`-|-[Стратегия](https://yandex.com/dev/direct/doc/dg-v4/ru/concepts/strategy.md)-на-поиске.-Ниже-перечислены-возможные-значения.----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”-(обязательный-параметр-`WeeklySumLimit`,-дополнительный-`MaxPrice`);---CPAOptimizer-—-стратегия-“Недельный-бюджет:-максимальная-конверсия”“Weekly-budget:-maximum-conversion-rate”-(обязательные-параметры-`WeeklySumLimit`-и-`GoalID`,-дополнительный-`MaxPrice`);-см.-[условия-подключения-стратегии](https://yandex.ru/support/direct/strategies/weekly-budget.xml)[условия-подключения-стратегии](https://yandex.com/support/direct/strategies/weekly-budget.xml)-в-помощи-Директа;---AverageClickPrice-—-стратегия-“Средняя-цена-клика”“Average-CPC”-(обязательный-параметр-`AveragePrice`,-дополнительный-`WeeklySumLimit`);---WeeklyPacketOfClicks-—-стратегия-“Недельный-пакет-кликов”“Weekly-click-package”-(обязательный-параметр-`ClicksPerWeek`,-дополнительные-`MaxPrice`-или-`AveragePrice`);---AverageCPAOptimization-—-стратегия-“Средняя-цена-конверсии”“Average-CPA”-(обязательные-параметры-`AverageCPA`-и-`GoalID`,-дополнительные-`WeeklySumLimit`-и-`MaxPrice`);-см.-[условия-подключения-стратегии](https://yandex.ru/support/direct/strategies/average-cpa.xml)[условия-подключения-стратегии](https://yandex.com/support/direct/strategies/average-cpa.xml)-в-помощи-Директа;---ROIOptimization-—-стратегия-“Средняя-рентабельность-инвестиций”“Average-ROI”-(обязательные-параметры-`ReserveReturn`,-`ROICoef`,-`GoalID`,-дополнительные-`Profitability`,-`WeeklySumLimit`-и-`MaxPrice`);-см.-[условия-подключения-стратегии](https://yandex.ru/support/direct/strategies/average-roi.xml)[условия-подключения-стратегии](https://yandex.com/support/direct/strategies/average-roi.xml)-в-помощи-Директа.-|-Да-||) с ручным управлением ставками. || || `ContextPrice` | Ставка в Рекламной сети Яндекса (в валюте, указанной в параметре `Currency`)[ Если возвращаемые ставки конвертируются из валюты кампании в у. е., то они округляются по математическим правилам с точностью до второго знака после запятой (для всех валют, в том числе тенге). ](*-Если-возвращаемые-ставки-конвертируются-из-валюты-кампании-в-у.-е.,-то-они-округляются-по-математическим-правилам-с-точностью-до-второго-знака-после-запятой-(для-всех-валют,-в-том-числе-тенге).-). Параметр доступен для изменения в следующих случаях: 1. Для Рекламной сети выбрана стратегия MaximumCoverage. 1. Для Рекламной сети выбрана стратегия 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`. Если возвращаемые параметры торгов (цены позиций показа и охвата аудитории, ставки конкурентов) конвертируются из валюты кампании в у. е., то они округляются вверх с точностью до [шага торгов](https://yandex.com/dev/direct/doc/dg-v4/ru/concepts/multicurrency_const.md#increment) (0,01 у. е.). || || `Max` | Цена, обеспечивающая для большинства объявлений группы показ на первом месте в блоке гарантированных показов — в валюте, указанной в параметре `Currency`. Если возвращаемые параметры торгов (цены позиций показа и охвата аудитории, ставки конкурентов) конвертируются из валюты кампании в у. е., то они округляются вверх с точностью до [шага торгов](https://yandex.com/dev/direct/doc/dg-v4/ru/concepts/multicurrency_const.md#increment) (0,01 у. е.). || || `PremiumMin` | Цена, обеспечивающая для большинства объявлений группы показ в спецразмещении — в валюте, указанной в параметре `Currency`. Если возвращаемые параметры торгов (цены позиций показа и охвата аудитории, ставки конкурентов) конвертируются из валюты кампании в у. е., то они округляются вверх с точностью до [шага торгов](https://yandex.com/dev/direct/doc/dg-v4/ru/concepts/multicurrency_const.md#increment) (0,01 у. е.). || || `PremiumMax` | Цена, обеспечивающая для большинства объявлений группы показ на первом месте в спецразмещении — в валюте, указанной в параметре `Currency`. Если возвращаемые параметры торгов (цены позиций показа и охвата аудитории, ставки конкурентов) конвертируются из валюты кампании в у. е., то они округляются вверх с точностью до [шага торгов](https://yandex.com/dev/direct/doc/dg-v4/ru/concepts/multicurrency_const.md#increment) (0,01 у. е.). || || `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.com/dev/direct/doc/dg-v4/ru/concepts/choice-rates.md) к фразам. || || `Prices` | Массив минимальных ставок за все позиции в спецразмещении и в блоке гарантированных показов (в валюте, указанной в параметре `Currency`). Если возвращаемые параметры торгов (цены позиций показа и охвата аудитории, ставки конкурентов) конвертируются из валюты кампании в у. е., то они округляются вверх с точностью до [шага торгов](https://yandex.com/dev/direct/doc/dg-v4/ru/concepts/multicurrency_const.md#increment) (0,01 у. е.). || || `CurrentOnSearch` | Конечная цена клика c учетом автоброкера (в валюте, указанной в параметре `Currency`). Если возвращаемые параметры торгов (цены позиций показа и охвата аудитории, ставки конкурентов) конвертируются из валюты кампании в у. е., то они округляются вверх с точностью до [шага торгов](https://yandex.com/dev/direct/doc/dg-v4/ru/concepts/multicurrency_const.md#increment) (0,01 у. е.). Если по фразе не осуществляется показ объявления на поиске или фраза отключена на поиске за низкий CTR, в параметре возвращается значение NULL. || || `MinPrice` | [Минимальная цена](https://yandex.com/dev/direct/doc/dg-v4/ru/concepts/prices.md#min-price), назначаемая индивидуально для каждого рекламодателя (в валюте, указанной в параметре `Currency`). Если возвращаемые параметры торгов (цены позиций показа и охвата аудитории, ставки конкурентов) конвертируются из валюты кампании в у. е., то они округляются вверх с точностью до [шага торгов](https://yandex.com/dev/direct/doc/dg-v4/ru/concepts/multicurrency_const.md#increment) (0,01 у. е.). || || `StatusPaused` | Показы по фразе остановлены — Yes/No. Останавливать и возобновлять показы можно методом [Keyword (Live)](https://yandex.com/dev/direct/doc/dg-v4/ru/live/Keyword.md). || || `Currency` | Валюта, в которой выражены ставки. Возможные значения: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN. Если параметр отсутствует или равен NULL, подразумеваются условные единицы (у. е.). || || `AuctionBids` | Массив объектов `PhraseAuctionBids`, содержащий результаты торгов по фразе: ставку за каждую позицию в спецразмещении и в нижнем блоке, а также списываемую цену для каждой позиции. || || **Объект CoverageInfo** || || `Probability` | Частота показа при ставке из параметра `Price`. В массиве `ContextCoverage` указывается в процентах от 0 до 100. Используется для [подбора ставок](https://yandex.com/dev/direct/doc/dg-v4/ru/concepts/choice-rates.md). || || `Price` | Ставка, для которой параметр `Probability` содержит частоту показа. (в валюте, указанной в параметре `Currency`). Если возвращаемые параметры торгов (цены позиций показа и охвата аудитории, ставки конкурентов) конвертируются из валюты кампании в у. е., то они округляются вверх с точностью до [шага торгов](https://yandex.com/dev/direct/doc/dg-v4/ru/concepts/multicurrency_const.md#increment) (0,01 у. е.). || || **Объект PhraseUserParams** || || `Param1` | Значение подстановочной переменной `{param1}`. Не более 255 байт. || || `Param2` | Значение подстановочной переменной `{param2}`. Не более 255 байт. || || **Объект PhraseAuctionBids** || || `Position` | Позиция показа: P_mn_, где - _m_ — номер блока (1 — спецразмещение, 2 — блок гарантированных показов); - _n_ — номер позиции в рамках блока. Например, P12 — второе место в спецразмещении, P21 — первое место в блоке гарантированных показов. || || `Bid` | Минимальная ставка за указанную позицию (в валюте, указанной в параметре `Currency`). Если возвращаемые параметры торгов (цены позиций показа и охвата аудитории, ставки конкурентов) конвертируются из валюты кампании в у. е., то они округляются вверх с точностью до [шага торгов](https://yandex.com/dev/direct/doc/dg-v4/ru/concepts/multicurrency_const.md#increment) (0,01 у. е.). || || `Price` | Списываемая цена для указанной позиции (в валюте, указанной в параметре `Currency`). Если возвращаемые параметры торгов (цены позиций показа и охвата аудитории, ставки конкурентов) конвертируются из валюты кампании в у. е., то они округляются вверх с точностью до [шага торгов](https://yandex.com/dev/direct/doc/dg-v4/ru/concepts/multicurrency_const.md#increment) (0,01 у. е.). || || **Примечания** || || 1. Если возвращаемые ставки конвертируются из валюты кампании в у. е., то они округляются по математическим правилам с точностью до второго знака после запятой (для всех валют, в том числе тенге). 1. Если возвращаемые параметры торгов (цены позиций показа и охвата аудитории, ставки конкурентов) конвертируются из валюты кампании в у. е., то они округляются вверх с точностью до [шага торгов](https://yandex.com/dev/direct/doc/dg-v4/ru/concepts/multicurrency_const.md#increment) (0,01 у. е.). 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' } ```