GetCampaignsListFilter (Live)

Возвращает список кампаний, соответствующих условиям отбора, с краткими сведениями о кампаниях.

Ограничения

Внимание

Метод возвращает только кампании с типом “Текстово-графические объявления”“Text & Image Ads”. Для работы с кампаниями всех типов используйте сервис Campaigns API версии 5. Подробнее о типах кампаний...

Новое в версии Live 4

Добавлены результирующие параметры StrategyName и ContextStrategyName.

Добавлены входные параметры Limit и Offset. Служат для постраничной выборки кампаний из базы данных.

Добавлен входной параметр CurrencySupported, а также результирующие параметры Currency, CampaignCurrency, BonusDiscount и SourceCampaignID.

Добавлен результирующий параметр DayBudgetEnabled.

Добавлен результирующий параметр EnableRelatedKeywords.

Добавлен результирующий параметр ExtendedAdTitleEnabled.

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

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

{
   "method": "GetCampaignsListFilter",
   "param": {
      /* GetCampaignsInfo */
      "Logins": [
         (string)
         ...
      ],
      "Filter": {
         /* CampaignsFilterInfo */
         "StatusModerate": [
            (string)
            ...
         ],
         "IsActive": [
            (string)
            ...
         ],
         "StatusArchive": [
            (string)
            ...
         ],
         "StatusActivating": [
            (string)
            ...
         ],
         "StatusShow": [
            (string)
            ...
         ]
      },
      "Limit": (int),
      "Offset": (int),
      "CurrencySupported": (string)
   }
}

Ниже приведено описание параметров.

Параметр

Описание

Требуется

Объект GetCampaignsInfo

Logins

Массив, содержащий логины клиентов (не более 100), для которых требуется получить список кампаний. Заполняется только рекламными агентствами. Другие пользователи могут не указывать этот параметр.

Да для рекламных агентств

Filter

Объект CampaignsFilterInfo, содержащий условия отбора кампаний. Если не задан, возвращаются сведения о всех кампаниях, как в методе GetCampaignsList (Live).

Нет

Limit

Количество кампаний, параметры которых выводятся в ответ (число больше нуля). Вместе с параметром Offset позволяет организовать постраничную выборку из базы данных.

Нет

Offset

Порядковый номер кампании в выборке из базы данных (число больше нуля). В ответ выводятся кампании, начиная с указанного номера, в количестве Limit.

Нет

CurrencySupported

Возвращать денежные значения в валюте кампании — Yes/No. При значении No значения конвертируются из валюты кампании в у. е.

Значение по умолчанию — No.

Нет

Объект CampaignsFilterInfo

StatusModerate

Отбирать кампании по состоянию модерации:

  • Yes — прошедшие модерацию;
  • No — не прошедшие модерацию;
  • New — не отправленные на модерацию (статус “Черновик”);
  • Pending — находящиеся на модерации.

Нет

IsActive

Отбирать кампании по состоянию активности:

  • Yes — активные;
  • No — не активные.

Под активностью понимается состояние кампании, при котором показ объявлений включается и выключается автоматически — в соответствии с настройками временного таргетинга или в зависимости от баланса кампании. Неактивность кампании означает, что показ объявлений заблокирован клиентом или менеджером Яндекса и не может быть включен автоматически.

Нет

StatusArchive

Отбирать кампании по признаку помещения в архив:

  • Yes — в архиве;
  • No — не в архиве;
  • CurrencyConverted — кампания автоматически заархивирована при переходе клиента на работу в валюте и не может быть разархивирована.

Нет

StatusActivating

Отбирать кампании по состоянию активизации:

  • Yes — активированные;
  • Pending — выполняется активизация.

Нет

StatusShow

Отбирать кампании по состоянию показа объявлений:

  • Yes — показ включен;
  • No — показ выключен.

Нет

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

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

{
   "data": [
      {  /* ShortCampaignInfo */
         "CampaignID": (int),
         "Login": (string),
         "Name": (string),
         "StartDate": (date),
         "StrategyName": (string),
         "ContextStrategyName": (string),
         "Sum": (float),
         "Rest": (float),
         "BonusDiscount": (float),
         "SumAvailableForTransfer": (float),
         "Currency": (string),         
         "Shows": (int),
         "Clicks": (int),
         "Status": (string),
         "StatusShow": (string),
         "StatusArchive": (string),
         "StatusActivating": (string),
         "StatusModerate": (string),
         "IsActive": (string),
         "ManagerName": (string),
         "AgencyName": (string),
         "CampaignCurrency": (string),
         "SourceCampaignID": (int),
         "DayBudgetEnabled": (string),
         "EnableRelatedKeywords": (string),
         "ExtendedAdTitleEnabled": (string)
      }
      ...
   ]
}

Ниже приведено описание параметров.

Параметр

Описание

Объект ShortCampaignInfo

CampaignID

Идентификатор кампании.

Для создания кампании задают 0, для изменения параметров существующей кампании указывают ее идентификатор.

Login

Логин владельца кампании (логин пользователя Яндекса, в пользу которого ведется рекламная кампания).

При создании кампании прямые рекламодатели указывают собственный логин в Яндексе, рекламные агентства — логин своего клиента. При получении параметров кампании возвращается логин главного представителя рекламодателя.

Name

Название кампании.

StrategyName

Стратегия на поиске. Ниже перечислены возможные значения.

  • 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); см. условия подключения стратегииусловия подключения стратегии в помощи Директа;
  • AverageClickPrice — стратегия “Средняя цена клика”“Average CPC” (обязательный параметр AveragePrice, дополнительный WeeklySumLimit);
  • WeeklyPacketOfClicks — стратегия “Недельный пакет кликов”“Weekly click package” (обязательный параметр ClicksPerWeek, дополнительные MaxPrice или AveragePrice);
  • AverageCPAOptimization — стратегия “Средняя цена конверсии”“Average CPA” (обязательные параметры AverageCPA и GoalID, дополнительные WeeklySumLimit и MaxPrice); см. условия подключения стратегииусловия подключения стратегии в помощи Директа;
  • ROIOptimization — стратегия “Средняя рентабельность инвестиций”“Average ROI” (обязательные параметры ReserveReturn, ROICoef, GoalID, дополнительные Profitability, WeeklySumLimit и MaxPrice); см. условия подключения стратегииусловия подключения стратегии в помощи Директа.

ContextStrategyName

Стратегия в Рекламной сети Яндекса. Ниже перечислены возможные значения.

  • ShowsDisabled — выключить показ объявлений в Рекламной сети Яндекса. Это возможно, только если показ не выключен на поиске.

Стратегии с ручным управлением ставками в Рекламной сети Яндекса:

  • Default — стратегия “Процент от цены на поиске”. Процент задают в параметре ContextPricePercent. Дополнительные параметры — ContextLimit и ContextLimitSum. Данная стратегия применяется для кампаний, которым стратегия не назначена явно.

  • MaximumCoverage — стратегия “Максимальный доступный охват”“Maximum audience coverage”. Ставки задают с помощью одного из методов: CreateOrUpdateBanners, SetAutoPrice (Live), UpdatePrices.

    Важно

    Стратегия MaximumCoverage не доступна, если на поиске выбрана любая автоматическая стратегия.

Автоматические стратегии в Рекламной сети Яндекса:

Важно

Автоматические стратегии в Рекламной сети доступны, только если на поиске выключен показ объявлений (стратегия ShowsDisabled).

  • WeeklyBudget — стратегия “Недельный бюджет: максимум кликов”“Weekly budget: maximum clicks” (обязательный параметр WeeklySumLimit, дополнительный MaxPrice);
  • CPAOptimizer — стратегия “Недельный бюджет: максимальная конверсия”“Weekly budget: maximum conversion rate” (обязательные параметры WeeklySumLimit и GoalID, дополнительный MaxPrice); см. условия подключения стратегииусловия подключения стратегии в помощи Директа;
  • AverageClickPrice — стратегия “Средняя цена клика”“Average CPC” (обязательный параметр AveragePrice, дополнительный WeeklySumLimit);
  • WeeklyPacketOfClicks — стратегия “Недельный пакет кликов”“Weekly click package” (обязательный параметр ClicksPerWeek, дополнительные MaxPrice или AveragePrice);
  • AverageCPAOptimization — стратегия “Средняя цена конверсии”“Average CPA” (обязательные параметры AverageCPA и GoalID, дополнительные WeeklySumLimit и MaxPrice); см. условия подключения стратегииусловия подключения стратегии в помощи Директа;
  • ROIOptimization — стратегия “Средняя рентабельность инвестиций”“Average ROI” (обязательные параметры ReserveReturn, ROICoef, GoalID, дополнительные Profitability, WeeklySumLimit и MaxPrice); см. условия подключения стратегииусловия подключения стратегии в помощи Директа.

StartDate

Начало показа объявлений, YYYY-MM-DD. Если не задана, используется дата создания кампании.

Дата может находиться в будущем. В этом случае показ объявлений начинается при наступлении указанной даты, если модератор одобрил объявления и внесены средства на баланс кампании.

Sum

Если у клиента подключен общий счет — сумма израсходованных средств за все время существования кампании.

Если общий счет не подключен — сумма средств, зачисленных на баланс кампании за время ее существования.

При значении Yes входного параметра CurrencySupported значение выражено в валюте кампании, указанной в результирующем параметре CampaignCurrency. В противном случае значение выражено в у. е.

Если возвращаемое значение конвертируется из валюты кампании в у. е., то оно округляется по математическим правилам с точностью до второго знака после запятой.

Если значение выражено в реальной валюте, оно не включает НДС.

Rest

Текущий баланс общего счета + сумма возврата на кампанию (если у рекламодателя подключен общий счет) или текущий баланс кампании (если общий счет не подключен).

Примечание

Сумма возврата средств за клики, признанные системой недобросовестными или ошибочными, может быть израсходована только в рамках этой же кампании.

При значении Yes входного параметра CurrencySupported значение выражено в валюте кампании, указанной в результирующем параметре CampaignCurrency. В противном случае значение выражено в у. е.

Если возвращаемое значение конвертируется из валюты кампании в у. е., то оно округляется по математическим правилам с точностью до второго знака после запятой.

Если значение выражено в реальной валюте, оно не включает НДС.

BonusDiscount

Скидочный бонус, пропорциональный текущему балансу. В настоящее время скидка не применяется.

SumAvailableForTransfer

Сумма, доступная для перевода с помощью метода TransferMoney. Возвращается только в случае, если общий счет не подключен. Может быть меньше баланса кампании.

При значении Yes входного параметра CurrencySupported значение выражено в валюте кампании, указанной в результирующем параметре CampaignCurrency. В противном случае значение выражено в у. е.

Если возвращаемое значение конвертируется из валюты кампании в у. е., то оно округляется по математическим правилам с точностью до второго знака после запятой.

Если значение выражено в реальной валюте, оно не включает НДС.

Currency

Валюта, в которой выражены денежные значения в ответе (ставки, бюджеты, статистика).

Возможные значения: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN. Если параметр отсутствует или равен NULL, подразумеваются условные единицы (у. е.).

Shows

Количество показов за время существования кампании.

Clicks

Количество кликов за время существования кампании.

Status

Статус кампании, например: “Идут показы”, “Ожидает оплаты”, “На модерации”, “Остановлена”, “Идут показы. Идет активизация”, “Кампания заархивирована” и другие.

StatusShow

Показ объявлений кампании включен — Yes/No. Включение и выключение выполняется методами StopCampaign и ResumeCampaign.

Разрешение показа на уровне кампании не означает, что объявления фактически показываются. Для этого необходимо выполнение и других условий: достаточный баланс средств, кампания и объявления проверены модератором, разрешен показ на уровне объявлений (метод ResumeBanners). Фактическому показу соответствует значение Yes в параметре IsActive.

StatusArchive

Состояние архивации кампании:

  • Yes — кампания помещена в архив;
  • No — кампания не в архиве;
  • Pending — происходит перенос кампании в архив либо возврат из архива;
  • CurrencyConverted — кампания автоматически заархивирована при переходе клиента на работу в валюте и не может быть разархивирована.

Перенос в архив выполняют с помощью метода ArchiveCampaign. Для возврата из архива служит метод UnArchiveCampaign.

StatusActivating

Состояние активизации кампании:

  • Yes — активизирована;
  • Pending — ожидается активизация.

StatusModerate

Результат проверки модератором:

  • Yes — модератор одобрил хотя бы одно объявление;
  • No — модератор отклонил все объявления;
  • New — объявления не отправлялись на проверку (статус кампании “Черновик”);
  • Pending — проводится проверка.

Для отправки на проверку служит метод ModerateBanners.

IsActive

Кампания активна, объявления показываются — Yes/No.

Под активностью понимается состояние кампании, при котором показ объявлений включается и выключается автоматически — в соответствии с настройками временного таргетинга или в зависимости от баланса кампании. Неактивность кампании означает, что показ объявлений заблокирован и не может быть включен автоматически.

ManagerName

Имя персонального менеджера в Яндексе. Заполняется автоматически для кампаний, обслуживаемых персональным менеджером.

AgencyName

Название рекламного агентства. Заполняется автоматически, если создателем кампании является агентство.

CampaignCurrency

Валюта, в которой ведется кампания.

Возможные значения: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN. Если параметр отсутствует или равен NULL, это означает, что кампания ведется в у. е.

SourceCampaignID

Идентификатор исходной кампании в у. е., если текущая кампания была создана автоматически при переходе клиента на работу в валюту. Отсутствует или равен NULL — в противном случае.

DayBudgetEnabled

Доступно ли управление дневным бюджетом кампании — Yes/No.

EnableRelatedKeywords

Авторасширение фразАвторасширение фраз включено — Yes/No.

ExtendedAdTitleEnabled

Подстановка части текста объявления в заголовок включена — Yes/No.

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

Python

{
   'Logins': ['agrom'],
   'Filter': {
      'IsActive': ['Yes'],
      'StatusShow': ['Yes']
   },
   'Limit': 20,
   'Offset': 1
}

PHP

array(
   'Logins' => array('agrom'),
   'Filter' => array(
      'IsActive' => array('Yes'),
      'StatusShow' => array('Yes')
   ),
   'Limit' => 20,
   'Offset' =1
)

Perl

{
   'Logins' => ['agrom'],
   'Filter' ={
      'IsActive' => ['Yes'],
      'StatusShow' => ['Yes']
   },
   'Limit' => 20,
   'Offset' =1
}
Предыдущая
GetCampaignsListFilter
Следующая
GetCampaignsParams