get

Возвращает параметры кампаний, отвечающих заданным критериям.

  1. Ограничения
  2. Запрос
  3. Ответ
Внимание. Все денежные параметры кампаний (дневной бюджет, недельный бюджет, средняя цена для автоматических стратегий) передаются через API Директа в виде целых чисел. Передаваемое значение представляет собой денежное значение в валюте рекламодателя, умноженное на 1 000 000.

Ограничения

Метод возвращает не более 10 000 объектов.

Запрос

Структура запроса в формате JSON:

{
  "method": "get",
  "params": { /* params */
    "SelectionCriteria": {  /* CampaignsSelectionCriteria */
      "Ids": [(long), ... ],
      "Types": [( "TEXT_CAMPAIGN" | "MOBILE_APP_CAMPAIGN" | "DYNAMIC_TEXT_CAMPAIGN" | "CPM_BANNER_CAMPAIGN" ), ... ],
      "States": [( "ARCHIVED" | "CONVERTED" | "ENDED" | "OFF" | "ON" | "SUSPENDED" ), ... ],
      "Statuses": [( "ACCEPTED" | "DRAFT" | "MODERATION" | "REJECTED" ), ... ],
      "StatusesPayment": [( "DISALLOWED" | "ALLOWED" ), ... ]
    }, /* required */
    "FieldNames": [( "BlockedIps" | ... | "Type" ), ... ], /* required */
    "TextCampaignFieldNames": [( "CounterIds" | "RelevantKeywords" | "Settings" | "BiddingStrategy" | "PriorityGoals" ), ... ],
    "MobileAppCampaignFieldNames": [( "Settings" | "BiddingStrategy" ), ... ],
    "DynamicTextCampaignFieldNames": [( "CounterIds" | "Settings" | "BiddingStrategy" ), ... ]
    "CpmBannerCampaignFieldNames": [( "CounterIds" | "FrequencyCap" | "Settings" | "BiddingStrategy" ), ... ]
    "Page": {  /* LimitOffset */
      "Limit": (long),
      "Offset": (long)
    }
  }
}
Параметр Тип Описание Обяза-тельный
Структура params (для JSON) / GetRequest (для SOAP)
SelectionCriteria CampaignsSelectionCriteria

Критерий отбора кампаний.

Чтобы получить все кампании рекламодателя, необходимо указать пустой SelectionCriteria.

Да
FieldNames array of CampaignFieldEnum Имена параметров, общие для всех типов кампаний, которые требуется получить. Да
TextCampaignFieldNames array of TextCampaignFieldEnum Имена параметров кампании с типом «Текстово-графические объявления», которые требуется получить. См. Тип кампании.
Примечание. Если согласно SelectionCriteria отобрана кампания другого типа, параметры из TextCampaignFieldNames не возвращаются.
Нет
MobileAppCampaignFieldNames array of MobileAppCampaignFieldEnum Имена параметров кампании с типом «Реклама мобильных приложений», которые требуется получить. См. Тип кампании.
Примечание. Если согласно SelectionCriteria отобрана кампания другого типа, параметры из MobileAppCampaignFieldNames не возвращаются.
Нет
DynamicTextCampaignFieldNames array of DynamicTextCampaignFieldEnum Имена параметров кампании с типом «Динамические объявления», которые требуется получить. См. Тип кампании.
Примечание. Если согласно SelectionCriteria отобрана кампания другого типа, параметры из DynamicTextCampaignFieldNames не возвращаются.
Нет
CpmBannerCampaignFieldNames array of CpmBannerCampaignFieldEnum Имена параметров кампании с типом «Медийная кампания», которые требуется получить. См. Тип кампании.
Примечание. Если согласно SelectionCriteria отобрана кампания другого типа, параметры из CpmBannerCampaignFieldNames не возвращаются.
Нет
Page LimitOffset

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

Нет
Структура CampaignsSelectionCriteria
Ids array of long Отбирать кампании с указанными идентификаторами. Не более 1000 элементов в массиве. Нет
Types array of CampaignTypeEnum Отбирать кампании с указанными типами. См. Тип кампании. Нет
States array of CampaignStateEnum

Отбирать кампании с указанными состояниями. Описание состояний см. в разделе Статус и состояние кампании.

Примечание. Метод get возвращает кампанию в состоянии CONVERTED, только если в параметре States указано значение CONVERTED или в параметре Ids указан идентификатор этой кампании. Если параметры Ids и States оба не заданы, метод не возвращает кампании в состоянии CONVERTED.
Нет
Statuses array of CampaignStatusSelectionEnum Отбирать кампании с указанными статусами. Описание статусов см. в разделе Статус и состояние кампании. Нет
StatusesPayment array of CampaignStatusPaymentEnum Отбирать кампании с указанными статусами оплаты. Описание статусов см. в разделе Статус и состояние кампании. Нет

Ответ

Структура ответа в формате JSON:

{
  "result": { /* result */
    "Campaigns": [{  /* CampaignGetItem */
      "Id": (long),
      "Name": (string),
      "StartDate": (string),
      "Type": ( "TEXT_CAMPAIGN" | "MOBILE_APP_CAMPAIGN" |  "DYNAMIC_TEXT_CAMPAIGN" | "UNKNOWN" ),
      "Status": ( "ACCEPTED" | "DRAFT" | "MODERATION" | "REJECTED" | "UNKNOWN" ),
      "State": ( "ARCHIVED" | "CONVERTED" | "ENDED" | "OFF" | "ON" | "SUSPENDED" | "UNKNOWN" ),
      "StatusPayment": ( "DISALLOWED" | "ALLOWED" ),
      "StatusClarification": (string),
      "SourceId": (long), /* nillable */
      "Statistics": {  /* Statistics */
        "Clicks": (long), /* required */
        "Impressions": (long) /* required */
      },
      "Currency": ( "RUB" | ... | "USD" ),
      "Funds": {  /* FundsParam */
        "Mode": ( "CAMPAIGN_FUNDS" | "SHARED_ACCOUNT_FUNDS" ), /* required */
        "CampaignFunds": {  /* CampaignFundsParam */
          "Sum": (long), /* required */
          "Balance": (long), /* required */
          "BalanceBonus": (long), /* required */
          "SumAvailableForTransfer": (long)
        },
        "SharedAccountFunds": {  /* SharedAccountFundsParam */
          "Refund": (long),
          "Spend": (long)
        }
      },
      "RepresentedBy": {  /* CampaignAssistant */
        "Manager": (string), /* nillable */
        "Agency": (string) /* nillable */
      },
      "DailyBudget": {  /* DailyBudget */
        "Amount": (long), /* required */
        "Mode": ( "STANDARD" | "DISTRIBUTED" ) /* required */
      }, /* nillable */
      "EndDate": (string), /* nillable */
      "NegativeKeywords": {  /* ArrayOfString */
        "Items": [(string), ... ] /* required */
      }, /* nillable */
      "BlockedIps": {  /* ArrayOfString */
        "Items": [(string), ... ] /* required */
      }, /* nillable */
      "ExcludedSites": {  /* ArrayOfString */
        "Items": [(string), ... ] /* required */
      }, /* nillable */
      "TextCampaign": {  /* TextCampaignGetItem */
        ... text campaign params ...
      },
      "MobileAppCampaign": {  /* MobileAppCampaignGetItem */
        ... mobile app campaign params ...
      },
      "DynamicTextCampaign": {  /* DynamicTextCampaignGetItem */
        ... dynamic text campaign params ...
      },
      "CpmBannerCampaign": {  /* CpmBannerCampaignGetItem */
        ... cpm banner campaign params ...
      },
      "ClientInfo": (string),
      "Notification": {  /* Notification */
        "SmsSettings": {  /* SmsSettings */
          "Events": [( "MONITORING" | ... | "FINISHED" ), ... ],
          "TimeFrom": (string),
          "TimeTo": (string)
        },
        "EmailSettings": {  /* EmailSettings */
          "Email": (string),
          "CheckPositionInterval": (int),
          "WarningBalance": (int),
          "SendAccountNews": ( "YES" | "NO" ),
          "SendWarnings": ( "YES" | "NO" )
        }
      },
      "TimeTargeting": {  /* TimeTargeting */
        "Schedule": {  /* ArrayOfString */
          "Items": [(string), ... ] /* required */
        },
        "ConsiderWorkingWeekends": ( "YES" | "NO" ), /* required */
        "HolidaysSchedule": {  /* TimeTargetingOnPublicHolidays */
          "SuspendOnHolidays": ( "YES" | "NO" ), /* required */
          "BidPercent": (int),
          "StartHour": (int),
          "EndHour": (int)
        } /* nillable */
      },
      "TimeZone": (string)
    }, ... ],
    "LimitedBy": (long)
  }
}
Параметр Тип Описание
Структура result (для JSON) / GetResponse (для SOAP)
Campaigns array of CampaignGetItem Кампании.
LimitedBy long Порядковый номер последнего возвращенного объекта. Передается в случае, если количество объектов в ответе было ограничено лимитом. См. раздел Постраничная выборка.
Структура CampaignGetItem
Id long Идентификатор кампании.
Name string Название кампании (до 255 символов).
ClientInfo string Название клиента (до 255 символов). Значение по умолчанию — наименование из настроек рекламодателя.
StartDate string

Дата начала показов объявлений в формате YYYY-MM-DD. Должна быть не меньше текущей даты.

Показы объявлений начинаются в 00:00 по московскому времени (независимо от значения параметра TimeZone). На время начала показов влияют настройки временного таргетинга (параметр TimeTargeting).

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

EndDate string, nillable Дата окончания показов объявлений в формате YYYY-MM-DD. Показы объявлений прекращаются в 24:00 по московскому времени (независимо от значения параметра TimeZone).
TimeTargeting TimeTargeting Настройки временного таргетинга и почасовой корректировки ставок. Указываются по времени часового пояса, указанного в параметре TimeZone.
TimeZone string

Часовой пояс в месте нахождения рекламодателя. Справочник часовых поясов можно получить с помощью метода Dictionaries.get.

Значение по умолчанию Europe/Moscow.

NegativeKeywords ArrayOfString, nillable

Массив минус-фраз, общих для всех ключевых фраз кампании.

Ограничение. Для кампаний с типом «Медийная кампания» параметр не поддерживается.

Минус-фразу следует указывать без минуса перед первым словом.

Не более 7 слов в минус-фразе. Длина каждого слова — не более 35 символов. Суммарная длина минус-фраз в массиве — 20000 символов. Пробелы, дефисы и операторы не учитываются в суммарной длине.

BlockedIps ArrayOfString, nillable Массив IP-адресов, которым не нужно показывать объявления. Не более 25 элементов в массиве.
ExcludedSites ArrayOfString, nillable

Массив мест показа, где не нужно показывать объявления:

  • доменные имена сайтов;

  • идентификаторы мобильных приложений (bundle ID для iOS, package name для Android);

  • наименования внешних сетей (SSP). Список наименований можно получить с помощью метода Dictionaries.get.

Не более 1000 элементов в массиве. Не более 255 символов в каждом элементе массива.

DailyBudget DailyBudget, nillable

Настройки дневного бюджета кампании.

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

Notification Notification Настройки SMS- и email-уведомлений.
Type CampaignTypeGetEnum Тип кампании. См. Тип кампании.
Status StatusEnum Статус кампании. См. Статус и состояние кампании.
State CampaignStateGetEnum Состояние кампании. См. Статус и состояние кампании.
StatusPayment CampaignStatusPaymentEnum Статус оплаты кампании. Описание статусов оплаты см. в разделе Статус и состояние кампании.
StatusClarification string Текстовое пояснение к статусу.
SourceId long, nillable Идентификатор исходной кампании в у. е., если текущая кампания была создана автоматически при переходе рекламодателя на работу в валюту.
Statistics Statistics Статистика показов и кликов за время существования кампании.
Currency CurrencyEnum

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

Справочник валют можно получить с помощью метода Dictionaries.get.

Funds FundsParam Финансовые показатели кампании.
RepresentedBy CampaignAssistant Персональный менеджер в Яндексе или агентство, обслуживающее кампанию.
TextCampaign TextCampaignGetItem Настройки для кампании с типом «Текстово-графические объявления». Описание структуры данных см. в разделе get: параметры TextCampaign.
MobileAppCampaign MobileAppCampaignGetItem Настройки для кампании с типом «Реклама мобильных приложений». Описание структуры данных см. в разделе get: параметры MobileAppCampaign.
DynamicTextCampaign DynamicTextCampaignGetItem Настройки для кампании с типом «Динамические объявления». Описание структуры данных см. в разделе get: параметры DynamicTextCampaign.
CpmBannerCampaign CpmBannerCampaignGetItem Настройки для кампании с типом «Медийная кампания». Описание структуры данных см. в разделе get: параметры CpmBannerCampaign.
Структура TimeTargeting
Schedule ArrayOfString

Настройки временного таргетинга и почасовой корректировки ставок. Не более 7 элементов в массиве.

Каждый элемент массива содержит 25 чисел, разделенных запятыми. Первое число — номер дня недели: от 1 (понедельник) до 7 (воскресенье). Следующие 24 числа — последовательность коэффициентов к ставке для показа объявлений в соответствующие часы. Коэффициенты указываются в процентах от 0 до 200, значение должно быть кратно 10. Коэффициент 0 означает, что объявления в этот час не показываются. Пример элемента массива: 1,0,0,50,50,100,100,150,200,200,150,100,100,80,70,100,100,100,50,50,40,30,0,0,0

Примечание.
  • Если в массиве не указан элемент, соответствующий дню недели, то для этого дня все коэффициенты устанавливаются равными 100.
  • Если выбрана автоматическая стратегия показа, коэффициент 0 означает запрет показов, а любой другой коэффициент означает разрешение показов (то есть эквивалентен 100).
ConsiderWorkingWeekends YesNoEnum

Менять ли расписание показов при переносе рабочего дня на субботу или воскресенье.

Например, если рабочий день перенесен с понедельника на субботу, при значении YES в рабочую субботу пойдут показы по расписанию понедельника, а в нерабочий понедельник, — по расписанию субботы.

HolidaysSchedule TimeTargetingOnPublicHolidays, nillable

Настройки показа в праздничные дни.

Если часовой пояс, указанный в параметре TimeZone, относится к России, Украине, Беларуси, Казахстану или Турции, то используется календарь праздников и переносов рабочих дней соответствующей страны. В остальных случаях используется российский календарь.

Структура TimeTargetingOnPublicHolidays
SuspendOnHolidays YesNoEnum

Останавливать ли объявления в праздничные нерабочие дни: YES — останавливать, NO — не останавливать.

Примечание. Параметры BidPercent, StartHour и EndHour допускается задавать только при значении NO параметра SuspendOnHolidays.
BidPercent int Коэффициент к ставке при показе в праздничные нерабочие дни. Указывается в процентах от 10 до 200, значение должно быть кратно 10.
StartHour int Время (в часах) начала показов в праздничные нерабочие дни. От 0 до 23.
EndHour int Время (в часах) окончания показов в праздничные нерабочие дни. От 1 до 24.
Структура DailyBudget
Amount long

Дневной бюджет кампании в валюте рекламодателя, умноженный на 1 000 000.

Минимальный дневной бюджет для каждой валюты представлен в справочнике валют. Справочник валют можно получить с помощью метода Dictionaries.get.

Mode DailyBudgetModeEnum

Режим показа объявлений:

  • STANDARD — стандартный.
  • DISTRIBUTED — распределенный.

См. подраздел Средний дневной бюджет раздела «Ручное управление ставками» помощи Директа.

Структура Notification
SmsSettings SmsSettings

Настройки отправки SMS-уведомлений. Телефонный номер для отправки берется из профиля рекламодателя на Яндексе (см. раздел Мои телефоны помощи Яндекс.Паспорта).

EmailSettings EmailSettings Настройки отправки уведомлений по электронной почте.
Структура SmsSettings
Events array of SmsEventsEnum
События, о которых необходимо информировать по SMS:
  • MONITORING — остановка и возобновление показов объявлений мониторингом доступности сайта по данным Метрики;
  • MODERATION — объявления приняты или отклонены модерацией;
  • MONEY_IN — поступление средств на баланс кампании (не используется при подключенном общем счете);
  • MONEY_OUT — исчерпание средств на балансе кампании (не используется при подключенном общем счете);
  • FINISHED — окончание кампании.
TimeFrom string

Время, начиная с которого разрешено отправлять SMS о событиях, связанных с кампанией. Указывается в формате HH:MM, минуты задают кратно 15 (0, 15, 30, 45). Например, 19:45.

Значение по умолчанию 9:00.

TimeTo string

Время, до которого разрешено отправлять SMS о событиях, связанных с кампанией. Указывается в формате HH:MM, минуты задают кратно 15 (0, 15, 30, 45). Например, 19:45.

Значение по умолчанию 21:00.

Структура EmailSettings
Email string

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

Значение по умолчанию — адрес рекламодателя.

CheckPositionInterval int

Периодичность проверки прогноза трафика — 15, 30 или 60 минут. Значение по умолчанию — 60.

Уведомление отправляется, если прогноз трафика стал ниже того, который обеспечивала ставка на момент установки.

WarningBalance int

Минимальный баланс, при уменьшении до которого отправляется уведомление. Задается в процентах от суммы последнего платежа, от 1 до 50. Значение по умолчанию — 20.

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

SendAccountNews YesNoEnum

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

SendWarnings YesNoEnum Отправлять ли уведомления по электронной почте. Значение по умолчанию — NO.
Структура Statistics
Impressions long Количество показов за время существования кампании.
Clicks long Количество кликов за время существования кампании.
Структура FundsParam
Mode CampaignFundsEnum

Тип финансовых показателей кампании:

  • CAMPAIGN_FUNDS — общий счет не подключен, финансовые показатели кампании возвращаются в дочерней структуре CampaignFund;
  • SHARED_ACCOUNT_FUNDS — общий счет подключен, финансовые показатели кампании возвращаются в дочерней структуре SharedAccountFund.
CampaignFunds CampaignFundsParam Финансовые показатели кампании, в случае если общий счет не подключен.
SharedAccountFunds SharedAccountFundsParam Финансовые показатели кампании, в случае если общий счет подключен.
Структура CampaignFundsParam
Sum long Сумма средств, зачисленных на баланс кампании за время ее существования, в валюте рекламодателя, без НДС.
Balance long Текущий баланс кампании в валюте рекламодателя, без НДС.
BalanceBonus long Скидочный бонус. Параметр утратил актуальность.
SumAvailableForTransfer long Сумма, доступная для переноса на другую кампанию, в валюте рекламодателя, без НДС.
Структура SharedAccountFundsParam
Refund long Параметр утратил актуальность, всегда возвращается значение 0.
Spend long Сумма средств, израсходованных по данной кампании за все время ее существования, без НДС.
Структура CampaignAssistant
Manager string, nillable Имя персонального менеджера в Яндексе (для кампаний, обслуживаемых персональным менеджером).
Agency string, nillable Название рекламного агентства (для кампаний, обслуживаемых агентством).