GetBanners

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

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

Ограничения

Alert

Метод возвращает только текстово-графические объявления. Для работы с объявлениями всех типов используйте сервис Ads 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

Ссылка на сайт рекламодателя. Может содержать подстановочные переменные.

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

Ставка в Рекламной сети Яндекса (у. е.). Ставку можно задавать в следующих случаях:

  1. На поиске используется стратегия IndependentControl. Эту стратегию можно выбрать только через веб-интерфейс Директа.

  2. На поиске используется любая ручная стратегия и фраза отключена за низкий 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.

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

Адрес быстрой ссылки. Может содержать подстановочные переменные.

Объект RejectReason

Type

Тип объекта, отклоненного на модерации, — Banner, Phrases, ContactInfo, Sitelink.

Text

Причина отклонения на модерации.

Примечания

  1. В редких случаях цены позиций показа и некоторые другие параметры, связанные с результатами аукциона, могут иметь значение 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'
}
Previous
DeleteBanners (Live)
Next
GetBanners (Live)