--- metadata: - name: generator content: Diplodoc Platform v5.50.2 alternate: - https://yandex.com/dev/direct/doc/dg-v4/en/reference/GetBanners.md - https://yandex.com/dev/direct/doc/dg-v4/ru/reference/GetBanners.md --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.com/dev/direct/doc/dg-v4/en/llms.txt # GetBanners Возвращает параметры объявлений и фраз. Для метода существует версия [GetBanners (Live)](https://yandex.ru/dev/direct/doc/dg-v4/live/GetBanners.html). Кроме параметров объявлений, метод возвращает параметры фраз в сокращенном или в полном виде, что определяется входным параметром `GetPhrases`. При значении “No” сведения о фразах не возвращаются. При значении “Yes” или если `GetPhrases` отсутствует, возвращается сокращенный состав сведений о фразах. При значении “WithPrices” возвращается полный состав сведений о фразах, а результирующая структура после модификации необходимых параметров может подаваться на вход метода [CreateOrUpdateBanners](https://yandex.ru/dev/direct/doc/dg-v4/reference/CreateOrUpdateBanners.html). ## Ограничения {% note alert %} Метод возвращает только текстово-графические объявления. Для работы с объявлениями всех типов используйте сервис [Ads](https://yandex.ru/dev/direct/doc/ru/ads/ads) API версии 5. [Подробнее о типах объявлений...](https://yandex.ru/dev/direct/doc/dg-v4/dg/objects/ad.html) {% endnote %} ## Входные данные {#input} Ниже показана структура входных данных в формате JSON. ```javascript { "method": "GetBanners", "param": { /* GetBannersInfo */ "CampaignIDS": [ (int) ... ], "BannerIDS": [ (long) ... ], "GetPhrases": (string), "Filter": { /* BannersFilterInfo */ "StatusPhoneModerate": [ (string) ... ], "StatusBannerModerate": [ (string) ... ], "StatusPhrasesModerate": [ (string) ... ], "StatusActivating": [ (string) ... ], "StatusShow": [ (string) ... ], "IsActive": [ (string) ... ], "StatusArchive": [ (string) ... ] } } } ``` Ниже приведено описание параметров. #| || **Параметр** | **Описание** | **Требуется** || || **Объект GetBannersInfo** || || `CampaignIDS` | Массив идентификаторов кампаний (не более 10 идентификаторов). Метод возвращает параметры объявлений, принадлежащих указанным кампаниям. | Один из параметров: `CampaignIDS` или `BannerIDS` || || `BannerIDS` | Массив, содержащий идентификаторы объявлений. Допускается указывать не более 2000 идентификаторов. Данный параметр имеет приоритет над `CampaignIDS`: если указаны оба параметра, объявления отбираются по идентификаторам из массива `BannerIDS`. || || `Filter` | Содержит объект `BannersFilterInfo`, задающий условия отбора объявлений. | Нет || || `GetPhrases` | Возвращать параметры фраз в массиве `Phrases`: - No — не возвращать параметры фраз; - Yes — возвращать сокращенный состав параметров; - WithPrices — возвращать полный состав параметров, включая цены и статистику. Если параметр `GetPhrases` отсутствует, подразумевается значение Yes. | Нет || || **Объект BannersFilterInfo** || || `StatusBannerModerate` | Отбирать объявления по результату модерации: - New — объявление не проверено (статус “Черновик”); - Pending — выполняется проверка; - Yes — принято; - No — отклонено; - PreliminaryAccept — объявление предварительно принято, окончательный результат будет известен позже. | Нет || || `StatusPhrasesModerate` | Отбирать объявления по результату модерации фраз: - New — фразы не проверены; - Pending — выполняется проверка; - Yes — хотя бы одна фраза принята (некоторые могли быть отклонены); - No — все фразы отклонены; - PreliminaryAccept — фразы предварительно приняты, окончательный результат будет известен позже. | Нет || || `StatusPhoneModerate` | Отбирать объявления по результату модерации визитки: - New — контактная информация не проверена; - Pending — выполняется проверка; - Yes — принято; - No — отклонено; | Нет || || `StatusActivating` | Отбирать объявления по актуальности внесенных изменений: - Yes — внесенные изменения вступили в силу; - Pending — ожидается вступление изменений в силу. Между внесением изменений в объявления и вступлением изменений в силу проходит некоторое время. Обычно оно не превышает 40 минут, но в часы наибольшей нагрузки может достигать трех часов. | Нет || || `StatusShow` | Отбирать показываемые или непоказываемые объявления : - Yes — показ включен; - No — показ выключен. Включение и выключение показа выполняется методами [ResumeBanners](https://yandex.ru/dev/direct/doc/dg-v4/reference/ResumeBanners.html) и [StopBanners](https://yandex.ru/dev/direct/doc/dg-v4/reference/StopBanners.html) соответственно. | Нет || || `IsActive` | Отбирать объявления по статусу активизации: - Yes — активизированные объявления; - No — неактивизированные объявления. | Нет || || `StatusArchive` | Отбирать объявления по статусу архивирования: - Yes — объявления в архиве; - No — объявления не в архиве. | Нет || |# ## Результирующие данные {#output} Возвращается массив объектов `BannerInfo`, содержащих параметры объявлений. Ниже показана структура результирующих данных в формате JSON. ```javascript { "data": [ { /* BannerInfo */ "BannerID": (long), "CampaignID": (int), "Title": (string), "Text": (string), "Href": (string), "Domain": (string), "Geo": (string), "ContactInfo": { /* ContactInfo */ "ContactPerson": (string), "Country": (string), "CountryCode": (string), "City": (string), "Street": (string), "House": (string), "Build": (string), "Apart": (string), "CityCode": (string), "Phone": (string), "PhoneExt": (string), "CompanyName": (string), "IMClient": (string), "IMLogin": (string), "ExtraMessage": (string), "ContactEmail": (string), "WorkTime": (string), "OGRN": (string), "PointOnMap": { /* MapPoint */ "x": (float), "y": (float), "x1": (float), "y1": (float), "x2": (float), "y2": (float) } }, "Phrases": [ { /* 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) } ... ], "StatusActivating": (string), "StatusArchive": (string), "StatusBannerModerate": (string), "StatusPhrasesModerate": (string), "StatusPhoneModerate": (string), "StatusShow": (string), "IsActive": (string), "StatusSitelinksModerate": (string), "Sitelinks": [ { /* Sitelink */ "Title": (string), "Href": (string) } ... ], "AdWarnings": [ (string) ... ], "FixedOnModeration": (string), "ModerateRejectionReasons": [ { /* RejectReason */ "Type": (string), "Text": (string) } ... ], "MinusKeywords": [ (string) ... ] } ... ] } ``` Ниже приведено описание параметров. #| || **Параметр** | **Описание** || || **Объект BannerInfo** || || `BannerID` | Идентификатор объявления. Для создания объявления задают 0, для изменения параметров объявления указывают его идентификатор. || || `CampaignID` | Идентификатор кампании. || || `Title` | Заголовок объявления (до 33 символов, включая пробелы и знаки препинания). || || `Text` | Текст объявления (до 75 символов, включая пробелы и знаки препинания). || || `Href` | Ссылка на сайт рекламодателя. Может содержать подстановочные переменные. || || `Domain` | Домен, на который ведет ссылка `Href`. Домен заполняется автоматически. Если ссылка ведет на редирект, в параметре указан конечный домен. || || `Geo` | Идентификаторы регионов, для которых показы включены или выключены. Идентификатор 0 или пустая строка — показывать во всех регионах (предустановленное значение). Чтобы выключить показ в регионе, перед идентификатором региона ставят минус, например “1,-219” — показывать для Москвы и Московской области, кроме Черноголовки. Регионы с минусом нельзя использовать, если указан нулевой регион. Также параметр не должен состоять только из минус-регионов. Полный список регионов можно получить с помощью метода [GetRegions](https://yandex.ru/dev/direct/doc/dg-v4/reference/GetRegions.html). || || `ContactInfo` | Объект `ContactInfo` с контактными данными рекламодателя (визитка). || || `Phrases` | Массив объектов `BannerPhraseInfo` с параметрами фраз. Выводится, если входной параметр `GetPhrases` имеет значение “Yes” или “WithPrices” либо отсутствует. || || `StatusActivating` | Все внесенные изменения вступили в силу — Yes/Pending. || || `StatusArchive` | Объявление помещено в архив — Yes/No. || || `StatusBannerModerate` | Результат модерации объявления (проверяется текст и ссылка): - New — объявление не проверено (статус “Черновик”); - Pending — выполняется проверка; - Yes — принято; - No — отклонено; - PreliminaryAccept — объявление предварительно принято, окончательный результат будет известен позже. || || `StatusPhrasesModerate` | Результат модерации фраз: - New — фразы не проверены; - Pending — выполняется проверка; - Yes — хотя бы одна фраза принята (некоторые могли быть отклонены); - No — все фразы отклонены; - PreliminaryAccept — фразы предварительно приняты, окончательный результат будет известен позже. || || `StatusPhoneModerate` | Результат модерации визитки: - New — контактная информация не проверена; - Pending — выполняется проверка; - Yes — принято; - No — отклонено; || || `StatusShow` | Показ объявления включен — Yes/No. Включение и выключение показа выполняется методами [ResumeBanners](https://yandex.ru/dev/direct/doc/dg-v4/reference/ResumeBanners.html) и [StopBanners](https://yandex.ru/dev/direct/doc/dg-v4/reference/StopBanners.html). Разрешение показа не означает, что объявления фактически показываются. Для этого необходимо выполнение и других условий: достаточный баланс средств, кампания и объявление проверены модератором, показ на уровне кампании разрешен (метод [ResumeCampaign](https://yandex.ru/dev/direct/doc/dg-v4/reference/ResumeCampaign.html)). Фактическому показу соответствует значение Yes в параметре `IsActive`. || || `IsActive` | Объявление активно — Yes/No. Под активностью понимается состояние объявлений, при котором показ включается и выключается автоматически — в соответствии с настройками временного таргетинга или в зависимости от баланса кампании. Неактивными являются объявления, показ которых выключен пользователем или менеджером Яндекса и не может быть включен автоматически. || || `StatusSitelinksModerate` | Результат проверки быстрых ссылок: - New — быстрые ссылки не проверены; - Pending — выполняется проверка; - Yes — принято; - No — отклонено. || || `Sitelinks` | Массив объектов `Sitelink` с [быстрыми ссылками](https://yandex.ru/support/direct/features/quick-links.xml)[быстрыми ссылками](https://yandex.com/support/direct/features/quick-links.xml). Массив должен содержать от 1 до 4 объектов `Sitelink` или отсутствовать. || || `AdWarnings` | Массив, содержащий отметки о принадлежности объекта рекламирования к особым категориям. Для таких категорий показ объявлений либо запрещен, либо сопровождается предупреждением в соответствии с законодательством РФ. Возможные группы: - abortion — медицинские услуги по искусственному прерыванию беременности; - alcohol — алкогольная продукция, пиво и напитки на его основе; - baby_food — детское питание; - dietarysuppl — БАД; - medicine — лекарственные средства, медицинская техника, медицинские услуги, в том числе методы лечения; - pseudoweapon — изделия, конструктивно сходные с оружием; - tobacco — табак и табачные изделия; - project_declaration — долевое строительство. || || `FixedOnModeration` | В ходе модерации исправлены опечатки — Yes/No. || || `ModerateRejectionReasons` | Массив объектов `RejectReason`. Эти объекты описывают причины, по которым отклонен текст объявления, фраза, контактная информация, быстрая ссылка. || || `MinusKeywords` | Массив минус-фраз, общих для всех ключевых фраз группы объявлений. Минус-фразу следует указывать без минуса перед первым словом. Не более 7 слов в минус-фразе. Длина каждого слова — не более 35 символов. Суммарная длина минус-фраз в массиве — не более 4096 символов. Оператор “!” или “+” перед словом не учитывается в суммарной длине. {% note info %} Минус-фразы, общие для всех групп в кампании, предпочтительно задавать в одноименном параметре кампании. {% endnote %} || || **Объект ContactInfo** || || `ContactPerson` | Контактное лицо. Не более 155 символов. || || `Country` | Страна. Не более 50 символов. || || `CountryCode` | Телефонный код страны. Например, “+7” для России. || || `City` | Город. Не более 50 символов. || || `Street` | Улица. Не более 55 символов. || || `House` | Номер дома. Не более 30 символов. || || `Build` | Номер строения или корпуса. Не более 10 символов. || || `Apart` | Номер квартиры или офиса. Не более 255 символов. || || `CityCode` | Телефонный код города. || || `Phone` | Телефонный номер для связи. || || `PhoneExt` | Добавочный телефонный номер для соединения через офисную АТС. || || `CompanyName` | Название организации. Не более 255 символов. || || `IMClient` | Тип сети мгновенного обмена сообщениями — icq, jabber, skype, mail_agent. || || `IMLogin` | Логин в сети мгновенного обмена сообщениями. || || `ExtraMessage` | Дополнительная информация о рекламируемом товаре или услуге. Не более 200 символов. || || `ContactEmail` | Адрес электронной почты. Не более 255 символов. || || `WorkTime` | Режим работы организации или режим обслуживания клиентов. Задается как строка, в которой указан диапазон дней недели, рабочих часов и минут. Дни недели обозначаются цифрами от 0 до 6, где 0 — понедельник, 6 — воскресенье. Минуты задают кратно 15: 0, 15, 30 или 45. Формат строки: `"день_с;день_по;час_с;минуты_с;час_до;мин_до"` Например, строка `"0;4;10;0;18;0"` задает такой режим: `0;4` — с понедельника по пятницу; `10;0` — с 10 часов 0 минут; `18;0` — до 18 часов 0 минут. Режим может состоять из нескольких строк указанного формата, например: "`0;4;10;0;18;0;5;6;11;0;16;0`". Здесь в дополнение к предыдущему примеру задан режим: `5;6` — с субботы по воскресенье; `11;0` — с 11 часов 0 минут; `16;0` — до 16 часов 0 минут. Круглосуточный режим работы задается строкой `"0;6;00;00;00;00"`. || || `OGRN` | Код ОГРН для юридических лиц. || || `PointOnMap` | Объект `MapPoint`, задающий координаты местоположения клиента. По этим координатам ставится метка на карте. Если не заданы, метка ставится по указанному адресу клиента. || || **Объект MapPoint** || || `x` | Долгота точки. От -180 до 180. || || `y` | Широта точки. От -90 до 90. || || `x1` | Долгота левого нижнего угла области на карте. От -180 до 180. || || `y1` | Широта левого нижнего угла области на карте. От -90 до 90. || || `x2` | Долгота правого верхнего угла области на карте. От -180 до 180. || || `y2` | Широта правого верхнего угла области на карте. От -90 до 90. || || **Объект 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 байт. || || **Объект Sitelink** || || `Title` | Текст быстрой ссылки. || || `Href` | Адрес быстрой ссылки. Может содержать подстановочные переменные. || || **Объект RejectReason** || || `Type` | Тип объекта, отклоненного на модерации, — Banner, Phrases, ContactInfo, Sitelink. || || `Text` | Причина отклонения на модерации. || || **Примечания** || || 1. В редких случаях цены позиций показа и некоторые другие параметры, связанные с результатами аукциона, могут иметь значение NULL, что говорит об ошибке получения данных на стороне API. Рекомендуется повторить вызов метода через некоторое время. || |# ## Примеры входных данных {#examples} ## Python ```python { 'BannerIDS': [1974642, 20920155, 20155899, 64654], 'Filter': { 'StatusPhoneModerate': ['Yes'], 'StatusBannerModerate': ['Yes'], 'StatusPhrasesModerate': ['Yes'], 'StatusActivating': ['Yes'], 'StatusShow': ['Yes'], 'IsActive': ['Yes'], 'StatusArchive': ['No'] }, 'GetPhrases': 'WithPrices' } ``` ## PHP ```php array( 'BannerIDS' => array(1974642, 20920155, 20155899, 64654), 'Filter' => array( 'StatusPhoneModerate' => array('Yes'), 'StatusBannerModerate' => array('Yes'), 'StatusPhrasesModerate' => array('Yes'), 'StatusActivating' => array('Yes'), 'StatusShow' => array('Yes'), 'IsActive' => array('Yes'), 'StatusArchive' => array('No') ), 'GetPhrases' ='WithPrices' ) ``` ## Perl ```perl { 'BannerIDS' => [1974642, 20920155, 20155899, 64654], 'Filter' ={ 'StatusPhoneModerate' => ['Yes'], 'StatusBannerModerate' => ['Yes'], 'StatusPhrasesModerate' => ['Yes'], 'StatusActivating' => ['Yes'], 'StatusShow' => ['Yes'], 'IsActive' => ['Yes'], 'StatusArchive' => ['No'] }, 'GetPhrases' ='WithPrices' } ```