Документация
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 элементов в массиве.

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

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

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

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

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

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

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

“KeywordId“ | “AdGroupId“ | “CampaignId“ | “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Имена параметров верхнего уровня, которые требуется получить.Да
Page LimitOffset

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

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

Ответ

Структура ответа в формате 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), "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[

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

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

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

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

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

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

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

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

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

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

Примечание. Если в кампании выбрана стратегия показа в сетях SERVING_OFF или NETWORK_DEFAULT, возвращается 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[

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

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

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

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

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

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

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

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

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

]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Идентификатор ключевой фразы.
Bid longСтавка на поиске.
ContextBid longСтавка в сетях.
StrategyPriority PriorityEnum, nillableПриоритет фразы: LOW, NORMAL или HIGH.
CompetitorsBids array of longМассив минимальных ставок за все позиции в спецразмещении и в блоке гарантированных показов.
SearchPrices array of SearchPricesМинимальные ставки за позиции показа для данной фразы на поиске.
ContextCoverage ContextCoverage, nillable

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

Примечание. Если в кампании выбрана стратегия показа в сетях SERVING_OFF
[no-highlight[

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

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

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

]no-highlight]
, возвращается null (nil).
MinSearchPrice long, nillableМинимальная ставка, установленная для рекламодателя, при которой возможен показ на поиске.
CurrentSearchPrice long, nillable

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

AuctionBids array of AuctionBidItemРезультаты торгов по фразе.
Структура SearchPrices
Position PositionEnumПозиция показа на поиске:
  • FOOTERBLOCK — минимальная ставка за 4-ю позицию в гарантии (вход в блок гарантированных показов);
  • FOOTERFIRST — минимальная ставка за 1-ю позицию в гарантии;
  • PREMIUMBLOCK — минимальная ставка за 3-ю позицию в спецразмещении (вход в спецразмещение);
  • 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 — второе место в спецразмещении, P21 — первое место в блоке гарантированных показов.

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
      }
    ]
  }
}