SetAutoPrice

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 4 and 5, see the Migration guide.

The SetAutoPrice (Live) version also exists for this method.

This method is used for campaigns with manual bid management strategies. For campaigns with automatic strategies, bids are calculated automatically, so it is not practical to set them using this method.

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.

Input data

The method can set bids in two different ways, called SinglePrice and Wizard. The first way sets the same bids for all keywords, and the second way calculates an individual bid for each keyword.

Input data for SinglePrice

The same bid is set for all keywords. This mode is appropriate for campaigns with a small number of ads whose keywords are priced similarly. Otherwise, the single bid may turn out to be inflated for some keywords and too low for others.

{
   "method": "SetAutoPrice",
   "param": {
      /* AutoPriceInfo */
      "CampaignID": (int),
      "Mode": "SinglePrice",
      "SinglePrice": (float)
   }
}

Parameters are described below.

Parameter Description Required
AutoPriceInfo object
CampaignID The campaign ID. Yes
Mode The value “SinglePrice”. Yes
SinglePrice

The bid to set for all phases in all ads.

Note. If the campaign has a strategy selected with different bid management on search and in the Yandex Advertising Network, the new bids apply to both the search and the Yandex Advertising Network.
Yes

Input data for Wizard

Bids are calculated for each keyword so that an ad is shown in a particular position and bids are not overly inflated. The calculation is based on the minimal CPC for the selected position. A markup is added to the minimal price, in the percentage set by the user. The result becomes the bid.

Note.

Over time, the activity of competitors may raise the minimal CPC and it may exceed the bid. For this reason, the higher the markup, the better competitive margin the ad has, but potential expenses are also higher.

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.

{
   "method": "SetAutoPrice",
   "param": {
      /* AutoPriceInfo */
      "CampaignID": (int),
      "Mode": "Wizard",
      "PhrasesType": (string),
      "UpdatePhrases": (string),
      "UpdateCategories": (string),
      "MaxPrice": (float),
      "PriceBase": (string),
      "ProcBase": (string),
      "Proc": (int),
      "Scope": (int)
   }
}

Parameters are described below.

Parameter Description Required
AutoPriceInfo object
CampaignID The campaign ID. Yes
Mode The value “Wizard”. Yes
PhrasesType

Filters keywords for calculating bids. Possible values:

  • Search — Keywords that are active on the search.
  • Network — Keywords that are disabled on the search due to a low CTR.
  • Both — All keywords.

If the parameter is omitted, Search is assumed.

For active keywords, bids are calculated using the PriceBase, ProcBase and Proc parameters; for disabled keywords, using the Scope and Proc parameter. In both cases, the maximum bid is limited by the MaxPrice parameter.

No
UpdatePhrases Calculate bids for keywords. This parameter is not used, and the passed value is ignored. No
UpdateCategories Calculate bids for keywords. This parameter is not used, and the passed value is ignored. No
MaxPrice Maximum bid (no more than 50 Yandex units). If omitted, the default limit is used: 50 Yandex units. No
PriceBase

The position where the ad should be placed. Possible values:

  • min — Lower block.
  • max — Top position in the lower block.
  • pmin — Premium Placement.
  • pmax — Top position in Premium Placement.

The cost of the selected position is used as a base for calculating bids. A markup is added to the cost of the position (see the Proc and ProcBase parameters).

If the value is set to "pmax", zero markup is added, and the final bid is equal to the cost of the top position in Premium Placement.

When PhrasesType has the value Search or Both

ProcBase

Base for calculating markup:

  • value — The cost of the position selected in ProcBase.

  • diff — The difference between the cost of two positions: the one selected in ProcBase and the next by cost (for example, when the "min" position is selected, the difference in 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

Proc

Markup percent from 0 to 1000. If not set, 0 is assumed.

For active keywords, markup is added to the base specified in ProcBase, and the result is added to the minimal price specified in PriceBase.

For disabled keywords, it increases the bid that is calculated in accordance with the Scope parameter.

No
Scope

The desired audience coverage in the Yandex Advertising Network as a percentage from 1 to 100. Used when calculating bids for keywords that are disabled on the search due to a low CTR. The bids that are received only apply to the Yandex Advertising Network.

The final bids are affected by the Proc parameter. If it is set, bids are increased by the specified percent.

Attention. Calculating bids using the Scope parameter is based on probability, and does not guarantee that the audience size will actually match the desired coverage. The calculation is based on statistical data about which bids produce various audience coverage.
When PhrasesType has the value Network or Both

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)
      }
      ...
   ]
}

Parameters are described below.

Parameter Description
PhrasePriceInfo object
PhraseID The keyword ID.
BannerID The ad ID.
CampaignID The campaign ID.
Price New bid. Calculated for active keywords.
ContextPrice New bid for the Yandex Advertising Network. Calculated for keywords that are disabled on the search due to a low CTR.
AutoBroker

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

Examples of input data

Python

Sets an identical price for all keywords in all ads in the campaign.

{
   'CampaignID': 1327944,
   'Mode':'SinglePrice',
   'SinglePrice': 4.35,
}

PHP

Calculates and sets prices for active keywords.

array(
   'CampaignID' => 1327944,
   'Mode' => 'Wizard',
   'PriceBase' => 'min',
   'ProcBase' => 'value',
   'Proc' => 14,
   'MaxPrice' => 9.5,
   'PhrasesType' => 'Search'
)

Perl

Calculates and sets prices for keywords that are disabled in the search due to a low CTR.

{
   'CampaignID' => 1327944,
   'Mode' => 'Wizard',
   'MaxPrice' => 9.5,
   'Scope' => 80,
   'PhrasesType' => 'Network'
}