GetBanners

Returns parameters of ads and keywords.
A GetBanners (Live) version of this method exists.

In addition to ad parameters, the method returns keyword parameters in abbreviated or full form, which is determined by the GetPhrases input parameter. With the value "No", keyword information is not returned. With the value "Yes" or if GetPhrases is absent, an abbreviated set of keyword information is returned. With the value "WithPrices", a full set of keyword information is returned, and the resulting structure, after modifying the necessary parameters, can be submitted as input to the CreateOrUpdateBanners method.

Restrictions

Alert

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

Input data

The structure of input data in JSON format is shown below.

{
   "method": "GetBanners",
   "param": {
      /* GetBannersInfo */
      "CampaignIDS": [
         (int)
         ...
      ],
      "BannerIDS": [
         (long)
         ...
      ],
      "GetPhrases": (string),
      "Filter": {
         /* BannersFilterInfo */
         "StatusPhoneModerate": [
            (string)
            ...
         ],
         "StatusBannerModerate": [
            (string)
            ...
         ],
         "StatusPhrasesModerate": [
            (string)
            ...
         ],
         "StatusActivating": [
            (string)
            ...
         ],
         "StatusShow": [
            (string)
            ...
         ],
         "IsActive": [
            (string)
            ...
         ],
         "StatusArchive": [
            (string)
            ...
         ]
      }
   }
}

The parameters are described below.

^Parameter	^Description	^Required
_{GetBannersInfo object}
`CampaignIDS`	Array of campaign IDs (no more than 10 IDs). The method returns parameters of ads belonging to the specified campaigns.	One of the parameters: `CampaignIDS` or `BannerIDS`
`BannerIDS`	Array containing ad IDs. You can specify up to 2000 IDs. This parameter takes priority over `CampaignIDS`: if both parameters are specified, ads are selected by IDs from the `BannerIDS` array.
`Filter`	Contains a `BannersFilterInfo` object that specifies ad selection conditions.	No
`GetPhrases`	Return keyword parameters in the `Phrases` array: No — do not return keyword parameters; Yes — return an abbreviated set of parameters; WithPrices — return a full set of parameters, including prices and statistics. If the `GetPhrases` parameter is absent, the value Yes is assumed.	No
_{BannersFilterInfo object}
`StatusBannerModerate`	Select ads by moderation result: New — ad not checked (status "Draft"); Pending — check in progress; Yes — accepted; No — rejected; PreliminaryAccept — ad preliminarily accepted, final result will be known later.	No
`StatusPhrasesModerate`	Select ads by keyword moderation result: New — keywords not checked; Pending — check in progress; Yes — at least one keyword accepted (some may have been rejected); No — all keywords rejected; PreliminaryAccept — keywords preliminarily accepted, final result will be known later.	No
`StatusPhoneModerate`	Select ads by business card moderation result: New — contact information not checked; Pending — check in progress; Yes — accepted; No — rejected;	No
`StatusActivating`	Select ads by relevance of changes made: Yes — changes made have taken effect; Pending — changes are pending to take effect. Some time passes between making changes to ads and the changes taking effect. Usually it does not exceed 40 minutes, but during peak hours it can reach three hours.	No
`StatusShow`	Select ads that are shown or not shown: Yes — display enabled; No — display disabled. Enabling and disabling display is performed by the ResumeBanners and StopBanners methods, respectively.	No
`IsActive`	Select ads by activation status: Yes — activated ads; No — non-activated ads.	No
`StatusArchive`	Select ads by archive status: Yes — ads in archive; No — ads not in archive.	No

Output data

An array of BannerInfo objects containing ad parameters is returned. The structure of output data in JSON format is shown below.

{
   "data": [
      {  /* BannerInfo */
         "BannerID": (long),
         "CampaignID": (int),
         "Title": (string),
         "Text": (string),
         "Href": (string),
         "Domain": (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 */
               "BannerID": (long),
               "CampaignID": (int),
               "PhraseID": (long),
               "Phrase": (string),
               "IsRubric": (string),
               "Price": (float),
               "ContextPrice": (float),
               "AutoBroker": (string),
               "UserParams": {
                  /* PhraseUserParams */
                  "Param1": (string),
                  "Param2": (string)
               }
               "StatusPhraseModerate": (string),
               "AutoBudgetPriority": (string),
               "Clicks": (int),
               "Shows": (int),
               "Min": (float),
               "Max": (float),
               "PremiumMin": (float),
               "PremiumMax": (float),
               "LowCTRWarning": (string),
               "LowCTR": (string),
               "ContextLowCTR": (string),
               "Coverage": [
                  {  /* CoverageInfo */
                     "Probability": (float),
                     "Price": (float)
                  }
                  ...
               ],
               "ContextCoverage": [
                  {  /* CoverageInfo */
                     "Probability": (float),
                     "Price": (float)
                  }
                  ...
               ],
               "Prices": [
                  (float)
                  ...
               ],
               "CurrentOnSearch": (float),
               "MinPrice": (float)
            }
            ...
         ],
         "StatusActivating": (string),
         "StatusArchive": (string),
         "StatusBannerModerate": (string),
         "StatusPhrasesModerate": (string),
         "StatusPhoneModerate": (string),
         "StatusShow": (string),
         "IsActive": (string),
         "StatusSitelinksModerate": (string),
         "Sitelinks": [
            {  /* Sitelink */
               "Title": (string),
               "Href": (string)
            }
            ...
         ],
         "AdWarnings": [
            (string)
            ...
         ],
         "FixedOnModeration": (string),
         "ModerateRejectionReasons": [
            {  /* RejectReason */
               "Type": (string),
               "Text": (string)
            }
            ...
         ],
         "MinusKeywords": [
            (string)
            ...
         ]
      }
      ...
   ]
}

The parameters are described below.

^Parameter	^Description
_{BannerInfo object}
`BannerID`	Ad ID. To create an ad, set to 0; to change ad parameters, specify its ID.
`CampaignID`	Campaign ID.
`Title`	Ad title (up to 33 characters, including spaces and punctuation).
`Text`	Ad text (up to 75 characters, including spaces and punctuation).
`Href`	Link to the advertiser's website. May contain substitution variables.
`Domain`	Domain that the `Href` link leads to. The domain is filled in automatically. If the link leads to a redirect, the final domain is specified in the parameter.
`Geo`	IDs of regions for which display is enabled or disabled. ID 0 or empty string — display in all regions (default value). To disable display in a region, put a minus sign before the region ID, for example "1,-219" — display 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.
`ContactInfo`	`ContactInfo` object with advertiser contact data (business card).
`Phrases`	Array of `BannerPhraseInfo` objects with keyword parameters. Displayed if the `GetPhrases` input parameter has the value "Yes" or "WithPrices" or is absent.
`StatusActivating`	All changes made have taken effect — Yes/Pending.
`StatusArchive`	Ad placed in archive — Yes/No.
`StatusBannerModerate`	Ad moderation result (text and link are checked): New — ad not checked (status "Draft"); Pending — check in progress; Yes — accepted; No — rejected; PreliminaryAccept — ad preliminarily accepted, final result will be known later.
`StatusPhrasesModerate`	Keyword moderation result: New — keywords not checked; Pending — check in progress; Yes — at least one keyword accepted (some may have been rejected); No — all keywords rejected; PreliminaryAccept — keywords preliminarily accepted, final result will be known later.
`StatusPhoneModerate`	Business card moderation result: New — contact information not checked; Pending — check in progress; Yes — accepted; No — rejected;
`StatusShow`	Ad serving is enabled — Yes/No. Enabling and disabling display is performed by the ResumeBanners and StopBanners methods. Permission to serve ads does not mean that ads are actually being served. Other conditions must also be met: sufficient balance, campaign and ad checked by moderator, display at campaign level is enabled (ResumeCampaign method). Actual serving corresponds to the value Yes in the `IsActive` parameter.
`IsActive`	Ad is active — Yes/No. Activity refers to the state of ads in which serving is enabled and disabled automatically — according to time targeting settings or depending on the campaign balance. Inactive ads are those whose serving has been disabled by the user or a Yandex manager and cannot be enabled automatically.
`StatusSitelinksModerate`	Sitelink check result: New — sitelinks not checked; Pending — check in progress; Yes — accepted; No — rejected.
`Sitelinks`	Array of `Sitelink` objects with . The array must contain from 1 to 4 `Sitelink` objects or be absent.
`AdWarnings`	Array containing marks of the advertised object's belonging to special categories. For such categories, ad display is either prohibited or accompanied by a warning in accordance with Russian Federation legislation. Possible groups: abortion — medical services for artificial termination of pregnancy; alcohol — alcoholic products, beer and beverages based on it; baby_food — baby food; dietarysuppl — dietary supplements; medicine — medicines, medical equipment, medical services, including treatment methods; pseudoweapon — products structurally similar to weapons; tobacco — tobacco and tobacco products; project_declaration — shared construction.
`FixedOnModeration`	Typos corrected during moderation — Yes/No.
`ModerateRejectionReasons`	Array of `RejectReason` objects. These objects describe the reasons why ad text, keyword, contact information, or sitelink was rejected.
`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.
_{ContactInfo object}
`ContactPerson`	Contact person. No more than 155 characters.
`Country`	Country. No more than 50 characters.
`CountryCode`	Country phone code. For example, "+7" for Russia.
`City`	City. No more than 50 characters.
`Street`	Street. No more than 55 characters.
`House`	House number. No more than 30 characters.
`Build`	Building or block number. No more than 10 characters.
`Apart`	Apartment or office number. No more than 255 characters.
`CityCode`	City phone code.
`Phone`	Contact phone number.
`PhoneExt`	Extension phone number for connection through office PBX.
`CompanyName`	Organization name. No more than 255 characters.
`IMClient`	Type of instant messaging network — icq, jabber, skype, mail_agent.
`IMLogin`	Login in instant messaging network.
`ExtraMessage`	Additional information about the advertised product or service. No more than 200 characters.
`ContactEmail`	Email address. No more than 255 characters.
`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"`.
`OGRN`	OGRN code for legal entities.
`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.
_{MapPoint object}
`x`	Longitude of the point. From -180 to 180.
`y`	Latitude of the point. From -90 to 90.
`x1`	Longitude of the lower left corner of the map area. From -180 to 180.
`y1`	Latitude of the lower left corner of the map area. From -90 to 90.
`x2`	Longitude of the upper right corner of the map area. From -180 to 180.
`y2`	Latitude of the upper right corner of the map area. From -90 to 90.
_{BannerPhraseInfo object}
`CampaignID`	Campaign ID.
`BannerID`	Ad ID.
`PhraseID`	Keyword ID.
`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.
`IsRubric`	Indicator that the keyword is a Yandex Catalog category. Always contains the value 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.
`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.
`AutoBroker`	Indicator of enabled auto-broker. Always contains the value Yes.
`UserParams`	`PhraseUserParams` object. Contains values of substitution variables for forming the website link.
`StatusPhraseModerate`	Keyword check result: New — keyword not checked; Yes — accepted; No — rejected;
`AutoBudgetPriority`	Keyword priority when using automatic strategies. Possible values: Low — low priority; Medium — medium priority; High — high priority.
`Clicks`	Number of clicks on the ad shown in search for this keyword. Calculated for 28 days from the current date. Days during which there was at least one click on the ad are selected for calculation.
`Shows`	Number of ad impressions for this keyword in search. Calculated for 28 days from the current date. Days during which there was at least one ad impression for this keyword are selected for calculation.
`Min`	Minimum bid for entry into the Guaranteed placement block.
`Max`	Minimum bid for 1st position in the Guaranteed placement block.
`PremiumMin`	Minimum bid for entry into Premium placement.
`PremiumMax`	Minimum bid for 1st position in Premium placement.
`LowCTRWarning`	Keyword has low CTR and may be disabled soon — Yes/No. Alert This parameter is no longer relevant for new keywords, since keywords are no longer disabled for low CTR.
`LowCTR`	Keyword disabled in search for low CTR — Yes/No. Alert This parameter is no longer relevant for new keywords, since keywords are no longer disabled for low CTR.
`ContextLowCTR`	Keyword disabled on Yandex Advertising Network sites for low CTR — Yes/No. Alert This parameter is no longer relevant for new keywords, since keywords are no longer disabled for low CTR.
`Coverage`	Array of `CoverageInfo` objects that indicate the predicted audience reach in search. Alert The parameter is no longer relevant and should not be used for bid selection.
`ContextCoverage`	Array of `CoverageInfo` objects that indicate the predicted audience reach in the Yandex Advertising Network. The parameter is useful for bid selection for keywords.
`Prices`	Array of bids for all positions in Premium placement and in the Guaranteed placement block.
`CurrentOnSearch`	Final click price taking into account auto-broker. If the ad is not being shown in search for the keyword or the keyword is disabled in search for low CTR, the parameter returns the value NULL.
`MinPrice`	Minimum price, assigned individually for each advertiser.
_{CoverageInfo object}
`Probability`	Impression frequency at the bid from the `Price` parameter. In the `ContextCoverage` array, specified as a percentage from 0 to 100. Used for bid selection.
`Price`	Bid for which the `Probability` parameter contains the impression frequency.
_{PhraseUserParams object}
`Param1`	Value of the `{param1}` substitution variable. No more than 255 bytes.
`Param2`	Value of the `{param2}` substitution variable. No more than 255 bytes.
_{Sitelink object}
`Title`	Sitelink text.
`Href`	Sitelink address. May contain substitution variables.
_{RejectReason object}
`Type`	Type of object rejected in moderation — Banner, Phrases, ContactInfo, Sitelink.
`Text`	Reason for rejection in moderation.
Notes
In rare cases, impression position prices and some other parameters related to auction results may have a NULL value, which indicates an error retrieving data on the API side. It is recommended to retry the method call after some time.

Input data examples

Python

{
   'BannerIDS': [1974642, 20920155, 20155899, 64654],
   'Filter': {
      'StatusPhoneModerate': ['Yes'],
      'StatusBannerModerate': ['Yes'],
      'StatusPhrasesModerate': ['Yes'],
      'StatusActivating': ['Yes'],
      'StatusShow': ['Yes'],
      'IsActive': ['Yes'],
      'StatusArchive': ['No']
   },
   'GetPhrases': 'WithPrices'
}

PHP

array(
   'BannerIDS' => array(1974642, 20920155, 20155899, 64654),
   'Filter' => array(
      'StatusPhoneModerate' => array('Yes'),
      'StatusBannerModerate' => array('Yes'),
      'StatusPhrasesModerate' => array('Yes'),
      'StatusActivating' => array('Yes'),
      'StatusShow' => array('Yes'),
      'IsActive' => array('Yes'),
      'StatusArchive' => array('No')
   ),
   'GetPhrases' => 'WithPrices'
)

Perl

{
   'BannerIDS' => [1974642, 20920155, 20155899, 64654],
   'Filter' ={
      'StatusPhoneModerate' => ['Yes'],
      'StatusBannerModerate' => ['Yes'],
      'StatusPhrasesModerate' => ['Yes'],
      'StatusActivating' => ['Yes'],
      'StatusShow' => ['Yes'],
      'IsActive' => ['Yes'],
      'StatusArchive' => ['No']
   },
   'GetPhrases' => 'WithPrices'
}

Was the article helpful?

DeleteBanners (Live)

GetBanners (Live)