get

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

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

Внимание

Все возвращаемые денежные значения представляют собой целые числа — результат умножения ставки или цены на 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)
`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": "NORMAL", /* 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	Приоритет ключевой фразы или автотаргетинга: NORMAL.
`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). Для автотаргетинга возвращается 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
      }
    ]
  }
}

Была ли статья полезна?

Bids: управление ставками

set