setAuto
Sets bids for keywords on search depending on the desired traffic volume, or bids in ad networks depending on the desired frequency of impressions (audience share).
Bid calculation formula:
The bid that corresponds to the traffic volume TargetTrafficVolume × (1 + IncreasePercent / 100),
but no more than BidCeiling.
Over time, competitors' activity might increase the bid for a certain traffic volume, and it will go higher than the advertiser's bid. The higher the markup, the higher the traffic volume, but spending also increases.
The bid that corresponds to the impression frequency TargetCoverage × (1 + IncreasePercent / 100),
but no more than BidCeiling.
Over time, competitors' activity might increase the bid for the desired coverage, and it will be higher than the advertiser's bid. The higher the markup, the higher the frequency of impressions, but spending also might increase.
The method doesn't return the assigned bids, but you can get them using the get method.
The method doesn't reset the automatic bid value (AutotargetingSearchBidIsAuto).
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.
Restrictions
The bid for search can be set only if the HIGHEST_POSITION strategy is selected in the campaign for displays in search results. Otherwise, an error is returned.
The bid in ad networks can be assigned only if the MAXIMUM_COVERAGE or MANUAL_CPM strategy is selected in the campaign for displays in ad networks. Otherwise, an error is returned.
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. Changing bids in search for all the keywords in an ad group or campaign may affect the autotargeting bid.
- campaigns — maximum of 10
- groups — maximum of 1000
- keywords — maximum of 10,000
Request
Request structure in JSON format:
{
"method": "setAuto",
"params": { /* params */
"KeywordBids": [{ /* KeywordBidSetAutoItem */
"CampaignId": (long),
"AdGroupId": (long),
"KeywordId": (long),
"BiddingRule": { /* BiddingRule */
"SearchByTrafficVolume": { /* SearchByTrafficVolume */
"TargetTrafficVolume": (int), /* required */
"IncreasePercent": (int),
"BidCeiling": (long)
},
"NetworkByCoverage": { /* NetworkByCoverage */
"TargetCoverage": (int), /* required */
"IncreasePercent": (int),
"BidCeiling": (long)
}
} /* required */
}, ... ] /* required */
}
}
Parameter | Type | Description | Required |
Params structure (for JSON) / SetAutoRequest structure (for SOAP) | |||
---|---|---|---|
KeywordBids | array of KeywordBidSetAutoItem | Bid calculation parameters | Yes |
KeywordBidSetAutoItem 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. | |
BiddingRule | BiddingRule | Parameters for calculating bids. | Yes |
BiddingRule structure | |||
SearchByTrafficVolume | SearchByTrafficVolume | Parameters for calculating bids in search results. | Either SearchByTrafficVolume, or NetworkByCoverage |
NetworkByCoverage | NetworkByCoverage | Parameters for calculating bids in ad networks. | |
SearchByTrafficVolume structure | |||
TargetTrafficVolume | int | The desired traffic volume in search results. Indicated as a percentage from 5 to 100. A markup is added to the bid that corresponds to the selected traffic volume (see the IncreasePercent parameter). | Yes |
IncreasePercent | int | Markup percent from 0 to 1000. If omitted, markup is not calculated. | No |
BidCeiling | long | The bid limit 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 |
NetworkByCoverage structure | |||
TargetCoverage | int | The desired 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 corresponds to the selected impression frequency (see the IncreasePercent parameter). | Yes |
IncreasePercent | int | Markup percent from 0 to 1000. If omitted, markup is not calculated. | No |
BidCeiling | long | The bid limit 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 |
Parameter | Type | Description | Required |
Params structure (for JSON) / SetAutoRequest structure (for SOAP) | |||
---|---|---|---|
KeywordBids | array of KeywordBidSetAutoItem | Bid calculation parameters | Yes |
KeywordBidSetAutoItem 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. | |
BiddingRule | BiddingRule | Parameters for calculating bids. | Yes |
BiddingRule structure | |||
SearchByTrafficVolume | SearchByTrafficVolume | Parameters for calculating bids in search results. | Either SearchByTrafficVolume, or NetworkByCoverage |
NetworkByCoverage | NetworkByCoverage | Parameters for calculating bids in ad networks. | |
SearchByTrafficVolume structure | |||
TargetTrafficVolume | int | The desired traffic volume in search results. Indicated as a percentage from 5 to 100. A markup is added to the bid that corresponds to the selected traffic volume (see the IncreasePercent parameter). | Yes |
IncreasePercent | int | Markup percent from 0 to 1000. If omitted, markup is not calculated. | No |
BidCeiling | long | The bid limit 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 |
NetworkByCoverage structure | |||
TargetCoverage | int | The desired 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 corresponds to the selected impression frequency (see the IncreasePercent parameter). | Yes |
IncreasePercent | int | Markup percent from 0 to 1000. If omitted, markup is not calculated. | No |
BidCeiling | long | The bid limit 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 |
Response
Response structure in JSON format:
{
"result": { /* result */
"SetAutoResults": [{ /* KeywordBidActionResult */
"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 KeywordBidActionResult | The results of the bidding. |
KeywordBidActionResult 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 KeywordBidActionResult | The results of the bidding. |
KeywordBidActionResult 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
-
Sets the bid in search for all keywords in an ad group to get the traffic volume of 75, increased by 10%, but not more than 12.
{ "method": "setAuto", "params": { "KeywordBids": [{ "AdGroupId": 636056397, "BiddingRule": { "SearchByTrafficVolume": { "TargetTrafficVolume": 75, "IncreasePercent": 10, "BidCeiling": 12000000, } } }] } }
- Response example
-
{ "result" : { "SetAutoResults" : [ { "AdGroupId" : 636056397 } ] } }