SetAutoPrice (Live)

Sets bids for keywords, or calculates them based on an algorithm.

Attention.

Disabled method. Use version 5 of the API.

For information about the compatibility of methods between versions Live 4 and 5, see the Migration guide.

If none of the keywords has an updated bid, the method returns the error message 244.

Bid changes take effect after some time. See the Ad Serving Rules.

Restrictions

No more than 100 method calls per campaign per day.

Attention. This method only supports campaigns with the “Text & Image Ads” type. For setting bids in all types of campaigns, use the Bids service in version 5 of the API.

New in the Live 4 version

Added the input parameters BannerIDS and PhraseIDS.

Added the BannersType input parameter.

Added the input parameters Price and ContextPrice for SinglePrice mode.

Added the DontWaitForPriceUpdate input parameter.

Added the Currency input parameter and the Currency output parameter (also see the section Real currencies instead of Yandex units).

Attention.
  • Changed the behavior of the SetAutoPrice (Live) method: now the method does not consider ad activity when updating bids. Bids are updated for all the specified ads or keywords, with the exception of those ad groups in which all the ads are archived. In particular, bids can be updated for ad drafts that are under moderation, rejected during moderation, and stopped. The BannersType input parameter is ignored.
  • The CampaignID parameter is now mandatory.

Added a feature for calculating bids for search based on the minimum bid for second position in Premium Placement.

Input data

The method provides two ways to update bids, which are named SinglePrice and Wizard. The first way sets the same bids for all keywords, and the second way calculates an individual bid for each keyword.

SinglePrice

All keywords share one bid that is specified for the search, and one bid that is specified for the Yandex Advertising Network. This mode is appropriate for campaigns with a small number of ads whose keywords are priced similarly. Otherwise, the bid may turn out to be inflated for some keywords and too low for others.

The input data structure in JSON is shown below.

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

Parameters are described below.

Attention.
  • The BannerIDS and PhraseIDS parameters are mutually exclusive; only one of them can be included in the request.
  • If neither of the BannerIDS or PhraseIDS parameters is set, bids are updated for all keywords in all the ads in the campaign.
ParameterDescriptionRequired
AutoPriceInfo object
ModeThe value “SinglePrice”.Yes
CampaignIDThe ID of the campaign to update bids in.Yes
BannerIDS

Array of ad IDs (no more than 1000). Bids are updated only for keywords that belong to the specified ads in the specified campaign. Ads that do not belong to the specified campaign are ignored.

No
PhraseIDS

Array of keyword IDs (no more than 2000). Bids are updated only for the specified keywords in the specified campaign. Keywords that do not belong to the specified campaign are ignored.

No
BannersType

Filter ads for updating bids. This parameter is not used, and the passed value is ignored.

No
SinglePrice

Bid on the search and in the Yandex Advertising Network.

Restriction.

This parameter was kept for compatibility with the stable version of the API. The Live 4 version uses the Price and ContextPrice parameters. However, it is not allowed to use the SinglePrice parameter in combination with either of the Price or ContextPrice parameters.

Use either SinglePrice, or Price and ContextPrice.
Price

Bid on Yandex search (in the currency specified in the Currency parameter). Used only if a strategy with manual bid management is selected for the campaign.

The maximum and minimum values are provided in the ../concepts/multicurrency_const.html#multicurrency_const__limits table.

If the value is converted from Yandex units to the campaign currency before saving, it is rounded up to the nearest bid increment in this currency (see the section Real currencies instead of Yandex units). If converting the value to the campaign's currency results in a value that is less than the minimum bid or more than the maximum bid for this currency, it is set to equal the minimum or maximum bid, respectively.

Price or ContextPrice (both may be present)
ContextPrice

Bid in the Yandex Advertising Network (in the currency specified in the Currency parameter).

The parameter is available for editing in the following cases:

  1. When the MaximumCoverage strategy is selected for the Yandex Advertising Network.

  2. When the Default strategy is selected for the Yandex Advertising Network and the keyword is disabled on the search due to a low CTR.

    For new keywords this condition is irrelevant, since keywords are no longer disabled for a low CTR.

The maximum and minimum values are provided in the ../concepts/multicurrency_const.html#multicurrency_const__limits table.

If the value is converted from Yandex units to the campaign currency before saving, it is rounded up to the nearest bid increment in this currency (see the section Real currencies instead of Yandex units). If converting the value to the campaign's currency results in a value that is less than the minimum bid or more than the maximum bid for this currency, it is set to equal the minimum or maximum bid, respectively.

DontWaitForPriceUpdate

Call the method asynchronously — Yes/No. If omitted, No is assumed. When the value is Yes, output data will contain only the IDs of keywords, ads, and campaigns, and prices will be determined later.

No
Currency

The currency that bids are shown in.

Acceptable values: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN. The value must match the campaign's currency.

If this parameter is omitted or NULL, Yandex units are used. In this case, if the campaign is run using real currency, the bids passed by the application are converted to the actual currency before saving (see the section Real currencies instead of Yandex units).

If the value is something other than NULL but it does not match the currency of the campaign or one of the campaigns, an error is returned with code 245.

No

Wizard mode

The bid is calculated separately for each keyword. The bid on search is based on the price of the desired display position (for example, the price for getting in Premium Placement). The bid in the Yandex Advertising Network is based on the price for the desired audience coverage. A markup is added to the base price.

Calculation parameters are formed empirically. The optimal parameters make it possible to calculate bids that guarantee ad impressions, provide a competitive margin, and at the same time prevent overspending the budget.

Calculating bids on search (Price)

The bid calculation uses the values passed in the PriceBase, Proc, ProcBase, and MaxPrice parameters.

PriceBaseProcBaseBid calculation formula
minvalueMin + Min × Proc / 100
diffMin + (MaxMin) × Proc / 100
maxvalueMax + Max × Proc / 100
diffMax + (PremiumMinMax) × Proc / 100
pmin or P13valuePremiumMin + PremiumMin × Proc / 100
diffPremiumMin + (Bid for P12PremiumMin) × Proc / 100
P12valueBid for P12 + Bid for P12 × Proc / 100
diffBid for P12 + (PremiumMaxBid for P12) × Proc / 100
pmax or P11valuePremiumMax + PremiumMax × Proc / 100
diffPremiumMax

The resulting bid is limited by the MaxPrice parameter. If the calculated value exceeds MaxPrice, the bid is set equal to MaxPrice.

Note. Over time, the activity of competitors may increase the price for the position and it may exceed the bid. The higher the markup, the more likely it is that the ad will be shown in the selected position, but expenses are also greater.
Calculating bids in the Yandex Advertising Network (ContextPrice)

The bid calculation uses the values passed in the Scope, Proc, and MaxPrice parameters.

If PriceScope is the bid needed for getting the desired audience coverage, the bid consists of

PriceScope + PriceScope × Proc / 100

The resulting bid is limited by the MaxPrice parameter. If the calculated value exceeds MaxPrice, the bid is set equal to MaxPrice.

Note. Calculating bids using the Scope parameter is based on probability, and does not guarantee the desired audience coverage. The calculation is based on statistical data about which bids produce various shares of audience coverage.
{
   "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)
   }
}

Parameters are described below.

Attention.
  • The BannerIDS and PhraseIDS parameters are mutually exclusive; only one of them can be included in the request.
  • If neither of the BannerIDS or PhraseIDS parameters is set, bids are updated for all keywords in all the ads in the campaign.
ParameterDescriptionRequired
AutoPriceInfo object
ModeThe value “Wizard”.Yes
CampaignIDThe ID of the campaign to update bids in.Yes
BannerIDS

Array of ad IDs (no more than 1000). Bids are updated only for keywords that belong to the specified ads in the specified campaign. Ads that do not belong to the specified campaign are ignored.

No
PhraseIDS

Array of keyword IDs (no more than 2000). Bids are updated only for the specified keywords in the specified campaign. Keywords that do not belong to the specified campaign are ignored.

No
BannersType

Filter ads for updating bids. This parameter is not used, and the passed value is ignored.

No
PhrasesType

Specifies which bids to update. Possible values:

  • Search — Bids on search (see the PriceBase, Proc, and ProcBase parameters).
  • Network — Bids in the Yandex Advertising Network (see the Scope and Proc parameters). It can be set if a strategy with manual bid management (MaximumCoverage or Default) is selected for the Yandex Advertising Network.
    Attention.

    For the Default strategy, bids in the Yandex Advertising Network are updated only for keywords that are disabled on the search due to a low CTR (bids in the Yandex Advertising Network are calculated automatically for keywords that are active on search).

  • Both — Both types of bids.

If omitted, Search is assumed. In any case, the maximum bid is limited by the MaxPrice parameter.

No
UpdatePhrasesCalculate bids for keywords. This parameter is not used, and the passed value is ignored.No
UpdateCategoriesCalculate bids for Yandex.Catalog categories. This parameter is not used, and the passed value is ignored.No
MaxPrice

Maximum bid (in the currency specified in the Currency parameter).

The maximum and minimum values are provided in the ../concepts/multicurrency_const.html#multicurrency_const__limits table.

If the value is converted from Yandex units to the campaign currency before saving, it is rounded up to the nearest bid increment in this currency (see the section Real currencies instead of Yandex units). If converting the value to the campaign's currency results in a value that is less than the minimum bid or more than the maximum bid for this currency, it is set to equal the minimum or maximum bid, respectively.

No
PriceBase

The position on search that is used as the base price for calculating bids. Possible values:

  • min — The 4th position in Guaranteed Placement.
  • max — The 1st position in Guaranteed Placement.
  • pmin or P13 — The 3rd position in Premium Placement.
  • P12 — The 2nd position in Premium Placement.
  • pmax or P11 — The 1st position in Premium Placement.

A markup is added to the minimum bid for the selected position (see the Proc and ProcBase parameters).

When PhrasesType has the value Search or Both

Proc

Markup percent from 0 to 1000. If omitted, markup is not calculated.

The markup affects bid calculation for the search and the Yandex Advertising Network:
  • For the search, markup is calculated from the base set in ProcBase, and the result is added to the price of the position set in PriceBase.
  • For the Yandex Advertising Network, the specified percent is added to the bid, which is calculated in accordance with the Scope parameter.
No
ProcBase

Base for calculating markup. It is used for getting the percent that is set in the Proc parameter. It only affects bid calculation for search.

Possible values:

  • value — The price of the position selected in PriceBase.

  • diff — The difference between the cost of two positions: the one selected in PriceBase and the next (for example, when the "min" position is selected, the difference of max-min is used for calculating markup).

    When the "pmax" position is selected, there is no next position, and the markup is zero. This is also true when the "max" position is selected, if the cost of the next "pmin" position is less (this is an unusual situation, but possible).

When PhrasesType has the value Search or Both and Proc is set

Scope

The desired audience coverage in the Yandex Advertising Network as a percentage from 1 to 100. Only affects bid calculation in the Yandex Advertising Network.

A markup is added to the bid that is needed to get the selected audience coverage (see the Proc parameter).

When PhrasesType has the value Network or Both
DontWaitForPriceUpdate

Call the method asynchronously — Yes/No. If omitted, No is assumed. When the value is Yes, output data will contain only the IDs of keywords, ads, and campaigns, and prices will be determined later.

No
Currency

The currency that bids are shown in.

Acceptable values: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN. The value must match the campaign's currency.

If this parameter is omitted or NULL, Yandex units are used. In this case, if the campaign is run using real currency, the bids passed by the application are converted to the actual currency before saving (see the section Real currencies instead of Yandex units).

If the value is something other than NULL but it does not match the currency of the campaign or one of the campaigns, an error is returned with code 245.

No

Output data

The method returns an array of PhrasePriceInfo objects. Each object corresponds to a keyword that has an updated bid. The output data structure in JSON is shown below.

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

Parameters are described below.

ParameterDescription
PhrasePriceInfo object
PhraseIDThe keyword ID.
BannerIDThe ad ID.
CampaignIDThe campaign ID.
Price

New bid on Yandex search (in the currency specified in the Currency parameter).

If the campaign is run in a real currency and the bid is in Yandex units, the returned value is converted from the campaign's currency to Yandex units and rounded up to the bid increment (0.01 Yandex units; also see the sectionReal currencies instead of Yandex units).

ContextPrice

New bid in the Yandex Advertising Network (in the currency specified in the Currency parameter).

If the campaign is run in a real currency and the bid is in Yandex units, the returned value is converted from the campaign's currency to Yandex units and rounded up to the bid increment (0.01 Yandex units; also see the sectionReal currencies instead of Yandex units).

AutoBroker

Indicates that Autobroker is enabled. Always contains the value Yes.

Currency

The currency that bids are shown in.

Acceptable values: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN. If this parameter is omitted or NULL, Yandex units are used.

Examples of input data

Set a bid for the specified ads that is equal to the first place price + 30% of the difference from the price for Premium Placement, but no more than 19.5 Yandex units.

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
}