GetBanners

Возвращает параметры объявлений и фраз.
Для метода существует версия GetBanners (Live).

Кроме параметров объявлений, метод возвращает параметры фраз в сокращенном или в полном виде, что определяется входным параметром GetPhrases. При значении “No” сведения о фразах не возвращаются. При значении “Yes” или если GetPhrases отсутствует, возвращается сокращенный состав сведений о фразах. При значении “WithPrices” возвращается полный состав сведений о фразах, а результирующая структура после модификации необходимых параметров может подаваться на вход метода CreateOrUpdateBanners.

Ограничения

Alert

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

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

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

{
   "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 и StopBanners соответственно.	Нет
`IsActive`	Отбирать объявления по статусу активизации: Yes — активизированные объявления; No — неактивизированные объявления.	Нет
`StatusArchive`	Отбирать объявления по статусу архивирования: Yes — объявления в архиве; No — объявления не в архиве.	Нет

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

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

{
   "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`	Ссылка на сайт рекламодателя. Может содержать подстановочные переменные (см. раздел {#T}).
`Domain`	Домен, на который ведет ссылка `Href`. Домен заполняется автоматически. Если ссылка ведет на редирект, в параметре указан конечный домен.
`Geo`	Идентификаторы регионов, для которых показы включены или выключены. Идентификатор 0 или пустая строка — показывать во всех регионах (предустановленное значение). Чтобы выключить показ в регионе, перед идентификатором региона ставят минус, например “1,-219” — показывать для Москвы и Московской области, кроме Черноголовки. Регионы с минусом нельзя использовать, если указан нулевой регион. Также параметр не должен состоять только из минус-регионов. Полный список регионов можно получить с помощью метода GetRegions.
`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 и StopBanners. Разрешение показа не означает, что объявления фактически показываются. Для этого необходимо выполнение и других условий: достаточный баланс средств, кампания и объявление проверены модератором, показ на уровне кампании разрешен (метод ResumeCampaign). Фактическому показу соответствует значение Yes в параметре `IsActive`.
`IsActive`	Объявление активно — Yes/No. Под активностью понимается состояние объявлений, при котором показ включается и выключается автоматически — в соответствии с настройками временного таргетинга или в зависимости от баланса кампании. Неактивными являются объявления, показ которых выключен пользователем или менеджером Яндекса и не может быть включен автоматически.
`StatusSitelinksModerate`	Результат проверки быстрых ссылок: New — быстрые ссылки не проверены; Pending — выполняется проверка; Yes — принято; No — отклонено.
`Sitelinks`	Массив объектов `Sitelink` с быстрыми ссылками быстрыми ссылками. Массив должен содержать от 1 до 4 объектов `Sitelink` или отсутствовать.
`AdWarnings`	Массив, содержащий отметки о принадлежности объекта рекламирования к особым категориям. Для таких категорий показ объявлений либо запрещен, либо сопровождается предупреждением в соответствии с законодательством РФ. Возможные группы: abortion — медицинские услуги по искусственному прерыванию беременности; alcohol — алкогольная продукция, пиво и напитки на его основе; baby_food — детское питание; dietarysuppl — БАД; medicine — лекарственные средства, медицинская техника, медицинские услуги, в том числе методы лечения; pseudoweapon — изделия, конструктивно сходные с оружием; tobacco — табак и табачные изделия; project_declaration — долевое строительство.
`FixedOnModeration`	В ходе модерации исправлены опечатки — Yes/No.
`ModerateRejectionReasons`	Массив объектов `RejectReason`. Эти объекты описывают причины, по которым отклонен текст объявления, фраза, контактная информация, быстрая ссылка.
`MinusKeywords`	Массив минус-фраз, общих для всех ключевых фраз группы объявлений. Минус-фразу следует указывать без минуса перед первым словом. Не более 7 слов в минус-фразе. Длина каждого слова — не более 35 символов. Суммарная длина минус-фраз в массиве — не более 4096 символов. Оператор “!” или “+” перед словом не учитывается в суммарной длине. Note Минус-фразы, общие для всех групп в кампании, предпочтительно задавать в одноименном параметре кампании.
_{Объект 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`	Ставка в Рекламной сети Яндекса (у. е.). Ставку можно задавать в следующих случаях: На поиске используется стратегия 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 байт.
_{Объект Sitelink}
`Title`	Текст быстрой ссылки.
`Href`	Адрес быстрой ссылки. Может содержать подстановочные переменные (см. раздел {#T}).
_{Объект RejectReason}
`Type`	Тип объекта, отклоненного на модерации, — Banner, Phrases, ContactInfo, Sitelink.
`Text`	Причина отклонения на модерации.
Примечания
В редких случаях цены позиций показа и некоторые другие параметры, связанные с результатами аукциона, могут иметь значение NULL, что говорит об ошибке получения данных на стороне API. Рекомендуется повторить вызов метода через некоторое время.

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

Python

{
   'BannerIDS': [1974642, 20920155, 20155899, 64654],
   'Filter': {
      'StatusPhoneModerate': ['Yes'],
      'StatusBannerModerate': ['Yes'],
      'StatusPhrasesModerate': ['Yes'],
      'StatusActivating': ['Yes'],
      'StatusShow': ['Yes'],
      'IsActive': ['Yes'],
      'StatusArchive': ['No']
   },
   'GetPhrases': 'WithPrices'
}

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

{
   'BannerIDS' =[1974642, 20920155, 20155899, 64654],
   'Filter' ={
      'StatusPhoneModerate' =['Yes'],
      'StatusBannerModerate' =['Yes'],
      'StatusPhrasesModerate' =['Yes'],
      'StatusActivating' =['Yes'],
      'StatusShow' =['Yes'],
      'IsActive' =['Yes'],
      'StatusArchive' =['No']
   },
   'GetPhrases' ='WithPrices'
}