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)
SelectionCriteriaBidsSelectionCriteriaКритерий отбора ключевых фраз и автотаргетингов.Да
FieldNamesarray of BidFieldEnum

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

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

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

Да
PageLimitOffset

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

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

Ответ

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

{
  "result": { /* result */
    "Bids": [{  /* BidGetItem */
      "CampaignId": (long),
      "AdGroupId": (long),
      "KeywordId": (long),
      "ServingStatus": ( "ELIGIBLE" | "RARELY_SERVED" ),
      "Bid": (long),
      "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)
Bidsarray of BidGetItemСтавки и/или приоритеты.
LimitedBylongПорядковый номер последнего возвращенного объекта. Передается в случае, если количество объектов в ответе было ограничено лимитом. См. раздел Постраничная выборка.
Структура BidGetItem
CampaignIdlongИдентификатор кампании, к которой относится ключевая фраза или автотаргетинг.
AdGroupIdlongИдентификатор группы объявлений, к которой относится ключевая фраза или автотаргетинг.
KeywordIdlongИдентификатор ключевой фразы или автотаргетинга.
ServingStatusServingStatusEnumСтатус возможности показов группы объявлений. Описание статусов см. в разделе Статус возможности показов группы.
BidlongСтавка на поиске.
ContextBidlong

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

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

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

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

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

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

SearchPricesarray of SearchPrices

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

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

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

ContextCoverageContextCoverage, nillable

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

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

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

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

MinSearchPricelong, nillable

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

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

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

CurrentSearchPricelong, nillable

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

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

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

AuctionBidsarray of AuctionBidItem

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

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

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

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

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

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

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

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

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

Примеры

Пример запроса
{
  "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
      }
    ]
  }
}