GetCampaignsListFilter (Live)

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

Внимание.

Метод отключен. Используйте API версии 5.

Информацию о соответствии методов в версиях Live 4 и 5 см. в Руководстве по переходу.

Ограничения

Внимание. Метод возвращает только кампании с типом «Текстово-графические объявления». Для работы с кампаниями всех типов используйте сервис 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 — стратегия «Наивысшая доступная позиция»;
  • LowestCost — стратегия «Показ в блоке по минимальной цене»;
  • LowestCostPremium — стратегия «Показ в блоке по минимальной цене», но объявления показываются только в спецразмещении;
  • LowestCostGuarantee — стратегия «Показ под результатами поиска» (в нижнем блоке по наименьшей цене);
  • RightBlockHighest — стратегия «Показ под результатами поиска» (в нижнем блоке на наивысшей позиции, доступной при указанной ставке).

Автоматические стратегии на поиске:

  • WeeklyBudget — стратегия «Недельный бюджет: максимум кликов» (обязательный параметр WeeklySumLimit, дополнительный MaxPrice);
  • CPAOptimizer — стратегия «Недельный бюджет: максимальная конверсия» (обязательные параметры WeeklySumLimit и GoalID, дополнительный MaxPrice); см. условия подключения стратегии в помощи Директа;
  • AverageClickPrice — стратегия «Средняя цена клика» (обязательный параметр AveragePrice, дополнительный WeeklySumLimit);
  • WeeklyPacketOfClicks — стратегия «Недельный пакет кликов» (обязательный параметр ClicksPerWeek, дополнительные MaxPrice или AveragePrice);
  • AverageCPAOptimization — стратегия «Средняя цена конверсии» (обязательные параметры AverageCPA и GoalID, дополнительные WeeklySumLimit и MaxPrice); см. условия подключения стратегии в помощи Директа;
  • ROIOptimization — стратегия «Средняя рентабельность инвестиций» (обязательные параметры ReserveReturn, ROICoef, GoalID, дополнительные Profitability, WeeklySumLimit и MaxPrice); см. условия подключения стратегии в помощи Директа.
ContextStrategyName

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

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

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

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

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

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

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

Важно.

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

  • WeeklyBudget — стратегия «Недельный бюджет: максимум кликов» (обязательный параметр WeeklySumLimit, дополнительный MaxPrice);
  • CPAOptimizer — стратегия «Недельный бюджет: максимальная конверсия» (обязательные параметры WeeklySumLimit и GoalID, дополнительный MaxPrice); см. условия подключения стратегии в помощи Директа;
  • AverageClickPrice — стратегия «Средняя цена клика» (обязательный параметр AveragePrice, дополнительный WeeklySumLimit);
  • WeeklyPacketOfClicks — стратегия «Недельный пакет кликов» (обязательный параметр ClicksPerWeek, дополнительные MaxPrice или AveragePrice);
  • AverageCPAOptimization — стратегия «Средняя цена конверсии» (обязательные параметры AverageCPA и GoalID, дополнительные WeeklySumLimit и MaxPrice); см. условия подключения стратегии в помощи Директа;
  • ROIOptimization — стратегия «Средняя рентабельность инвестиций» (обязательные параметры 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
}