setAuto
The automatic bid constructor calculates bids for keywords based on the selected algorithm.
The method sets bids in asynchronous mode and does not return bids. Use the get method to get bids.
A bid can be set only if a manual strategy is selected in the campaign.
The method doesn't reset the automatic bid value (AutotargetingSearchBidIsAuto).
If an item in the input array contains bids that are not appropriate for the strategy, these bids are not applied.
- If the campaign has an automatic strategy selected, an error is returned.
- If displays in search results are disabled in the campaign and the Scope parameter has only the SEARCH parameter, an error is returned. If both values are passed (SEARCH and NETWORK), bids are only updated in ad networks and a warning is displayed.
- If the campaign has a manual strategy in search results, an error is returned if this campaign doesn't have independent bid management in ad networks, or if displays are disabled in ad networks but the Scope parameter only has the NETWORK value. If both values are passed (SEARCH and NETWORK), bids are only updated in search results and a warning is displayed.
Bids and prices are passed via the Yandex Direct API as integer numbers. The value passed is a bid or price multiplied by 1,000,000.
All bids and prices are shown in the advertiser's currency.
To set bids in search results, pass the value SEARCH in the Scope parameter.
The bid calculation uses the values passed in the Position, IncreasePercent, CalculateBy, and MaxBid parameters.
Position | CalculateBy | Bid calculation formula |
---|---|---|
FOOTERBLOCK | VALUE | Minimum bid for 4th position in Guaranteed + minimum bid for 4th position in Guaranteed × IncreasePercent / 100, but no greater than MaxBid |
DIFF | Minimum bid for 4th position in Guaranteed + (minimum bid for 1st position – minimum bid for 4th position in Guaranteed) × IncreasePercent / 100, but no greater than MaxBid | |
FOOTERFIRST | VALUE | Minimum bid for 1st position in Guaranteed + minimum bid for 1st position in Guaranteed × IncreasePercent / 100, but no greater than MaxBid |
DIFF | Minimum bid for 1st position in Guaranteed + (minimum bid for 3rd position in Premium – minimum bid for 1st position in Guaranteed) × IncreasePercent / 100, but no greater than MaxBid | |
PREMIUMBLOCK or P14 | VALUE | Minimum bid for 4th position in Premium + minimum bid for 4th position in Premium × IncreasePercent / 100, but no greater than MaxBid |
DIFF | Minimum bid for 4th position in Premium + (minimum bid for 3rd position in Premium – minimum bid for 4th position in Premium) × IncreasePercent / 100, but no greater than MaxBid | |
P13 | VALUE | Minimum bid for 3rd position in Premium + minimum bid for 3rd position in Premium × IncreasePercent / 100, but no greater than MaxBid |
DIFF | Minimum bid for 3rd position in Premium + (minimum bid for 2nd position in Premium – minimum bid for 3rd position in Premium) × IncreasePercent / 100, but no greater than MaxBid | |
P12 | VALUE | Minimum bid for 2nd position in Premium + minimum bid for 2nd position in Premium × IncreasePercent / 100, but no greater than MaxBid |
DIFF | Minimum bid for 2nd position in Premium + (minimum bid for 1st position in Premium – minimum bid for 2nd position in Premium) × IncreasePercent / 100, but no greater than MaxBid | |
PREMIUMFIRST or P11 | VALUE | Minimum bid for 1st position in Premium + minimum bid for 1st position in Premium × IncreasePercent / 100, but no greater than MaxBid |
DIFF | Minimum bid for 1st position in Premium, but no greater than MaxBid |
Position | CalculateBy | Bid calculation formula |
---|---|---|
FOOTERBLOCK | VALUE | Minimum bid for 4th position in Guaranteed + minimum bid for 4th position in Guaranteed × IncreasePercent / 100, but no greater than MaxBid |
DIFF | Minimum bid for 4th position in Guaranteed + (minimum bid for 1st position – minimum bid for 4th position in Guaranteed) × IncreasePercent / 100, but no greater than MaxBid | |
FOOTERFIRST | VALUE | Minimum bid for 1st position in Guaranteed + minimum bid for 1st position in Guaranteed × IncreasePercent / 100, but no greater than MaxBid |
DIFF | Minimum bid for 1st position in Guaranteed + (minimum bid for 3rd position in Premium – minimum bid for 1st position in Guaranteed) × IncreasePercent / 100, but no greater than MaxBid | |
PREMIUMBLOCK or P14 | VALUE | Minimum bid for 4th position in Premium + minimum bid for 4th position in Premium × IncreasePercent / 100, but no greater than MaxBid |
DIFF | Minimum bid for 4th position in Premium + (minimum bid for 3rd position in Premium – minimum bid for 4th position in Premium) × IncreasePercent / 100, but no greater than MaxBid | |
P13 | VALUE | Minimum bid for 3rd position in Premium + minimum bid for 3rd position in Premium × IncreasePercent / 100, but no greater than MaxBid |
DIFF | Minimum bid for 3rd position in Premium + (minimum bid for 2nd position in Premium – minimum bid for 3rd position in Premium) × IncreasePercent / 100, but no greater than MaxBid | |
P12 | VALUE | Minimum bid for 2nd position in Premium + minimum bid for 2nd position in Premium × IncreasePercent / 100, but no greater than MaxBid |
DIFF | Minimum bid for 2nd position in Premium + (minimum bid for 1st position in Premium – minimum bid for 2nd position in Premium) × IncreasePercent / 100, but no greater than MaxBid | |
PREMIUMFIRST or P11 | VALUE | Minimum bid for 1st position in Premium + minimum bid for 1st position in Premium × IncreasePercent / 100, but no greater than MaxBid |
DIFF | Minimum bid for 1st position in Premium, but no greater than MaxBid |
You can only set the bid in ad networks for strategies that allow separate management of bids in search results and ad networks.
To set bids in ad networks, pass the value NETWORK in the Scope parameter.
Bid calculation uses the values passed in the parameters ContextCoverage, IncreasePercent, and MaxBid.
Bid calculation formula:
Bid predicted to produce the specified impression frequency + bid predicted to produce the specified impression frequency × IncreasePercent / 100,
but not more than MaxBid.
Restrictions
A single request can only set bids for the same type of objects — either for campaigns only, or for groups only, or for keywords only. The method doesn't support setting the bid for autotargeting separately.
- campaigns — maximum of 10
- groups — maximum of 1000
- keywords — maximum of 10,000
Request
Request structure in JSON format:
{
"method": "setAuto",
"params": { /* params */
"Bids": [{ /* BidSetAutoItem */
"CampaignId": (long),
"AdGroupId": (long),
"KeywordId": (long),
"MaxBid": (long),
"Position": ( "PREMIUMFIRST" | "PREMIUMBLOCK" | "FOOTERFIRST" | "FOOTERBLOCK" | "P11" | "P12" | "P13" | "P14" | "P21" | "P22" | "P23" | "P24" ),
"IncreasePercent": (int),
"CalculateBy": ( "VALUE" | "DIFF" ),
"ContextCoverage": (int),
"Scope": [( "SEARCH" | "NETWORK" ), ... ] /* required */
}, ... ] /* required */
}
}
Parameter | Type | Description | Required |
Params structure (for JSON) / SetAutoRequest structure (for SOAP) | |||
---|---|---|---|
Bids | array of BidSetAutoItem | Bid calculation parameters | Yes |
BidSetAutoItem structure | |||
CampaignId | long | The campaign ID. Specified when updating the bid for all the campaign's keywords. | Either CampaignId, AdGroupId, or KeywordId |
AdGroupId | long | ID of the ad group. Specified when the bid needs to be updated for all the group's keywords. | |
KeywordId | long | The keyword ID. Specified when updating the bid for an individual keyword. Restriction. The autotargeting ID is not allowed. | |
Scope | array of ScopeEnum | Specifies which bids to set. The array may contain the following elements (one or both):
| Yes |
MaxBid | long | Limit on the bid, multiplied by 1,000,000. Integer. Specified in the advertiser's currency. Constraints are listed in the currencies dictionary. To get it, use the Dictionaries.get method and specify the Currencies dictionary name in the request. | No |
Position | PositionEnum | The display position whose bid is used as the basis for calculating bids in search results. A markup is added to the bid for the selected position (see the IncreasePercent and CalculateBy parameters). | If the Scope array has the Search value |
IncreasePercent | int | Markup percent from 0 to 1000. If omitted, markup is not calculated. | No |
CalculateBy | CalculateByEnum | The base for calculating the markup:
| If the Scope array has the Search value and the IncreasePercent parameter is set |
ContextCoverage | int | The frequency of impressions (the audience coverage) in ad networks. Indicated as a percentage from 0 to 100. A markup is added to the bid that is needed to get the selected audience coverage (see the IncreasePercent parameter). | If the Scope array has the Network value |
Parameter | Type | Description | Required |
Params structure (for JSON) / SetAutoRequest structure (for SOAP) | |||
---|---|---|---|
Bids | array of BidSetAutoItem | Bid calculation parameters | Yes |
BidSetAutoItem structure | |||
CampaignId | long | The campaign ID. Specified when updating the bid for all the campaign's keywords. | Either CampaignId, AdGroupId, or KeywordId |
AdGroupId | long | ID of the ad group. Specified when the bid needs to be updated for all the group's keywords. | |
KeywordId | long | The keyword ID. Specified when updating the bid for an individual keyword. Restriction. The autotargeting ID is not allowed. | |
Scope | array of ScopeEnum | Specifies which bids to set. The array may contain the following elements (one or both):
| Yes |
MaxBid | long | Limit on the bid, multiplied by 1,000,000. Integer. Specified in the advertiser's currency. Constraints are listed in the currencies dictionary. To get it, use the Dictionaries.get method and specify the Currencies dictionary name in the request. | No |
Position | PositionEnum | The display position whose bid is used as the basis for calculating bids in search results. A markup is added to the bid for the selected position (see the IncreasePercent and CalculateBy parameters). | If the Scope array has the Search value |
IncreasePercent | int | Markup percent from 0 to 1000. If omitted, markup is not calculated. | No |
CalculateBy | CalculateByEnum | The base for calculating the markup:
| If the Scope array has the Search value and the IncreasePercent parameter is set |
ContextCoverage | int | The frequency of impressions (the audience coverage) in ad networks. Indicated as a percentage from 0 to 100. A markup is added to the bid that is needed to get the selected audience coverage (see the IncreasePercent parameter). | If the Scope array has the Network value |
Response
Response structure in JSON format:
{
"result": { /* result */
"SetAutoResults": [{ /* BidActionResult */
"Warnings": [{ /* ExceptionNotification */
"Code": (int), /* required */
"Message": (string), /* required */
"Details": (string)
}, ... ],
"Errors": [{ /* ExceptionNotification */
"Code": (int), /* required */
"Message": (string), /* required */
"Details": (string)
}, ... ],
"CampaignId": (long),
"AdGroupId": (long),
"KeywordId": (long)
}, ... ]
}
}
Parameter | Type | Description |
Result structure (for JSON) / SetAutoResponse structure (for SOAP) | ||
---|---|---|
SetAutoResults | array of BidActionResult | Results of setting bids and/or priorities. |
BidActionResult structure | ||
CampaignId | long | The campaign ID. Returned if there aren't any errors, if it was specified in the request. See Operations on object arrays. |
AdGroupId | long | ID of the ad group. Returned if there aren't any errors, if it was specified in the request. See Operations on object arrays. |
KeywordId | long | Keyword ID. Returned if there aren't any errors, if it was specified in the request. See Operations on object arrays. |
Warnings | array of ExceptionNotification | Warnings that occurred during the operation. |
Errors | array of ExceptionNotification | Errors that occurred during the operation. |
Parameter | Type | Description |
Result structure (for JSON) / SetAutoResponse structure (for SOAP) | ||
---|---|---|
SetAutoResults | array of BidActionResult | Results of setting bids and/or priorities. |
BidActionResult structure | ||
CampaignId | long | The campaign ID. Returned if there aren't any errors, if it was specified in the request. See Operations on object arrays. |
AdGroupId | long | ID of the ad group. Returned if there aren't any errors, if it was specified in the request. See Operations on object arrays. |
KeywordId | long | Keyword ID. Returned if there aren't any errors, if it was specified in the request. See Operations on object arrays. |
Warnings | array of ExceptionNotification | Warnings that occurred during the operation. |
Errors | array of ExceptionNotification | Errors that occurred during the operation. |
Examples
- Request example
-
Set the price in search results of the 1st position in Guaranteed + 50% of the difference from Premium, but no greater than 0.25.
{ "method" : "setAuto", "params" : { "Bids" : [ { "Scope" : [ "SEARCH" ], "IncreasePercent" : 50, "CalculateBy" : "DIFF", "Position" : "FOOTERFIRST", "KeywordId" : 1574449505, "MaxBid" : 250000 } ] } }
- Response example
-
{ "result" : { "SetAutoResults" : [ { "KeywordId" : 1574449505 } ] } }