Документация
API версии 5. Руководство разработчика
API версии 5. Справочник

get

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

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

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

Ограничения

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

Запрос

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

{
  "method": "get",
  "params": { 
    "SelectionCriteria
[no-highlight[

Критерий отбора ключевых фраз и автотаргетингов.

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

Да

]no-highlight]
": { /* BidsSelectionCriteria */ "KeywordIds
[no-highlight[

Получить ставки или приоритеты для указанных ключевых фраз и автотаргетингов. Не более 10 000 элементов в массиве.

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

Один из параметров KeywordIds, AdGroupIds и CampaignIds (могут присутствовать все)

]no-highlight]
": [(long), ... ], "AdGroupIds
[no-highlight[

Получить ставки или приоритеты для ключевых фраз и автотаргетингов в указанных группах объявлений. От 1 до 1000 элементов в массиве.

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

Один из параметров KeywordIds, AdGroupIds и CampaignIds (могут присутствовать все)

]no-highlight]
": [(long), ... ], "CampaignIds
[no-highlight[

Получить ставки или приоритеты для ключевых фраз и автотаргетингов в указанных кампаниях. От 1 до 10 элементов в массиве.

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

Один из параметров KeywordIds, AdGroupIds и CampaignIds (могут присутствовать все)

]no-highlight]
": [(long), ... ], "ServingStatuses
[no-highlight[

Получить ставки или приоритеты для ключевых фраз и автотаргетингов с указанными статусами возможности показов группы. Описание статусов см. в разделе Статус возможности показов группы.

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

Нет

]no-highlight]
": [( "ELIGIBLE" | "RARELY_SERVED" ), ... ] }, /* required */ "FieldNames
[no-highlight[

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

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

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

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

Да

]no-highlight]
": [( "KeywordId" | ...
[no-highlight[

“KeywordId“ | “AdGroupId“ | “CampaignId“ | “ServingStatus“ | “Bid“ | “ContextBid“ | “StrategyPriority“ | “CompetitorsBids“ | “SearchPrices“ | “ContextCoverage“ | “MinSearchPrice“ | “CurrentSearchPrice“ | “AuctionBids“

]no-highlight]
| "AuctionBids" ), ... ], /* required */ "Page
[no-highlight[

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

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

Нет

]no-highlight]
": { /* 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Получить ставки или приоритеты для ключевых фраз и автотаргетингов с указанными статусами возможности показов группы. Описание статусов см. в разделе Статус возможности показов группы.Нет

Ответ

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

{
  "result": { 
    "Bids
[no-highlight[

Ставки и/или приоритеты.

]no-highlight]
": [{ /* BidGetItem */ "CampaignId
[no-highlight[

Идентификатор кампании, к которой относится ключевая фраза или автотаргетинг.

]no-highlight]
": (long), "AdGroupId
[no-highlight[

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

]no-highlight]
": (long), "KeywordId
[no-highlight[

Идентификатор ключевой фразы или автотаргетинга.

]no-highlight]
": (long), "ServingStatus
[no-highlight[

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

]no-highlight]
": ( "ELIGIBLE" | "RARELY_SERVED" ), "Bid
[no-highlight[

Ставка на поиске.

]no-highlight]
": (long), "ContextBid
[no-highlight[

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

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

]no-highlight]
": (long), "StrategyPriority
[no-highlight[

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

]no-highlight]
": ( "LOW" | "NORMAL" | "HIGH" ), /* nillable */ "CompetitorsBids
[no-highlight[

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

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

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

]no-highlight]
": [(long), ... ], "SearchPrices
[no-highlight[

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

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

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

]no-highlight]
": [{ /* SearchPrices */ "Position
[no-highlight[

Позиция показа на поиске:

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

]no-highlight]
": ( "PREMIUMFIRST" | "PREMIUMBLOCK" | "FOOTERFIRST" | "FOOTERBLOCK" ), "Price
[no-highlight[

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

]no-highlight]
": (long) }, ... ], "ContextCoverage
[no-highlight[

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

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

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

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

]no-highlight]
": { /* ContextCoverage */ "Items
[no-highlight[

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

]no-highlight]
": [{ /* ContextCoverageItem */ "Probability
[no-highlight[

Частота показа (доля аудитории) в сетях. Указывается в процентах от 0 до 100.

]no-highlight]
": (decimal), /* required */ "Price
[no-highlight[

Ставка в сетях, при которой прогнозируется указанная частота показа.

]no-highlight]
": (long) /* required */ }, ... ] }, /* nillable */ "MinSearchPrice
[no-highlight[

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

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

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

]no-highlight]
": (long), /* nillable */ "CurrentSearchPrice
[no-highlight[

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

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

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

]no-highlight]
": (long), /* nillable */ "AuctionBids
[no-highlight[

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

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

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

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

]no-highlight]
": [{ /* AuctionBidItem */ "Position
[no-highlight[

Позиция показа: Pmn, где

  • m — номер блока (1 — спецразмещение, 2 — блок гарантированных показов);
  • n — номер позиции в рамках блока.

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

]no-highlight]
": (string), "Bid
[no-highlight[

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

]no-highlight]
": (long), "Price
[no-highlight[

Списываемая цена для указанной позиции.

]no-highlight]
": (long) }, ... ] }, ... ], "LimitedBy
[no-highlight[

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

]no-highlight]
": (long) } }
Параметр Тип Описание
Структура result (для JSON) / GetResponse (для SOAP)
Bids array of BidGetItemСтавки и/или приоритеты.
LimitedBy longПорядковый номер последнего возвращенного объекта. Передается в случае, если количество объектов в ответе было ограничено лимитом. См. раздел Постраничная выборка.
Структура BidGetItem
CampaignId longИдентификатор кампании, к которой относится ключевая фраза или автотаргетинг.
AdGroupId longИдентификатор группы объявлений, к которой относится ключевая фраза или автотаргетинг.
KeywordId longИдентификатор ключевой фразы или автотаргетинга.
ServingStatus ServingStatusEnumСтатус возможности показов группы объявлений. Описание статусов см. в разделе Статус возможности показов группы.
Bid longСтавка на поиске.
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
[no-highlight[

Показы отключены

]no-highlight]
или NETWORK_DEFAULT
[no-highlight[

Ставка в сети устанавливается в зависимости от ставки на поиске

]no-highlight]
, возвращается null (nil).

Для автотаргетинга возвращается 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
      }
    ]
  }
}