Документация
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) или в кампании выбрана стратегия показа в сетях 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[

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

Примечание. Если в группе объявлений мало показов (значение RARELY_SERVED параметра ServingStatus), возвращается null (nil).
]no-highlight]
": (long), /* nillable */ "CurrentSearchPrice
[no-highlight[

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

Примечание. Если в группе объявлений мало показов (значение RARELY_SERVED параметра ServingStatus), возвращается 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) или в кампании выбрана стратегия показа в сетях SERVING_OFF
[no-highlight[

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

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

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

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

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

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

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

Примечание. Если в группе объявлений мало показов (значение RARELY_SERVED параметра ServingStatus), возвращается 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
      }
    ]
  }
}