CreateOrUpdateBanners
Creates an ad and keywords, or changes an existing ad and keywords.
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 CreateOrUpdateBanners (Live) version also exists for this method.
If the campaign is active, ads that have been added or changed are automatically submitted for moderation. For campaigns with “Draft” status, you can submit an ad for moderation by using the ModerateBanners method.
Restrictions
Groups of multiple ads are not supported in version 4. To work with groups like this, use the CreateOrUpdateBanners (Live) method.
A maximum of 1000 ads can be passed per method call.
The method can be called for a single campaign no more than 1000 times per day. Points are used when this method is invoked (see Point limitations). If there are not enough points available, the error message 152 is returned.
Each campaign may have a maximum of 1000 ads. The maximum number of keywords per ad is 200.
To update just the CPC, we recommend using the UpdatePrices method, which does not deduct points.
Input data
The input data structure in JSON is shown below.
{
"method": "CreateOrUpdateBanners",
"param": [
{ /* BannerInfo */
"BannerID": (long),
"CampaignID": (int),
"Title": (string),
"Text": (string),
"Href": (string),
"Geo": (string),
"ContactInfo": {
/* ContactInfo */
"ContactPerson": (string),
"Country": (string),
"CountryCode": (string),
"City": (string),
"Street": (string),
"House": (string),
"Build": (string),
"Apart": (string),
"CityCode": (string),
"Phone": (string),
"PhoneExt": (string),
"CompanyName": (string),
"IMClient": (string),
"IMLogin": (string),
"ExtraMessage": (string),
"ContactEmail": (string),
"WorkTime": (string),
"OGRN": (string),
"PointOnMap": {
/* MapPoint */
"x": (float),
"y": (float),
"x1": (float),
"y1": (float),
"x2": (float),
"y2": (float)
}
},
"Phrases": [
{ /* BannerPhraseInfo */
"PhraseID": (long),
"Phrase": (string),
"IsRubric": (string),
"Price": (float),
"ContextPrice": (float),
"AutoBroker": (string),
"AutoBudgetPriority": (string),
"UserParams": {
/* PhraseUserParams */
"Param1": (string),
"Param2": (string)
}
}
...
],
"Sitelinks": [
{ /* Sitelink */
"Title": (string),
"Href": (string)
}
...
],
"MinusKeywords": [
(string)
...
]
}
...
]
}
Parameters are described below.
Parameter | Description | Required |
BannerInfo object | ||
---|---|---|
BannerID | The ad ID. To create an ad, set 0; to change the parameters of an ad, set its ID. | Yes |
CampaignID | The campaign ID. | Yes |
Title | Title of the ad (up to 33 characters, including spaces and punctuation). | Yes |
Text | Text of the ad (up to 75 characters, including spaces and punctuation). | Yes |
Href | Link to the advertiser's website. It can contain wildcard variables (see section Links to the site). | One of the parameters: Href or ContactInfo |
ContactInfo | The ContactInfo object with the advertiser's contact information (business card). | |
Geo | IDs of regions where ad impressions are enabled or disabled. The ID 0 or an empty string indicates impressions in all regions (default value). To disable impressions in a region, prepend a minus sign to the region ID; for example, “1, -219” means to show ads for Moscow and the surrounding area, except Chernogolovka. Regions with a minus sign cannot be used if the zero region is set. Likewise, the parameter cannot consist entirely of minus regions. To get the full list of regions, use the GetRegions method. | Yes |
Phrases | Array of BannerPhraseInfo objects containing information on ad keywords. An ad must have at least one keyword. The maximum number of keywords per ad is 200. | Yes |
Sitelinks | Array of Sitelink objects with sitelinks. The array must contain from 1 to 4 Sitelink objects, or be omitted. | No |
MinusKeywords | Array of negative keywords that are shared by all the keywords of an ad group. A keyword should be specified without the minus sign before the first word. Maximum of 7 words per keyword. The maximum length of each word is 35 characters. The maximum combined length of negative keywords in the array is 4096 characters. The “!” operator or “+” operator before a word is not included in the total length. Note. Negative keywords that are shared for all a campaign's ad groups should preferably be set in the campaign parameter of the same name. | No |
ContactInfo object | ||
CompanyName | Name of the organization. Maximum of 255 characters. | Yes |
ContactPerson | Contact person. A maximum of 155 characters. | No |
Country | Country. A maximum of 50 characters. | Yes |
CountryCode | The country code for the phone number. The value must start with the “+” sign, such as “+7” for Russia. Exception: if the CityCode field is set to “800”, the CountryCode field may be set to “8”. | Yes |
City | The city. A maximum of 50 characters. | Yes |
Street | Street. A maximum of 55 characters. | No |
House | House number. A maximum of 30 characters. | No |
Build | The building or unit number. A maximum of 10 characters. | No |
Apart | The apartment or office number. Maximum of 255 characters. | No |
CityCode | The area code or city code for the phone number. | Yes |
Phone | The contact phone number. | Yes |
PhoneExt | The phone extension, if an office PBX system is used. | No |
IMClient | The type of instant messaging network — icq, jabber, skype or mail_agent. | No |
IMLogin | The user name for the instant messaging network. | No |
ExtraMessage | Additional information on the advertised product or service. Maximum of 200 characters. | No |
ContactEmail | Email address. Maximum of 255 characters. | No |
WorkTime | The operating hours or client service hours of the business. Set as a string that specifies the range of days of the week, work hours, and minutes. Days of the week are defined by the numbers from 0 to 6, where 0 is Monday and 6 is Sunday. Minutes are set as a multiple of 15: 0, 15, 30 or 45. String format:
For example, the string
The schedule may consist of several strings in this format, for example: "
A 24-hour schedule is set using the string | Yes |
OGRN | The OGRN code for a business registered in Russia. | No |
PointOnMap | The MapPoint object, which provides the coordinates of the client's location. These coordinates are used to mark the map. If not set, the map is marked at the address that was specified for the client. | No |
MapPoint object | ||
x | Longitude of the point. From -180 to 180. | Yes |
y | Latitude of the point. From -90 to 90. | Yes |
x1 | Longitude of the lower-left corner of the region on the map. From -180 to 180. | Yes |
y1 | Latitude of the lower-left corner of the region on the map. From -90 to 90. | Yes |
x2 | Longitude of the upper-right corner of the region on the map. From -180 to 180. | Yes |
y2 | Latitude of the upper-right corner of the region on the map. From -90 to 90. | Yes |
BannerPhraseInfo object | ||
PhraseID | The keyword ID. To create a keyword, set 0; to change the parameters of a keyword, specify its ID. | No |
Phrase | Keywords. It can contain negative keywords, which are specified with the minus sign before the word, such as [lightning -thunder -rain]. Negative keywords that are shared between several keywords should preferably be set in the MinusKeywords parameter for the ad group. The maximum length of a keyword is 4096 characters. The “!” operator before a negative keyword is not counted in the keyword length (the sequence “-!” counts as a single character). Maximum of 7 words per keyword, not counting stop words and negative keywords. Each word and negative keyword can be up to 35 characters, not counting the minus sign before a negative keyword. | Yes |
IsRubric | Whether the keyword is a Yandex Catalog category — Yes/No. The predefined value is No. When the value is Yes, the passed keyword is ignored. | No |
Price | The bid on Yandex search (in Yandex units). The predefined limit is 50 Yandex units. Required only if a strategy with manual bid management is selected for the campaign. | For manual strategies |
AutoBudgetPriority | Priority of the keyword when using automatic strategies. Possible values:
| For the WeeklyBudget strategy |
ContextPrice | Bid in the Yandex Advertising Network (in Yandex units). The bid can be set in the following cases:
| For the IndependentControl strategy |
AutoBroker | Enable/disable AutoBroker. This parameter is not used, and the passed value is ignored. | No |
UserParams | PhraseUserParams object. Contains values of substitution variables for the website links (see the section Site links). | No |
PhraseUserParams object | ||
Param1 | Value of the | When using substitution variables in Href |
Param2 | Value of the | |
Sitelink object | ||
Title | Text of a sitelink (maximum 30 characters). The maximum total length of texts for all the sitelinks is 66 characters. | Yes |
Href | Sitelink address. It can contain wildcard variables (see section Links to the site). Attention. The values of the {campaign_id} , {ad_id} , {banner_id} , and {phrase_id} variables will be substituted in the sitelinks only if the same variables are present in the main link for the ad. | Yes |
Parameter | Description | Required |
BannerInfo object | ||
---|---|---|
BannerID | The ad ID. To create an ad, set 0; to change the parameters of an ad, set its ID. | Yes |
CampaignID | The campaign ID. | Yes |
Title | Title of the ad (up to 33 characters, including spaces and punctuation). | Yes |
Text | Text of the ad (up to 75 characters, including spaces and punctuation). | Yes |
Href | Link to the advertiser's website. It can contain wildcard variables (see section Links to the site). | One of the parameters: Href or ContactInfo |
ContactInfo | The ContactInfo object with the advertiser's contact information (business card). | |
Geo | IDs of regions where ad impressions are enabled or disabled. The ID 0 or an empty string indicates impressions in all regions (default value). To disable impressions in a region, prepend a minus sign to the region ID; for example, “1, -219” means to show ads for Moscow and the surrounding area, except Chernogolovka. Regions with a minus sign cannot be used if the zero region is set. Likewise, the parameter cannot consist entirely of minus regions. To get the full list of regions, use the GetRegions method. | Yes |
Phrases | Array of BannerPhraseInfo objects containing information on ad keywords. An ad must have at least one keyword. The maximum number of keywords per ad is 200. | Yes |
Sitelinks | Array of Sitelink objects with sitelinks. The array must contain from 1 to 4 Sitelink objects, or be omitted. | No |
MinusKeywords | Array of negative keywords that are shared by all the keywords of an ad group. A keyword should be specified without the minus sign before the first word. Maximum of 7 words per keyword. The maximum length of each word is 35 characters. The maximum combined length of negative keywords in the array is 4096 characters. The “!” operator or “+” operator before a word is not included in the total length. Note. Negative keywords that are shared for all a campaign's ad groups should preferably be set in the campaign parameter of the same name. | No |
ContactInfo object | ||
CompanyName | Name of the organization. Maximum of 255 characters. | Yes |
ContactPerson | Contact person. A maximum of 155 characters. | No |
Country | Country. A maximum of 50 characters. | Yes |
CountryCode | The country code for the phone number. The value must start with the “+” sign, such as “+7” for Russia. Exception: if the CityCode field is set to “800”, the CountryCode field may be set to “8”. | Yes |
City | The city. A maximum of 50 characters. | Yes |
Street | Street. A maximum of 55 characters. | No |
House | House number. A maximum of 30 characters. | No |
Build | The building or unit number. A maximum of 10 characters. | No |
Apart | The apartment or office number. Maximum of 255 characters. | No |
CityCode | The area code or city code for the phone number. | Yes |
Phone | The contact phone number. | Yes |
PhoneExt | The phone extension, if an office PBX system is used. | No |
IMClient | The type of instant messaging network — icq, jabber, skype or mail_agent. | No |
IMLogin | The user name for the instant messaging network. | No |
ExtraMessage | Additional information on the advertised product or service. Maximum of 200 characters. | No |
ContactEmail | Email address. Maximum of 255 characters. | No |
WorkTime | The operating hours or client service hours of the business. Set as a string that specifies the range of days of the week, work hours, and minutes. Days of the week are defined by the numbers from 0 to 6, where 0 is Monday and 6 is Sunday. Minutes are set as a multiple of 15: 0, 15, 30 or 45. String format:
For example, the string
The schedule may consist of several strings in this format, for example: "
A 24-hour schedule is set using the string | Yes |
OGRN | The OGRN code for a business registered in Russia. | No |
PointOnMap | The MapPoint object, which provides the coordinates of the client's location. These coordinates are used to mark the map. If not set, the map is marked at the address that was specified for the client. | No |
MapPoint object | ||
x | Longitude of the point. From -180 to 180. | Yes |
y | Latitude of the point. From -90 to 90. | Yes |
x1 | Longitude of the lower-left corner of the region on the map. From -180 to 180. | Yes |
y1 | Latitude of the lower-left corner of the region on the map. From -90 to 90. | Yes |
x2 | Longitude of the upper-right corner of the region on the map. From -180 to 180. | Yes |
y2 | Latitude of the upper-right corner of the region on the map. From -90 to 90. | Yes |
BannerPhraseInfo object | ||
PhraseID | The keyword ID. To create a keyword, set 0; to change the parameters of a keyword, specify its ID. | No |
Phrase | Keywords. It can contain negative keywords, which are specified with the minus sign before the word, such as [lightning -thunder -rain]. Negative keywords that are shared between several keywords should preferably be set in the MinusKeywords parameter for the ad group. The maximum length of a keyword is 4096 characters. The “!” operator before a negative keyword is not counted in the keyword length (the sequence “-!” counts as a single character). Maximum of 7 words per keyword, not counting stop words and negative keywords. Each word and negative keyword can be up to 35 characters, not counting the minus sign before a negative keyword. | Yes |
IsRubric | Whether the keyword is a Yandex Catalog category — Yes/No. The predefined value is No. When the value is Yes, the passed keyword is ignored. | No |
Price | The bid on Yandex search (in Yandex units). The predefined limit is 50 Yandex units. Required only if a strategy with manual bid management is selected for the campaign. | For manual strategies |
AutoBudgetPriority | Priority of the keyword when using automatic strategies. Possible values:
| For the WeeklyBudget strategy |
ContextPrice | Bid in the Yandex Advertising Network (in Yandex units). The bid can be set in the following cases:
| For the IndependentControl strategy |
AutoBroker | Enable/disable AutoBroker. This parameter is not used, and the passed value is ignored. | No |
UserParams | PhraseUserParams object. Contains values of substitution variables for the website links (see the section Site links). | No |
PhraseUserParams object | ||
Param1 | Value of the | When using substitution variables in Href |
Param2 | Value of the | |
Sitelink object | ||
Title | Text of a sitelink (maximum 30 characters). The maximum total length of texts for all the sitelinks is 66 characters. | Yes |
Href | Sitelink address. It can contain wildcard variables (see section Links to the site). Attention. The values of the {campaign_id} , {ad_id} , {banner_id} , and {phrase_id} variables will be substituted in the sitelinks only if the same variables are present in the main link for the ad. | Yes |
Output data
When executed successfully, the method returns an array containing the IDs of created or updated ads, as shown in the following example.
{
"data": [33823946,33823947]
}
Examples of input data
Python
[
{
'BannerID': 2571700,
'CampaignID': 1327837,
'Title': 'Banner title',
'Text': 'Banner text',
'Href': 'http://www.client.ru/banner{param1}?page={param2}',
'Geo': '2,183,3',
'ContactInfo': {
'ContactPerson': u'Alexander Gromov',
'Country': u'Russia',
'CountryCode': '+7',
'City': 'Moscow',
'Street': 'Leo Tolstoy',
'House': '16',
'Build': '',
'Apart': '',
'CityCode': '495',
'Phone': '739-70-00',
'PhoneExt': '',
'CompanyName': 'MyCompany',
'IMClient': 'jabber',
'IMLogin': 'email@ya.ru',
'ExtraMessage': u'all products are certified',
'ContactEmail': 'direct@yandex.ru',
'WorkTime': '0;4;10;00;18;00;5;6;13;00;16;00',
'OGRN': '1077746365113',
'PointOnMap': {
'x': 37.587942,
'y': 55.733783,
'x1': 37.573500,
'y1': 55.729389,
'x2': 37.600772,
'y2': 55.740249
}
},
'Phrases': [
{
'PhraseID': 37512102,
'Phrase': 'refrigerator',
'ContextPrice': 1.6,
'Price': 2.1,
'AutoBudgetPriority': 'Medium',
'UserParams': {
'Param1': '17',
'Param2': '177'
}
}
],
'Sitelinks': [
{
'Title': u'Add'l link 1',
'Href': 'market-click2.ya.ru/?q=qu&action=1'
},
{
'Title': u'Add'l link 2',
'Href': 'market-click2.ya.ru/?q=qu&action=2'
},
{
'Title': u'Add'l link 3',
'Href': 'market-click2.ya.ru/?q=qu&action=3'
}
],
'MinusKeywords': ['ice','cream']
}
]
PHP
array(
array(
'BannerID' => 2571700,
'CampaignID' => 1327837,
'Title' => 'Banner title',
'Text' => 'Banner text',
'Href' => 'http://www.client.ru/bannerarray(param1)?page=array(param2)',
'Geo' => '2,183,3',
'ContactInfo' => array(
'ContactPerson' => 'Alexander Gromov',
'Country' => 'Russia',
'CountryCode' => '+7',
'City' => 'Moscow',
'Street' => 'Leo Tolstoy',
'House' => '16',
'Build' => '',
'Apart' => '',
'CityCode' => '495',
'Phone' => '739-70-00',
'PhoneExt' => '',
'CompanyName' => 'MyCompany',
'IMClient' => 'jabber',
'IMLogin' => 'email@ya.ru',
'ExtraMessage' => 'all products are certified',
'ContactEmail' => 'direct@yandex.ru',
'WorkTime' => '0;4;10;00;18;00;5;6;13;00;16;00',
'OGRN' => '1077746365113',
'PointOnMap' => array(
'x' => 37.587942,
'y' => 55.733783,
'x1' => 37.573500,
'y1' => 55.729389,
'x2' => 37.600772,
'y2' => 55.740249
)
),
'Phrases' => array(
array(
'PhraseID' => 37512102,
'Phrase' => 'refrigerator',
'ContextPrice' => 1.6,
'Price' => 2.1,
'AutoBudgetPriority' => 'Medium',
'UserParams' => array(
'Param1' => '17',
'Param2' => '177'
)
)
),
'Sitelinks' => array(
array(
'Title' => 'Add'l link 1',
'Href' => 'market-click2.ya.ru/?q=qu&action=1'
),
array(
'Title' => 'Add'l link 2',
'Href' => 'market-click2.ya.ru/?q=qu&action=2'
),
array(
'Title' => 'Add'l link 3',
'Href' => 'market-click2.ya.ru/?q=qu&action=3'
)
),
'MinusKeywords' => array('ice','cream')
)
)
Perl
[
{
'BannerID' => 2571700,
'CampaignID' => 1327837,
'Title' => 'Banner title',
'Text' => 'Banner text',
'Href' => 'http://www.client.ru/banner{param1}?page={param2}',
'Geo' => '2,183,3',
'ContactInfo' => {
'ContactPerson' => 'Alexander Gromov',
'Country' => 'Russia',
'CountryCode' => '+7',
'City' => 'Moscow',
'Street' => 'Leo Tolstoy',
'House' => '16',
'Build' => '',
'Apart' => '',
'CityCode' => '495',
'Phone' => '739-70-00',
'PhoneExt' => '',
'CompanyName' => 'MyCompany',
'IMClient' => 'jabber',
'IMLogin' => 'email@ya.ru',
'ExtraMessage' => 'all products are certified',
'ContactEmail' => 'direct@yandex.ru',
'WorkTime' => '0;4;10;00;18;00;5;6;13;00;16;00',
'OGRN' => '1077746365113',
'PointOnMap' => {
'x' => 37.587942,
'y' => 55.733783,
'x1' => 37.573500,
'y1' => 55.729389,
'x2' => 37.600772,
'y2' => 55.740249
}
},
'Phrases' => [
{
'PhraseID' => 37512102,
'Phrase' => 'refrigerator',
'ContextPrice' => 1.6,
'Price' => 2.1,
'AutoBudgetPriority' => 'Medium',
'UserParams' => {
'Param1' => '17',
'Param2' => '177'
}
}
],
'Sitelinks' => [
{
'Title' => 'Add'l link 1',
'Href' => 'market-click2.ya.ru/?q=qu&action=1'
},
{
'Title' => 'Add'l link 2',
'Href' => 'market-click2.ya.ru/?q=qu&action=2'
},
{
'Title' => 'Add'l link 3',
'Href' => 'market-click2.ya.ru/?q=qu&action=3'
}
],
'MinusKeywords' => ['ice','cream']
}
]