get

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

Узнайте больше

Ограничения

Метод возвращает не более page-size объектов.

Запрос

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

{
  "method": "get",
  "params": { /* params */
    "SelectionCriteria": {  /* CampaignsSelectionCriteria */
      "Ids": [(long), ... ],
      "Types": [( "TEXT_CAMPAIGN" | "MOBILE_APP_CAMPAIGN" | "DYNAMIC_TEXT_CAMPAIGN" | "CPM_BANNER_CAMPAIGN" | "SMART_CAMPAIGN" | "UNIFIED_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" | "AttributionModel" | "PackageBiddingStrategy" | "CanBeUsedAsPackageBiddingStrategySource" | "NegativeKeywordSharedSetIds" ), ... ],
    "TextCampaignSearchStrategyPlacementTypesFieldNames": [ ( "SearchResults" | "ProductGallery" | "DynamicPlaces") ],
    "MobileAppCampaignFieldNames": [( "Settings" | "BiddingStrategy" | "PackageBiddingStrategy" | "CanBeUsedAsPackageBiddingStrategySource" | "NegativeKeywordSharedSetIds" ), ... ],
    "DynamicTextCampaignFieldNames": [( "CounterIds" | "Settings" | "PlacementTypes" | "BiddingStrategy" | "PriorityGoals" | "AttributionModel" "PackageBiddingStrategy" | "CanBeUsedAsPackageBiddingStrategySource" | "NegativeKeywordSharedSetIds" ), ... ],
    "DynamicTextCampaignSearchStrategyPlacementTypesFieldNames": [ ( "SearchResults" | "ProductGallery" | "DynamicPlaces") ], 
    "CpmBannerCampaignFieldNames": [( "CounterIds" | "FrequencyCap" | "VideoTarget" | "Settings" | "BiddingStrategy" ), ... ],
    "SmartCampaignFieldNames": [( "CounterId" | "Settings" | "BiddingStrategy" | "PriorityGoals" | "AttributionModel" "PackageBiddingStrategy" | "CanBeUsedAsPackageBiddingStrategySource" ), ... ],
    "UnifiedCampaignFieldNames" : [ ("CounterIds"|"Settings"|"BiddingStrategy"|"PriorityGoals"|"TrackingParams"|"AttributionModel"|"PackageBiddingStrategy"|"CanBeUsedAsPackageBiddingStrategySource") ],
    "UnifiedCampaignSearchStrategyPlacementTypesFieldNames" : [ ( "SearchResults" | "ProductGallery" | "DynamicPlaces" | "Maps" | "SearchOrganizationList" ) ],
    "UnifiedCampaignPackageBiddingStrategyPlatformsFieldNames": [ ( "SearchResult" | "ProductGallery" | "Maps" | "SearchOrganizationList" | "Network" | "DynamicPlaces" ) ],
    "Page": {  /* LimitOffset */
      "Limit": (long),
      "Offset": (long)
    }
  }
}

Параметр

Тип

Описание

Обязательный

Структура params (для JSON) / GetRequest (для SOAP)

SelectionCriteria

CampaignsSelectionCriteria

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

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

Нет

FieldNames

array of CampaignFieldEnum

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

Да

TextCampaignFieldNames

array of TextCampaignFieldEnum

Имена параметров кампании с типом “Текстово-графические объявления”, которые требуется получить. См. Тип кампании.

Примечание

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

Нет

TextCampaignSearchStrategyPlacementTypesFieldNames

array of TextCampaignSearchStrategyPlacementTypesFieldNames

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

Нет

MobileAppCampaignFieldNames

array of MobileAppCampaignFieldEnum

Имена параметров кампании с типом “Реклама мобильных приложений”, которые требуется получить. См. Тип кампании.

Примечание

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

Нет

DynamicTextCampaignFieldNames

array of DynamicTextCampaignFieldEnum

Имена параметров кампании с типом “Динамические объявления”, которые требуется получить. См. Тип кампании.

Примечание

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

Нет

DynamicTextCampaignSearchStrategyPlacementTypesFieldNames

array of DynamicTextCampaignSearchStrategyPlacementTypesFieldNames

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

Нет

CpmBannerCampaignFieldNames

array of CpmBannerCampaignFieldEnum

Имена параметров кампании с типом “Медийная кампания”, которые требуется получить. См. Тип кампании.

Примечание

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

Нет

SmartCampaignFieldNames

SmartCampaignFieldEnum

Имена параметров кампании с типом “Смарт-баннеры”, которые требуется получить. См. Тип кампании.

Примечание

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

Нет

UnifiedCampaignFieldNames

array of UnifiedCampaignFieldEnum

Имена параметров кампании с типом “Единая перфоманс кампания”, которые требуется получить. См. Тип кампании.

Примечание

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

Нет

UnifiedCampaignSearchStrategyPlacementTypesFieldNames

array of UnifiedCampaignSearchStrategyPlacementTypesFieldNames

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

Нет

UnifiedCampaignPackageBiddingStrategyPlatformsFieldNames

array of UnifiedCampaignPackageBiddingStrategyPlatformsFieldNames

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

Нет

Page

LimitOffset

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

Нет

Структура CampaignsSelectionCriteria

Ids

array of long

Отбирать кампании с указанными идентификаторами. Не более 1000 элементов в массиве.

Нет

Types

array of CampaignTypeEnum

Отбирать кампании с указанными типами. См. Тип кампании.

Нет

States

array of CampaignStateEnum

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

Нет

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" | "SMART_CAMPAIGN" | "UNIFIED_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 ...
      },
      "SmartCampaign": {  /* SmartCampaignGetItem */
        ... smart campaign params ...
      },
      "UnifiedCampaign": {  /* SmartCampaignGetItem */
        ... unified campaign params ...
      },
      "ClientInfo": (string), /* nillable */
      "Notification": {  /* Notification */ /* nillable */
        "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, nillable

Название клиента (до 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, nillable

Настройки 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.

SmartCampaign

SmartCampaignGetItem

Настройки для кампании с типом “Смарт-баннеры”. Описание структуры данных см. в разделе get: параметры SmartCampaign.

UnifiedCampaign

UnifiedCampaignGetItem

Настройки для кампании с типом “Единая перфоманс кампания”. Описание структуры данных см. в разделе get: параметры UnifiedCampaign.

Структура 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 — распределенный.

См. подраздел Средний дневной бюджет раздела “Ручное управление ставками”“Manual bid management” помощи Директа.

Структура Notification

SmsSettings

SmsSettings

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

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.

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

Нельзя задать для UnifiedCampaign.

WarningBalance

int

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

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

Нельзя задать для UnifiedCampaign.

SendAccountNews

YesNoEnum

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

SendWarnings

YesNoEnum

Отправлять ли уведомления по электронной почте. Значение по умолчанию — NO.

Нельзя задать для UnifiedCampaign.

Структура 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

Название рекламного агентства (для кампаний, обслуживаемых агентством).

Узнайте больше

Предыдущая
delete
Следующая
get: параметры TextCampaign