SetAutoPrice (Live)
Sets bids for keywords, or calculates them based on an algorithm.
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.
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).
- 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.
- 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.
Parameter | Description | Required |
AutoPriceInfo object | ||
---|---|---|
Mode | The value “SinglePrice”. | Yes |
CampaignID | The 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:
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 |
Parameter | Description | Required |
AutoPriceInfo object | ||
---|---|---|
Mode | The value “SinglePrice”. | Yes |
CampaignID | The 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:
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.
PriceBase ProcBase Bid calculation formula 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 or P13 value PremiumMin + PremiumMin × Proc / 100 diff PremiumMin + (Bid for P12 – PremiumMin) × Proc / 100 P12 value Bid for P12 + Bid for P12 × Proc / 100 diff Bid for P12 + (PremiumMax – Bid for P12) × Proc / 100 pmax or P11 value PremiumMax + PremiumMax × Proc / 100 diff PremiumMax PriceBase ProcBase Bid calculation formula 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 or P13 value PremiumMin + PremiumMin × Proc / 100 diff PremiumMin + (Bid for P12 – PremiumMin) × Proc / 100 P12 value Bid for P12 + Bid for P12 × Proc / 100 diff Bid for P12 + (PremiumMax – Bid for P12) × Proc / 100 pmax or P11 value PremiumMax + PremiumMax × Proc / 100 diff PremiumMax 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 ofPriceScope
+PriceScope
× Proc / 100The 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.
- 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.
Parameter | Description | Required |
AutoPriceInfo object | ||
---|---|---|
Mode | The value “Wizard”. | Yes |
CampaignID | The 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:
If omitted, Search is assumed. In any case, 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 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:
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:
| 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:
| 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 |
Parameter | Description | Required |
AutoPriceInfo object | ||
---|---|---|
Mode | The value “Wizard”. | Yes |
CampaignID | The 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:
If omitted, Search is assumed. In any case, 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 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:
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:
| 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:
| 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.
Parameter | Description |
PhrasePriceInfo object | |
---|---|
PhraseID | The keyword ID. |
BannerID | The ad ID. |
CampaignID | The 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. |
Parameter | Description |
PhrasePriceInfo object | |
---|---|
PhraseID | The keyword ID. |
BannerID | The ad ID. |
CampaignID | The 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
}