get
Возвращает ставки и приоритеты для ключевых фраз и автотаргетингов, отвечающих заданным критериям, а также данные, полезные при подборе ставок: данные аукциона по позициям показа на поиске и ставки для охвата различных долей аудитории в сетях.
Ставки или приоритеты можно получить независимо от того, какая стратегия выбрана в кампании — ручная или автоматическая.
Ограничения
Метод возвращает не более 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 | Позиция показа на поиске:
|
Price | long | Минимальная ставка за указанную позицию. |
Структура ContextCoverage | ||
Items | array of ContextCoverageItem | Ставки для данной фразы, позволяющие достичь охвата различных долей аудитории в сетях (прогноз). Служат ориентиром при подборе ставок. |
Структура ContextCoverageItem | ||
Probability | decimal | Частота показа (доля аудитории) в сетях. Указывается в процентах от 0 до 100. |
Price | long | Ставка в сетях, при которой прогнозируется указанная частота показа. |
Структура AuctionBidItem | ||
Position | string | Позиция показа: Pmn, где
Например, 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 | Позиция показа на поиске:
|
Price | long | Минимальная ставка за указанную позицию. |
Структура ContextCoverage | ||
Items | array of ContextCoverageItem | Ставки для данной фразы, позволяющие достичь охвата различных долей аудитории в сетях (прогноз). Служат ориентиром при подборе ставок. |
Структура ContextCoverageItem | ||
Probability | decimal | Частота показа (доля аудитории) в сетях. Указывается в процентах от 0 до 100. |
Price | long | Ставка в сетях, при которой прогнозируется указанная частота показа. |
Структура AuctionBidItem | ||
Position | string | Позиция показа: Pmn, где
Например, 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 } ] } }