SetAutoPrice (Live)
Задает или рассчитывает по алгоритму ставки для фраз.
Метод отключен. Используйте API версии 5.
Информацию о соответствии методов в версиях Live 4 и 5 см. в Руководстве по переходу.
Если ни для одной фразы ставка не обновлена, метод возвращает сообщение об ошибке 244.
Изменения ставок вступают в силу спустя некоторое время, см. правила показа.
Ограничения
Не более 100 вызовов метода для одной кампании в сутки.
Новое в версии 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). Используется, только если для кампании выбрана стратегия с ручным управлением ставками. Максимальное и минимальное значения представлены в таблице ../concepts/multicurrency_const.html#multicurrency_const__limits. Если значение перед сохранением конвертируется из у. е. в валюту кампании, то оно округляется вверх с точностью до шага торгов в этой валюте (см. раздел Реальные валюты вместо у. е.). Если после конвертации в валюту кампании значение оказалось меньше минимальной или больше максимальной ставки в этой валюте, оно устанавливается равным минимальной или, соответственно, максимальной ставке. | Price или ContextPrice (могут присутствовать оба) |
ContextPrice | Ставка в Рекламной сети Яндекса (в валюте, указанной в параметре Currency). Параметр доступен для изменения в следующих случаях:
Максимальное и минимальное значения представлены в таблице ../concepts/multicurrency_const.html#multicurrency_const__limits. Если значение перед сохранением конвертируется из у. е. в валюту кампании, то оно округляется вверх с точностью до шага торгов в этой валюте (см. раздел Реальные валюты вместо у. е.). Если после конвертации в валюту кампании значение оказалось меньше минимальной или больше максимальной ставки в этой валюте, оно устанавливается равным минимальной или, соответственно, максимальной ставке. | |
DontWaitForPriceUpdate | Вызов метода в асинхронном режиме — Yes/No. Если не задано, подразумевается No. При значении Yes результирующие данные будут содержать только идентификаторы фраз, объявлений и кампаний, а цены будут назначены несколько позднее. | Нет |
Currency | Валюта, в которой указаны ставки. Возможные значения: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN. Значение должно совпадать с валютой кампании. Если параметр отсутствует или равен NULL, подразумеваются условные единицы (у. е.). В этом случае, если кампания ведется в реальной валюте, переданные приложением ставки перед сохранением конвертируются в реальную валюту (см. раздел Реальные валюты вместо у. е.). Если значение отлично от NULL и не совпадает с валютой кампании (одной из кампаний), возвращается ошибка с кодом 245. | Нет |
Параметр | Описание | Требуется |
Объект AutoPriceInfo | ||
---|---|---|
Mode | Значение «SinglePrice». | Да |
CampaignID | Идентификатор кампании, в которой требуется обновить ставки. | Да |
BannerIDS | Массив идентификаторов объявлений (не более 1000). Ставки обновляются только для фраз, принадлежащих указанным объявлениям в указанной кампании. Объявления, не относящиеся к указанной кампании, игнорируются. | Нет |
PhraseIDS | Массив идентификаторов фраз (не более 2000). Ставки обновляются только для указанных фраз в указанной кампании. Фразы, не принадлежащие указанной кампании, игнорируются. | Нет |
BannersType | Отбирать объявления для обновления ставок. Параметр не используется, переданное значение игнорируется. | Нет |
SinglePrice | Ставка на поиске и в Рекламной сети Яндекса. Ограничение. Параметр оставлен для совместимости со стабильной версией API. В версии Live 4 используются параметры Price и ContextPrice. При этом не допускается совместное использование параметра SinglePrice и любого из параметров Price и ContextPrice. | Либо SinglePrice, либо Price и ContextPrice |
Price | Ставка на поиске Яндекса (в валюте, указанной в параметре Currency). Используется, только если для кампании выбрана стратегия с ручным управлением ставками. Максимальное и минимальное значения представлены в таблице ../concepts/multicurrency_const.html#multicurrency_const__limits. Если значение перед сохранением конвертируется из у. е. в валюту кампании, то оно округляется вверх с точностью до шага торгов в этой валюте (см. раздел Реальные валюты вместо у. е.). Если после конвертации в валюту кампании значение оказалось меньше минимальной или больше максимальной ставки в этой валюте, оно устанавливается равным минимальной или, соответственно, максимальной ставке. | Price или ContextPrice (могут присутствовать оба) |
ContextPrice | Ставка в Рекламной сети Яндекса (в валюте, указанной в параметре Currency). Параметр доступен для изменения в следующих случаях:
Максимальное и минимальное значения представлены в таблице ../concepts/multicurrency_const.html#multicurrency_const__limits. Если значение перед сохранением конвертируется из у. е. в валюту кампании, то оно округляется вверх с точностью до шага торгов в этой валюте (см. раздел Реальные валюты вместо у. е.). Если после конвертации в валюту кампании значение оказалось меньше минимальной или больше максимальной ставки в этой валюте, оно устанавливается равным минимальной или, соответственно, максимальной ставке. | |
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 + (Max – Min) × Proc / 100 max value Max + Max × Proc / 100 diff Max + (PremiumMin – Max) × Proc / 100 pmin или P13 value PremiumMin + PremiumMin × Proc / 100 diff PremiumMin + (Ставка за P12 – PremiumMin) × Proc / 100 P12 value Ставка за P12 + Ставка за P12 × Proc / 100 diff Ставка за P12 + (PremiumMax – Ставка за P12) × Proc / 100 pmax или P11 value PremiumMax + PremiumMax × Proc / 100 diff PremiumMax PriceBase ProcBase Формула расчета ставки min value Min + Min × Proc / 100 diff Min + (Max – Min) × Proc / 100 max value Max + Max × Proc / 100 diff Max + (PremiumMin – Max) × Proc / 100 pmin или P13 value PremiumMin + PremiumMin × Proc / 100 diff PremiumMin + (Ставка за P12 – PremiumMin) × 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. Во всех случаях максимальная ставка ограничена параметром MaxPrice. | Нет |
UpdatePhrases | Рассчитывать ставки для фраз. Параметр не используется, переданное значение игнорируется. | Нет |
UpdateCategories | Рассчитывать ставки для рубрик Яндекс Каталога. Параметр не используется, переданное значение игнорируется. | Нет |
MaxPrice | Максимальная ставка (в валюте, указанной в параметре Currency). Максимальное и минимальное значения представлены в таблице ../concepts/multicurrency_const.html#multicurrency_const__limits. Если значение перед сохранением конвертируется из у. е. в валюту кампании, то оно округляется вверх с точностью до шага торгов в этой валюте (см. раздел Реальные валюты вместо у. е.). Если после конвертации в валюту кампании значение оказалось меньше минимальной или больше максимальной ставки в этой валюте, оно устанавливается равным минимальной или, соответственно, максимальной ставке. | Нет |
PriceBase | Позиция на поиске, стоимость которой берется за основу для расчета ставок. Возможные значения:
К минимальной ставке за выбранную позицию прибавляется надбавка (см. параметры Proc и ProcBase). | При PhrasesType со значением Search или Both |
Proc | Процент надбавки от 0 до 1000. Если не задан, надбавка не рассчитывается. Надбавка влияет на расчет ставок для поиска и для Рекламной сети Яндекса:
| Нет |
ProcBase | База для расчета надбавки. От нее берется процент, заданный в параметре Proc. Влияет только на расчет ставок для поиска. Возможные значения:
| При 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. | Нет |
Параметр | Описание | Требуется |
Объект AutoPriceInfo | ||
---|---|---|
Mode | Значение «Wizard». | Да |
CampaignID | Идентификатор кампании, в которой требуется обновить ставки. | Да |
BannerIDS | Массив идентификаторов объявлений (не более 1000). Ставки обновляются только для фраз, принадлежащих указанным объявлениям в указанной кампании. Объявления, не относящиеся к указанной кампании, игнорируются. | Нет |
PhraseIDS | Массив идентификаторов фраз (не более 2000). Ставки обновляются только для указанных фраз в указанной кампании. Фразы, не принадлежащие указанной кампании, игнорируются. | Нет |
BannersType | Отбирать объявления для обновления ставок. Параметр не используется, переданное значение игнорируется. | Нет |
PhrasesType | Указывает, какие ставки обновлять. Возможные значения:
Если не задано, подразумевается Search. Во всех случаях максимальная ставка ограничена параметром MaxPrice. | Нет |
UpdatePhrases | Рассчитывать ставки для фраз. Параметр не используется, переданное значение игнорируется. | Нет |
UpdateCategories | Рассчитывать ставки для рубрик Яндекс Каталога. Параметр не используется, переданное значение игнорируется. | Нет |
MaxPrice | Максимальная ставка (в валюте, указанной в параметре Currency). Максимальное и минимальное значения представлены в таблице ../concepts/multicurrency_const.html#multicurrency_const__limits. Если значение перед сохранением конвертируется из у. е. в валюту кампании, то оно округляется вверх с точностью до шага торгов в этой валюте (см. раздел Реальные валюты вместо у. е.). Если после конвертации в валюту кампании значение оказалось меньше минимальной или больше максимальной ставки в этой валюте, оно устанавливается равным минимальной или, соответственно, максимальной ставке. | Нет |
PriceBase | Позиция на поиске, стоимость которой берется за основу для расчета ставок. Возможные значения:
К минимальной ставке за выбранную позицию прибавляется надбавка (см. параметры Proc и ProcBase). | При PhrasesType со значением Search или Both |
Proc | Процент надбавки от 0 до 1000. Если не задан, надбавка не рассчитывается. Надбавка влияет на расчет ставок для поиска и для Рекламной сети Яндекса:
| Нет |
ProcBase | База для расчета надбавки. От нее берется процент, заданный в параметре Proc. Влияет только на расчет ставок для поиска. Возможные значения:
| При 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, подразумеваются условные единицы (у. е.). |
Параметр | Описание |
Объект 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
}