SetAutoPrice (Live)

Задает или рассчитывает по алгоритму ставки для фраз.

Внимание.

Метод отключен. Используйте API версии 5.

Информацию о соответствии методов в версиях Live 4 и 5 см. в Руководстве по переходу.

Если ни для одной фразы ставка не обновлена, метод возвращает сообщение об ошибке 244.

Изменения ставок вступают в силу спустя некоторое время, см. правила показа.

Ограничения

Не более 100 вызовов метода для одной кампании в сутки.

Внимание. Метод поддерживает только кампании с типом «Текстово-графические объявления». Для назначения ставок в кампаниях всех типов используйте сервис Bids API версии 5.

Новое в версии Live 4

Добавлены входные параметры BannerIDS и PhraseIDS.

Добавлен входной параметр BannersType.

Добавлены входные параметры Price и ContextPrice для способа SinglePrice.

Добавлен входной параметр DontWaitForPriceUpdate.

Добавлен входной параметр Currency и результирующий параметр Currency (см. также раздел Реальные валюты вместо у. е.).

Внимание.
  • Изменено поведение метода SetAutoPrice (Live): теперь метод не учитывает активность объявлений при обновлении ставок. Ставки обновляются для всех указанных объявлений или фраз, исключая те группы объявлений, в которых все объявления помещены в архив. В частности, ставки могут быть обновлены для объявлений-черновиков, находящихся на модерации, отклоненных на модерации, остановленных. Входной параметр BannersType игнорируется.
  • Параметр CampaignID стал обязательным.

Добавлена возможность рассчитывать ставки на поиске на основе минимальной ставки за второе место в спецразмещении.

Входные данные

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

Способ SinglePrice

Для всех фраз задается указанная ставка на поиске и указанная ставка в Рекламной сети Яндекса. Способ подходит для кампаний с малым количеством объявлений, фразы которых оцениваются примерно одинаково. В противном случае ставка может оказаться завышенной для одних фраз или заниженной для других.

Ниже показана структура входных данных в формате JSON.

{
   "method": "SetAutoPrice",
   "param": {
      /* AutoPriceInfo */
      "Mode": "SinglePrice",
      "CampaignID": (int),
      "BannerIDS": [
         (long)
         ...
      ],
      "PhraseIDS": [
         (long)
         ...
      ],
      "BannersType": (string),
      "SinglePrice": (float),
      "Price": (float),
      "ContextPrice": (float),
      "DontWaitForPriceUpdate": (string),
      "Currency": (string)
   }
}

Ниже приведено описание параметров.

Внимание.
  • Параметры BannerIDS и PhraseIDS являются взаимоисключающими — только один из них может присутствовать в запросе.
  • Если не указан ни один из параметров BannerIDS и PhraseIDS, ставки обновляются для всех фраз во всех объявлениях кампании.
Параметр Описание Требуется
Объект AutoPriceInfo
Mode Значение «SinglePrice». Да
CampaignID Идентификатор кампании, в которой требуется обновить ставки. Да
BannerIDS

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

Нет
PhraseIDS

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

Нет
BannersType

Отбирать объявления для обновления ставок. Параметр не используется, переданное значение игнорируется.

Нет
SinglePrice

Ставка на поиске и в Рекламной сети Яндекса.

Ограничение.

Параметр оставлен для совместимости со стабильной версией API. В версии Live 4 используются параметры Price и ContextPrice. При этом не допускается совместное использование параметра SinglePrice и любого из параметров Price и ContextPrice.

Либо SinglePrice, либо Price и ContextPrice
Price

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

Максимальное и минимальное значения представлены в таблице Валютные параметры и ограничения.

Если значение перед сохранением конвертируется из у. е. в валюту кампании, то оно округляется вверх с точностью до шага торгов в этой валюте (см. раздел Реальные валюты вместо у. е.). Если после конвертации в валюту кампании значение оказалось меньше минимальной или больше максимальной ставки в этой валюте, оно устанавливается равным минимальной или, соответственно, максимальной ставке.

Price или ContextPrice (могут присутствовать оба)
ContextPrice

Ставка в Рекламной сети Яндекса (в валюте, указанной в параметре Currency).

Параметр доступен для изменения в следующих случаях:

  1. Для Рекламной сети выбрана стратегия MaximumCoverage.

  2. Для Рекламной сети выбрана стратегия Default и фраза отключена на поиске за низкий CTR.

    Для новых фраз данное условие не актуально, поскольку фразы больше не отключаются за низкий CTR.

Максимальное и минимальное значения представлены в таблице Валютные параметры и ограничения.

Если значение перед сохранением конвертируется из у. е. в валюту кампании, то оно округляется вверх с точностью до шага торгов в этой валюте (см. раздел Реальные валюты вместо у. е.). Если после конвертации в валюту кампании значение оказалось меньше минимальной или больше максимальной ставки в этой валюте, оно устанавливается равным минимальной или, соответственно, максимальной ставке.

DontWaitForPriceUpdate

Вызов метода в асинхронном режиме — Yes/No. Если не задано, подразумевается No. При значении Yes результирующие данные будут содержать только идентификаторы фраз, объявлений и кампаний, а цены будут назначены несколько позднее.

Нет
Currency

Валюта, в которой указаны ставки.

Возможные значения: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN. Значение должно совпадать с валютой кампании.

Если параметр отсутствует или равен NULL, подразумеваются условные единицы (у. е.). В этом случае, если кампания ведется в реальной валюте, переданные приложением ставки перед сохранением конвертируются в реальную валюту (см. раздел Реальные валюты вместо у. е.).

Если значение отлично от NULL и не совпадает с валютой кампании (одной из кампаний), возвращается ошибка с кодом 245.

Нет

Способ Wizard

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

Параметры для расчета подбирают эмпирическим путем. Оптимальные параметры позволяют рассчитать ставки, которые гарантируют показ объявлений, обеспечивают запас конкурентоспособности и в то же время не приводят к перерасходу бюджета.

Расчет ставки на поиске (Price)

Для расчета ставки используются значения, переданные в параметрах PriceBase, Proc, ProcBase, MaxPrice.

PriceBase ProcBase Формула расчета ставки
min value Min + Min × Proc / 100
diff Min + (MaxMin) × Proc / 100
max value Max + Max × Proc / 100
diff Max + (PremiumMinMax) × Proc / 100
pmin или P13 value PremiumMin + PremiumMin × Proc / 100
diff PremiumMin + (Ставка за P12PremiumMin) × Proc / 100
P12 value Ставка за P12 + Ставка за P12 × Proc / 100
diff Ставка за P12 + (PremiumMaxСтавка за P12) × Proc / 100
pmax или P11 value PremiumMax + PremiumMax × Proc / 100
diff PremiumMax

Итоговая ставка ограничена параметром MaxPrice. Если рассчитанное значение превысило MaxPrice, ставка устанавливается равной MaxPrice.

Примечание. Со временем активность конкурентов может поднять цену позиции, и она превысит ставку. Чем выше надбавка, тем больше вероятность, что объявление будет показываться на выбранной позиции, но и выше возможные расходы.
Расчет ставки в Рекламной сети (ContextPrice)

Для расчета ставки используются значения, переданные в параметрах Scope, Proc, MaxPrice.

Если PriceScope — ставка, необходимая для охвата требуемой доли аудитории, то ставка составит

PriceScope + PriceScope × Proc / 100

Итоговая ставка ограничена параметром MaxPrice. Если рассчитанное значение превысило MaxPrice, ставка устанавливается равной MaxPrice.

Примечание. Расчет ставок по параметру Scope носит вероятностный характер и не гарантирует охвата требуемой доли аудитории. Расчет делается на основе статистических данных о том, при каких ставках достигается та или иная доля.
{
   "method": "SetAutoPrice",
   "param": {
      /* AutoPriceInfo */
      "Mode": "Wizard",
      "CampaignID": (int),
      "BannerIDS": [
         (long)
         ...
      ],
      "PhraseIDS": [
         (long)
         ...
      ],
      "BannersType": (string),
      "PhrasesType": (string),
      "UpdatePhrases": (string),
      "UpdateCategories": (string),
      "MaxPrice": (float),
      "PriceBase": (string),
      "Proc": (int),
      "ProcBase": (string),
      "Scope": (int),
      "DontWaitForPriceUpdate": (string),
      "Currency": (string)
   }
}

Ниже приведено описание параметров.

Внимание.
  • Параметры BannerIDS и PhraseIDS являются взаимоисключающими — только один из них может присутствовать в запросе.
  • Если не указан ни один из параметров BannerIDS и PhraseIDS, ставки обновляются для всех фраз во всех объявлениях кампании.
Параметр Описание Требуется
Объект AutoPriceInfo
Mode Значение «Wizard». Да
CampaignID Идентификатор кампании, в которой требуется обновить ставки. Да
BannerIDS

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

Нет
PhraseIDS

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

Нет
BannersType

Отбирать объявления для обновления ставок. Параметр не используется, переданное значение игнорируется.

Нет
PhrasesType

Указывает, какие ставки обновлять. Возможные значения:

  • Search — ставки на поиске (см. параметры PriceBase, Proc, ProcBase).
  • Network — ставки в Рекламной сети Яндекса (см. параметры Scope и Proc). Может задаваться, если для Рекламной сети выбрана стратегия с ручным управлением ставками — MaximumCoverage или Default.
    Внимание.

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

  • Both — и те и другие ставки.

Если не задано, подразумевается Search. Во всех случаях максимальная ставка ограничена параметром MaxPrice.

Нет
UpdatePhrases Рассчитывать ставки для фраз. Параметр не используется, переданное значение игнорируется. Нет
UpdateCategories Рассчитывать ставки для рубрик Яндекс.Каталога. Параметр не используется, переданное значение игнорируется. Нет
MaxPrice

Максимальная ставка (в валюте, указанной в параметре Currency).

Максимальное и минимальное значения представлены в таблице Валютные параметры и ограничения.

Если значение перед сохранением конвертируется из у. е. в валюту кампании, то оно округляется вверх с точностью до шага торгов в этой валюте (см. раздел Реальные валюты вместо у. е.). Если после конвертации в валюту кампании значение оказалось меньше минимальной или больше максимальной ставки в этой валюте, оно устанавливается равным минимальной или, соответственно, максимальной ставке.

Нет
PriceBase

Позиция на поиске, стоимость которой берется за основу для расчета ставок. Возможные значения:

  • min — 4-я позиция в блоке гарантированных показов;
  • max — 1-я позиция в блоке гарантированных показов;
  • pmin или P13 — 3-я позиция в спецразмещении;
  • P12 — 2-я позиция в спецразмещении;
  • pmax или P11 — 1-я позиция в спецразмещении.

К минимальной ставке за выбранную позицию прибавляется надбавка (см. параметры Proc и ProcBase).

При PhrasesType со значением Search или Both

Proc

Процент надбавки от 0 до 1000. Если не задан, надбавка не рассчитывается.

Надбавка влияет на расчет ставок для поиска и для Рекламной сети Яндекса:
  • для поиска надбавка считается от базы, указанной в ProcBase, а результат прибавляется к цене позиции, указанной в PriceBase.
  • для Рекламной сети на указанный процент увеличивается ставка, рассчитанная в соответствии с параметром Scope.
Нет
ProcBase

База для расчета надбавки. От нее берется процент, заданный в параметре Proc. Влияет только на расчет ставок для поиска.

Возможные значения:

  • value — цена позиции, выбранной в PriceBase.

  • diff — разница в цене двух позиций: выбранной в PriceBase и следующей (например, при выборе позиции min для расчета надбавки берется разница max-min).

    При выборе позиции pmax следующая позиция отсутствует и надбавка равна нулю. Это же верно при выборе позиции max, если стоимость следующей позиции pmin меньше (редкая, но возможная ситуация).

При PhrasesType со значением Search или Both и если задан Proc

Scope

Требуемая доля аудитории Рекламной сети Яндекса в процентах от 1 до 100. Влияет только на расчет ставок в Рекламной сети Яндекса.

К ставке, необходимой для охвата выбранной доли аудитории, прибавляется надбавка (см. параметр Proc).

При PhrasesType со значением Network или Both
DontWaitForPriceUpdate

Вызов метода в асинхронном режиме — Yes/No. Если не задано, подразумевается No. При значении Yes результирующие данные будут содержать только идентификаторы фраз, объявлений и кампаний, а цены будут назначены несколько позднее.

Нет
Currency

Валюта, в которой указаны ставки.

Возможные значения: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN. Значение должно совпадать с валютой кампании.

Если параметр отсутствует или равен NULL, подразумеваются условные единицы (у. е.). В этом случае, если кампания ведется в реальной валюте, переданные приложением ставки перед сохранением конвертируются в реальную валюту (см. раздел Реальные валюты вместо у. е.).

Если значение отлично от NULL и не совпадает с валютой кампании (одной из кампаний), возвращается ошибка с кодом 245.

Нет

Результирующие данные

Метод возвращает массив объектов PhrasePriceInfo. Каждый объект соответствует фразе, для которой обновлена ставка. Ниже показана структура результирующих данных в формате JSON.

{
   "data": [
      {  /* PhrasePriceInfo */
         "PhraseID": (long),
         "BannerID": (long),
         "CampaignID": (int),
         "Price": (float),
         "ContextPrice": (float),
         "AutoBroker": (string),
         "Currency": (string)
      }
      ...
   ]
}

Ниже приведено описание параметров.

Параметр Описание
Объект PhrasePriceInfo
PhraseID Идентификатор фразы.
BannerID Идентификатор объявления.
CampaignID Идентификатор кампании.
Price

Новая ставка на поиске Яндекса (в валюте, указанной в параметре Currency).

Если кампания ведется в реальной валюте, а ставка выражена в у. е., возвращаемое значение конвертируется из валюты кампании в у. е. и округляется вверх с точностью до шага торгов (0,01 у. е., см. также раздел Реальные валюты вместо у. е.).

ContextPrice

Новая ставка в Рекламной сети Яндекса (в валюте, указанной в параметре Currency).

Если кампания ведется в реальной валюте, а ставка выражена в у. е., возвращаемое значение конвертируется из валюты кампании в у. е. и округляется вверх с точностью до шага торгов (0,01 у. е., см. также раздел Реальные валюты вместо у. е.).

AutoBroker

Признак включенного автоброкера. Всегда содержит значение Yes.

Currency

Валюта, в которой выражены ставки.

Возможные значения: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN. Если параметр отсутствует или равен NULL, подразумеваются условные единицы (у. е.).

Примеры входных данных

Установить для указанных объявлений ставку, равную цене 1-го места + 30% от разницы до цены входа в спецразмещение, но не более 19,5 у. е.

Python

{
   'Mode': 'Wizard',
   'CampaignID': 1327944,
   'BannerIDS': [1974642, 20920155, 20155899, 64654],
   'PriceBase': 'max',
   'ProcBase': 'diff',
   'Proc': 30,
   'MaxPrice': 19.5
}

PHP

array(
   'Mode' => 'Wizard',
   'CampaignID' => 1327944,
   'BannerIDS' =>  array(1974642, 20920155, 20155899, 64654),
   'PriceBase' => 'max',
   'ProcBase' => 'diff',
   'Proc' => 30,
   'MaxPrice' => 19.5
)

Perl

{
   'Mode' => 'Wizard',
   'CampaignID' => 1327944,
   'BannerIDS' =>  [1974642, 20920155, 20155899, 64654],
   'PriceBase' => 'max',
   'ProcBase' => 'diff',
   'Proc' => 30,
   'MaxPrice' => 19.5
}