get

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

  1. Ограничения
  2. Запрос
  3. Ответ
  4. Примеры

Ставки или приоритеты можно получить независимо от того, какая стратегия выбрана в кампании — ручная или автоматическая.

Внимание. Все возвращаемые денежные значения представляют собой целые числа — результат умножения ставки или цены на 1 000 000.

Ограничения

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

Запрос

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

{
  "method": "get",
  "params": { /* params */
    "SelectionCriteria": {  /* BidsSelectionCriteria */
      "KeywordIds": [(long), ... ], 
      "AdGroupIds": [(long), ... ],
      "CampaignIds": [(long), ... ],
      "ServingStatuses": [( "ELIGIBLE" | "RARELY_SERVED" ), ... ]
    }, /* required */
    "FieldNames": [( "KeywordId" | ... | "AuctionBids" ), ... ], /* required */
    "Page": {  /* LimitOffset */
      "Limit": (long),
      "Offset": (long)
    }
  } 
}
Параметр Тип Описание Обязательный
Структура params (для JSON) / GetRequest (для SOAP)
SelectionCriteria BidsSelectionCriteria Критерий отбора ключевых фраз и автотаргетингов. Да
FieldNames array of BidFieldEnum

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

Не запрашивайте параметры CompetitorsBids, SearchPrices, MinSearchPrice, CurrentSearchPrice, AuctionBids, если в кампании отключены показы на поиске (стратегия на поиске SERVING_OFF).

Не запрашивайте параметр ContextCoverage, если в кампании отключены показы в сетях (стратегия в сетях SERVING_OFF).

Да
Page LimitOffset

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

Нет
Структура BidsSelectionCriteria
KeywordIds array of long Получить ставки или приоритеты для указанных ключевых фраз и автотаргетингов. Не более 10 000 элементов в массиве. Один из параметров KeywordIds, AdGroupIds и CampaignIds (могут присутствовать все)
AdGroupIds array of long Получить ставки или приоритеты для ключевых фраз и автотаргетингов в указанных группах объявлений. От 1 до 1000 элементов в массиве.
CampaignIds array of long Получить ставки или приоритеты для ключевых фраз и автотаргетингов в указанных кампаниях. От 1 до 10 элементов в массиве.
ServingStatuses array of ServingStatusEnum Получить ставки или приоритеты для ключевых фраз и автотаргетингов с указанными статусами возможности показов группы. Описание статусов см. в разделе Статус возможности показов группы. Нет
Параметр Тип Описание Обязательный
Структура params (для JSON) / GetRequest (для SOAP)
SelectionCriteria BidsSelectionCriteria Критерий отбора ключевых фраз и автотаргетингов. Да
FieldNames array of BidFieldEnum

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

Не запрашивайте параметры CompetitorsBids, SearchPrices, MinSearchPrice, CurrentSearchPrice, AuctionBids, если в кампании отключены показы на поиске (стратегия на поиске SERVING_OFF).

Не запрашивайте параметр ContextCoverage, если в кампании отключены показы в сетях (стратегия в сетях SERVING_OFF).

Да
Page LimitOffset

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

Нет
Структура BidsSelectionCriteria
KeywordIds array of long Получить ставки или приоритеты для указанных ключевых фраз и автотаргетингов. Не более 10 000 элементов в массиве. Один из параметров KeywordIds, AdGroupIds и CampaignIds (могут присутствовать все)
AdGroupIds array of long Получить ставки или приоритеты для ключевых фраз и автотаргетингов в указанных группах объявлений. От 1 до 1000 элементов в массиве.
CampaignIds array of long Получить ставки или приоритеты для ключевых фраз и автотаргетингов в указанных кампаниях. От 1 до 10 элементов в массиве.
ServingStatuses array of ServingStatusEnum Получить ставки или приоритеты для ключевых фраз и автотаргетингов с указанными статусами возможности показов группы. Описание статусов см. в разделе Статус возможности показов группы. Нет

Ответ

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

{
  "result": { /* result */
    "Bids": [{  /* BidGetItem */
      "CampaignId": (long),
      "AdGroupId": (long),
      "KeywordId": (long),
      "ServingStatus": ( "ELIGIBLE" | "RARELY_SERVED" ),
      "Bid": (long),
      "AutotargetingSearchBidIsAuto" : ("YES"|"NO"),
      "ContextBid": (long),
      "StrategyPriority": ( "LOW" | "NORMAL" | "HIGH" ), /* nillable */
      "CompetitorsBids": [(long), ... ], 
      "SearchPrices": [{  /* SearchPrices */
        "Position": ( "PREMIUMFIRST" | "PREMIUMBLOCK" | "FOOTERFIRST" | "FOOTERBLOCK" ),
        "Price": (long)
      }, ... ], 
      "ContextCoverage": {  /* ContextCoverage */
        "Items": [{  /* ContextCoverageItem */
          "Probability": (decimal), /* required */
          "Price": (long) /* required */
        }, ... ]
      }, /* nillable */
      "MinSearchPrice": (long), /* nillable */
      "CurrentSearchPrice": (long), /* nillable */       
      "AuctionBids": [{  /* AuctionBidItem */ 
        "Position": (string),
        "Bid": (long),
        "Price": (long)
      }, ... ]
    }, ... ],
    "LimitedBy": (long)
  }
}
Параметр Тип Описание
Структура result (для JSON) / GetResponse (для SOAP)
Bids array of BidGetItem Ставки и/или приоритеты.
LimitedBy long Порядковый номер последнего возвращенного объекта. Передается в случае, если количество объектов в ответе было ограничено лимитом. См. раздел Постраничная выборка.
Структура BidGetItem
CampaignId long Идентификатор кампании, к которой относится ключевая фраза или автотаргетинг.
AdGroupId long Идентификатор группы объявлений, к которой относится ключевая фраза или автотаргетинг.
KeywordId long Идентификатор ключевой фразы или автотаргетинга.
ServingStatus ServingStatusEnum Статус возможности показов группы объявлений. Описание статусов см. в разделе Статус возможности показов группы.
Bid long Ставка на поиске.
AutotargetingSearchBidIsAuto YesNoEnum Признак включения опции автоматической ставки.
ContextBid long

Ставка в сетях.

StrategyPriority PriorityEnum, nillable

Приоритет ключевой фразы или автотаргетинга: LOW, NORMAL или HIGH.

CompetitorsBids array of long

Массив минимальных ставок для данной фразы за все позиции в спецразмещении и в блоке гарантированных показов.

Если в группе объявлений мало показов (значение RARELY_SERVED параметра ServingStatus), параметр не возвращается.

Для автотаргетинга параметр не возвращается.

SearchPrices array of SearchPrices

Минимальные ставки для данной фразы за позиции показа на поиске.

Если в группе объявлений мало показов (значение RARELY_SERVED параметра ServingStatus), параметр не возвращается.

Для автотаргетинга параметр не возвращается.

ContextCoverage ContextCoverage, nillable

Ставки для данной фразы, позволяющие достичь охвата различных долей аудитории сетей (прогноз). Служат ориентиром при подборе ставок.

Если в группе объявлений мало показов (значение RARELY_SERVED параметра ServingStatus), возвращается null (nil).

Если в кампании выбрана стратегия показа в сетях SERVING_OFF или NETWORK_DEFAULT, возвращается null (nil).

Ограничение.

Параметр NETWORK_DEFAULT не поддерживается для ручной стратегии HIGHEST_POSITION.

Для автотаргетинга возвращается null (nil).

MinSearchPrice long, nillable

Минимальная ставка, установленная для рекламодателя, при которой возможен показ на поиске.

Если в группе объявлений мало показов (значение RARELY_SERVED параметра ServingStatus), возвращается null (nil).

Для автотаргетинга возвращается null (nil).

CurrentSearchPrice long, nillable

Текущая цена клика на поиске. Эта цена может быть списана при клике по объявлению на странице результатов поиска (по запросу, точно соответствующему ключевой фразе). Подробнее см. в разделе Расчет цены клика помощи Директа.

Если в группе объявлений мало показов (значение RARELY_SERVED параметра ServingStatus), возвращается null (nil).

Для автотаргетинга возвращается null (nil).

AuctionBids array of AuctionBidItem

Результаты торгов по фразе.

Если в группе только графические объявления, параметр не возвращается.

Если в группе объявлений мало показов (значение RARELY_SERVED параметра ServingStatus), параметр не возвращается.

Для автотаргетинга параметр не возвращается.

Структура SearchPrices
Position PositionEnum Позиция показа на поиске:
  • FOOTERBLOCK — минимальная ставка за 4-ю позицию в гарантии (вход в блок гарантированных показов);
  • FOOTERFIRST — минимальная ставка за 1-ю позицию в гарантии;
  • PREMIUMBLOCK — минимальная ставка за 4-ю позицию в спецразмещении (вход в спецразмещение);
  • PREMIUMFIRST — минимальная ставка за 1-ю позицию в спецразмещении.
Price long

Минимальная ставка за указанную позицию.

Структура ContextCoverage
Items array of ContextCoverageItem Ставки для данной фразы, позволяющие достичь охвата различных долей аудитории в сетях (прогноз). Служат ориентиром при подборе ставок.
Структура ContextCoverageItem
Probability decimal Частота показа (доля аудитории) в сетях. Указывается в процентах от 0 до 100.
Price long Ставка в сетях, при которой прогнозируется указанная частота показа.
Структура AuctionBidItem
Position string Позиция показа: Pmn, где
  • m — номер блока (1 — спецразмещение, 2 — блок гарантированных показов);
  • n — номер позиции в рамках блока.

Например, P12 — 2-я позиция в спецразмещении, P21 — 1-я позиция в блоке гарантированных показов.

Bid long Минимальная ставка за указанную позицию.
Price long Списываемая цена для указанной позиции.
Параметр Тип Описание
Структура result (для JSON) / GetResponse (для SOAP)
Bids array of BidGetItem Ставки и/или приоритеты.
LimitedBy long Порядковый номер последнего возвращенного объекта. Передается в случае, если количество объектов в ответе было ограничено лимитом. См. раздел Постраничная выборка.
Структура BidGetItem
CampaignId long Идентификатор кампании, к которой относится ключевая фраза или автотаргетинг.
AdGroupId long Идентификатор группы объявлений, к которой относится ключевая фраза или автотаргетинг.
KeywordId long Идентификатор ключевой фразы или автотаргетинга.
ServingStatus ServingStatusEnum Статус возможности показов группы объявлений. Описание статусов см. в разделе Статус возможности показов группы.
Bid long Ставка на поиске.
AutotargetingSearchBidIsAuto YesNoEnum Признак включения опции автоматической ставки.
ContextBid long

Ставка в сетях.

StrategyPriority PriorityEnum, nillable

Приоритет ключевой фразы или автотаргетинга: LOW, NORMAL или HIGH.

CompetitorsBids array of long

Массив минимальных ставок для данной фразы за все позиции в спецразмещении и в блоке гарантированных показов.

Если в группе объявлений мало показов (значение RARELY_SERVED параметра ServingStatus), параметр не возвращается.

Для автотаргетинга параметр не возвращается.

SearchPrices array of SearchPrices

Минимальные ставки для данной фразы за позиции показа на поиске.

Если в группе объявлений мало показов (значение RARELY_SERVED параметра ServingStatus), параметр не возвращается.

Для автотаргетинга параметр не возвращается.

ContextCoverage ContextCoverage, nillable

Ставки для данной фразы, позволяющие достичь охвата различных долей аудитории сетей (прогноз). Служат ориентиром при подборе ставок.

Если в группе объявлений мало показов (значение RARELY_SERVED параметра ServingStatus), возвращается null (nil).

Если в кампании выбрана стратегия показа в сетях SERVING_OFF или NETWORK_DEFAULT, возвращается null (nil).

Ограничение.

Параметр NETWORK_DEFAULT не поддерживается для ручной стратегии HIGHEST_POSITION.

Для автотаргетинга возвращается null (nil).

MinSearchPrice long, nillable

Минимальная ставка, установленная для рекламодателя, при которой возможен показ на поиске.

Если в группе объявлений мало показов (значение RARELY_SERVED параметра ServingStatus), возвращается null (nil).

Для автотаргетинга возвращается null (nil).

CurrentSearchPrice long, nillable

Текущая цена клика на поиске. Эта цена может быть списана при клике по объявлению на странице результатов поиска (по запросу, точно соответствующему ключевой фразе). Подробнее см. в разделе Расчет цены клика помощи Директа.

Если в группе объявлений мало показов (значение RARELY_SERVED параметра ServingStatus), возвращается null (nil).

Для автотаргетинга возвращается null (nil).

AuctionBids array of AuctionBidItem

Результаты торгов по фразе.

Если в группе только графические объявления, параметр не возвращается.

Если в группе объявлений мало показов (значение RARELY_SERVED параметра ServingStatus), параметр не возвращается.

Для автотаргетинга параметр не возвращается.

Структура SearchPrices
Position PositionEnum Позиция показа на поиске:
  • FOOTERBLOCK — минимальная ставка за 4-ю позицию в гарантии (вход в блок гарантированных показов);
  • FOOTERFIRST — минимальная ставка за 1-ю позицию в гарантии;
  • PREMIUMBLOCK — минимальная ставка за 4-ю позицию в спецразмещении (вход в спецразмещение);
  • PREMIUMFIRST — минимальная ставка за 1-ю позицию в спецразмещении.
Price long

Минимальная ставка за указанную позицию.

Структура ContextCoverage
Items array of ContextCoverageItem Ставки для данной фразы, позволяющие достичь охвата различных долей аудитории в сетях (прогноз). Служат ориентиром при подборе ставок.
Структура ContextCoverageItem
Probability decimal Частота показа (доля аудитории) в сетях. Указывается в процентах от 0 до 100.
Price long Ставка в сетях, при которой прогнозируется указанная частота показа.
Структура AuctionBidItem
Position string Позиция показа: Pmn, где
  • m — номер блока (1 — спецразмещение, 2 — блок гарантированных показов);
  • n — номер позиции в рамках блока.

Например, P12 — 2-я позиция в спецразмещении, P21 — 1-я позиция в блоке гарантированных показов.

Bid long Минимальная ставка за указанную позицию.
Price long Списываемая цена для указанной позиции.

Примеры

Пример запроса
{
  "method" : "get",
  "params" : {
    "SelectionCriteria" : {
      "KeywordIds" : [
        151289987,
        151289988,
        414808783,
        414808784,
        414808785,
        414811825,
        414811826,
        414811827,
        1574449505
      ]
    },
    "FieldNames" : [
      "KeywordId",
      "Bid",
      "ContextBid"
    ]
  }
}
Пример ответа
{
  "result" : {
    "Bids" : [
      {
        "KeywordId" : 414808783,
        "Bid" : 10000,
        "ContextBid" : 0
      },
      {
        "Bid" : 10000,
        "KeywordId" : 414808784,
        "ContextBid" : 0
      },
      {
        "Bid" : 10000,
        "KeywordId" : 414808785,
        "ContextBid" : 0
      },
      {
        "Bid" : 10000,
        "KeywordId" : 1574449505,
        "ContextBid" : 0
      }
    ]
  }
}