CreateOrUpdateBanners

Creates an ad and keywords or modifies an existing ad and keywords.
A CreateOrUpdateBanners (Live) version of this method exists.

If the campaign is active, added and modified ads are automatically submitted for moderation. For campaigns with "Draft" status, ads can be submitted for moderation using the ModerateBanners method.

Restrictions

Alert

The method only supports “Text & Image Ads”. To work with ads of all types, use the Ads service in API version 5. Learn more about ad types...

Groups of multiple ads are not supported in version 4. To work with such groups, use the CreateOrUpdateBanners (Live) method.

No more than 1000 ads can be passed in a single method call.

The method can be called no more than 1000 times per day for one campaign. Calling the method consumes points. If there are not enough points, error message 152 is returned.

A campaign can have no more than 1000 ads. The number of keywords in an ad — no more than 200.

To update only click prices, it is recommended to use the UpdatePrices method, which does not consume points when called.

Input data

The structure of input data in JSON format 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)
            ...
         ]
      }
      ...
   ]
}

The parameters are described below.

^Parameter	^Description	^Required
_{BannerInfo object}
`BannerID`	Ad ID. To create an ad, set to 0; to change ad parameters, specify its ID.	Yes
`CampaignID`	Campaign ID.	Yes
`Title`	Ad title (up to 33 characters, including spaces and punctuation).	Yes
`Text`	Ad text (up to 75 characters, including spaces and punctuation).	Yes
`Href`	Link to the advertiser's website. May contain substitution variables.	One of the parameters — `Href` or `ContactInfo`
`ContactInfo`	`ContactInfo` object with advertiser contact data (business card).
`Geo`	IDs of regions for which ad serving is enabled or disabled. ID 0 or empty string — serve ads in all regions (default value). To disable ad serving in a region, put a minus sign before the region ID, for example "1,-219" — serve ads for Moscow and Moscow Oblast, except Chernogolovka. Regions with a minus cannot be used if region zero is specified. Also, the parameter must not consist only of minus-regions. The complete list of regions can be obtained using the GetRegions method.	Yes
`Phrases`	Array of `BannerPhraseInfo` objects containing keyword information. The ad must have at least one keyword. The number of keywords in an ad — no more than 200.	Yes
`Sitelinks`	Array of `Sitelink` objects with sitelinks. The array must contain from 1 to 4 `Sitelink` objects or be absent.	No
`MinusKeywords`	Array of negative keywords common to all keywords in the ad group. A negative keyword should be specified without a minus before the first word. No more than 7 words in a negative keyword. Length of each word — no more than 35 characters. Total length of negative keywords in the array — no more than 4096 characters. The "!" or "+" operator before a word is not counted in the total length. Note Negative keywords common to all groups in a campaign should preferably be specified in the campaign's parameter of the same name.	No
_{ContactInfo object}
`CompanyName`	Organization name. No more than 255 characters.	Yes
`ContactPerson`	Contact person. No more than 155 characters.	No
`Country`	Country. No more than 50 characters.	Yes
`CountryCode`	Country phone code. The value must start with a "+" sign, for example "+7" for Russia. Exception: if the `CityCode` field contains the value "800", then the `CountryCode` field may contain the value "8".	Yes
`City`	City. No more than 50 characters.	Yes
`Street`	Street. No more than 55 characters.	No
`House`	House number. No more than 30 characters.	No
`Build`	Building or block number. No more than 10 characters.	No
`Apart`	Apartment or office number. No more than 255 characters.	No
`CityCode`	City phone code.	Yes
`Phone`	Contact phone number.	Yes
`PhoneExt`	Extension phone number for connection through office PBX.	No
`IMClient`	Type of instant messaging network — icq, jabber, skype, mail_agent.	No
`IMLogin`	Login in instant messaging network.	No
`ExtraMessage`	Additional information about the advertised product or service. No more than 200 characters.	No
`ContactEmail`	Email address. No more than 255 characters.	No
`WorkTime`	Organization's working hours or customer service hours. Specified as a string indicating the range of weekdays, working hours, and minutes. Weekdays are designated by numbers from 0 to 6, where 0 is Monday, 6 is Sunday. Minutes are specified in multiples of 15: 0, 15, 30, or 45. String format: `"day_from;day_to;hour_from;minutes_from;hour_to;min_to"` For example, the string `"0;4;10;0;18;0"` specifies the following schedule: `0;4` — Monday through Friday; `10;0` — from 10:00; `18;0` — until 18:00. The schedule can consist of several strings of the specified format, for example: "`0;4;10;0;18;0;5;6;11;0;16;0`". Here, in addition to the previous example, the following schedule is specified: `5;6` — Saturday through Sunday; `11;0` — from 11:00; `16;0` — until 16:00. 24-hour operation is specified by the string `"0;6;00;00;00;00"`.	Yes
`OGRN`	OGRN code for legal entities.	No
`PointOnMap`	`MapPoint` object specifying the coordinates of the client's location. A marker is placed on the map at these coordinates. If not specified, the marker is placed at the specified client address.	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 map area. From -180 to 180.	Yes
`y1`	Latitude of the lower left corner of the map area. From -90 to 90.	Yes
`x2`	Longitude of the upper right corner of the map area. From -180 to 180.	Yes
`y2`	Latitude of the upper right corner of the map area. From -90 to 90.	Yes
_{BannerPhraseInfo object}
`PhraseID`	Keyword ID. To add a keyword, set to 0; to change keyword parameters, specify its ID.	No
`Phrase`	Keyword. May contain negative words, which are specified with a minus sign before the word, for example [lightning -thunder -rain]. Negative words common to several keywords should preferably be specified in the ad group's `MinusKeywords` parameter. Keyword length — no more than 4096 characters. The "!" operator before a negative word is not counted in the keyword length (the sequence "-!" is counted as one character). No more than 7 words in a keyword, excluding stop words and negative words. Each word and negative word — no more than 35 characters, excluding the minus before the negative word.	Yes
`IsRubric`	Indicator that the keyword is a Yandex Catalog category — Yes/No. Default value — No. With the value Yes, the passed keyword is ignored.	No
`Price`	Bid on Yandex Search (Yandex units). Default limit — 50 Yandex units. Required only if a manual bid management strategy is selected for the campaign.	For manual strategies
`AutoBudgetPriority`	Keyword priority when using automatic strategies. Possible values: Low — low priority; Medium — medium priority; High — high priority.	For WeeklyBudget strategy
`ContextPrice`	Bid in the Yandex Advertising Network (Yandex units). The bid can be specified in the following cases: The IndependentControl strategy is used on search. This strategy can only be selected through the Yandex Direct web interface. Any manual strategy is used on search and the keyword is disabled for low CTR. For new keywords, this condition is not relevant, since keywords are no longer disabled for low CTR.	For IndependentControl strategy
`AutoBroker`	Enable/disable auto-broker. The parameter is not used, the passed value is ignored.	No
`UserParams`	`PhraseUserParams` object. Contains values of substitution variables for forming the website link.	No
_{PhraseUserParams object}
`Param1`	Value of the `{param1}` substitution variable. No more than 255 bytes.	When using substitution variables in `Href`
`Param2`	Value of the `{param2}` substitution variable. No more than 255 bytes.
_{Sitelink object}
`Title`	Sitelink text (no more than 30 characters). Total length of texts of all sitelinks — no more than 66 characters.	Yes
`Href`	Sitelink address. May contain substitution variables.	Yes

Output data

Upon successful execution, the method returns an array containing the IDs of created/updated banners, as shown in the following example.

{
   "data": [33823946,33823947]
}

Input data examples

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'Александр Громов',
         'Country': u'Россия',
         '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'все товары сертифицированы',
         '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'Доп. ссылка 1',
            'Href': 'market-click2.ya.ru/?q=qu&action=1'
         },
         {
            'Title': u'Доп. ссылка 2',
            'Href': 'market-click2.ya.ru/?q=qu&action=2'
         },
         {
            'Title': u'Доп. ссылка 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' => 'Александр Громов',
         'Country' => 'Россия',
         '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' => 'все товары сертифицированы',
         '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' => 'Доп. ссылка 1',
            'Href' =>'market-click2.ya.ru/?q=qu&amp;action=1'
         ),
         array(
            'Title' => 'Доп. ссылка 2',
            'Href' =>'market-click2.ya.ru/?q=qu&amp;action=2'
         ),
         array(
            'Title' => 'Доп. ссылка 3',
            'Href' =>'market-click2.ya.ru/?q=qu&amp;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' => 'Александр Громов',
         'Country' => 'Россия',
         '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' => 'все товары сертифицированы',
         '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' => 'Доп. ссылка 1',
            'Href' =>'market-click2.ya.ru/?q=qu&amp;action=1'
         },
         {
            'Title' => 'Доп. ссылка 2',
            'Href' =>'market-click2.ya.ru/?q=qu&amp;action=2'
         },
         {
            'Title' => 'Доп. ссылка 3',
            'Href' =>'market-click2.ya.ru/?q=qu&amp;action=3'
         }
      ],
      'MinusKeywords' => ['ice','cream']
   }
]

Was the article helpful?

ArchiveBanners (Live)

CreateOrUpdateBanners (Live)