GetBanners (Live)
Returns parameters of ad groups, ads, and keywords.
The method returns parameters of ad groups, ads, and keywords. Keyword parameters are returned in either abbreviated or full form (see the GetPhrases parameter).
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
What's new in Live version 4
Added input parameters Limit and Offset for paginating ads from the database.
Added input parameters Tags and TagIDS for filtering ads by labels and label IDs.
Added input parameter FieldsNames to limit the set of returned data.
Added output keyword parameters StatusPaused, ContextClicks, ContextShows.
Added output ad parameter AgeLabel.
Added input parameter StatusAdImageModerate, as well as output parameters AdImageHash and StatusAdImageModerate.
Added input parameter Currency and output parameter Currency.
Added output parameters AdGroupID and AdGroupName.
Added output parameter AdGroupMobileBidAdjustment.
Added output parameter Type.
Added input parameter AuctionBids and output array AuctionBids.
Input data
The structure of the input data in JSON format is shown below.
{
"method": "GetBanners",
"param": {
/* GetBannersInfo */
"CampaignIDS": [
(int)
...
],
"BannerIDS": [
(long)
...
],
"FieldsNames": [
(string)
...
],
"GetPhrases": (string),
"Limit": (int),
"Offset": (int),
"Currency": (string),
"Filter": {
/* BannersFilterInfo */
"StatusPhoneModerate": [
(string)
...
],
"StatusBannerModerate": [
(string)
...
],
"StatusPhrasesModerate": [
(string)
...
],
"StatusActivating": [
(string)
...
],
"StatusShow": [
(string)
...
],
"IsActive": [
(string)
...
],
"StatusArchive": [
(string)
...
],
"TagIDS": [
(int)
...
],
"Tags": [
(string)
...
],
"StatusAdImageModerate": [
(string)
...
]
},
"AuctionBids": (string)
}
}
The parameters are described below.
|
Parameter |
Description |
Required |
|
GetBannersInfo object |
||
|
|
An array of campaign IDs (up to 10 IDs). The method returns parameters of ads belonging to the specified campaigns. |
One of the parameters: |
|
|
An array of ad IDs. Up to 2000 IDs can be specified. This parameter takes priority over |
|
|
|
Contains the |
No |
|
|
Names of top-level parameters to retrieve (other parameters are not returned). If the array is not specified, all parameters are returned. Note Limiting the set of returned parameters is recommended when requesting data for a large number of ads. Such requests put a heavy load on the API and may be processed slowly, or may fail entirely. |
No |
|
|
Return keyword parameters in the
If the |
No |
|
|
The number of ads whose parameters are included in the response (a number greater than zero). Together with the The |
No |
|
|
The sequential number of the ad in the database result set (a number greater than zero). The response includes ads starting from the specified number. The number of ads returned at a time is specified in the |
No |
|
|
The currency in which bids should be expressed in the response. Possible values: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN. The value must match the campaign currency. If the parameter is absent or equals NULL, Yandex units are assumed. In this case, if the campaign uses a real currency, the returned values are converted from the campaign currency to Yandex units. If the value is not NULL and does not match the currency of the campaign (or one of the campaigns), an error with code 245 is returned. |
No |
|
|
Whether to return auction results (the |
No |
|
BannersFilterInfo object |
||
|
|
Filter ads by moderation result:
|
No |
|
|
Filter ads by keyword moderation result:
|
No |
|
|
Filter ads by vCard moderation result:
|
No |
|
|
Filter ads by whether changes have taken effect:
There is a delay between making changes to ads and those changes taking effect. This is usually no more than 40 minutes, but during peak load periods it may take up to three hours. |
No |
|
|
Filter ads that are enabled or disabled for serving:
Serving is enabled and disabled using the ResumeBanners and StopBanners methods, respectively. |
No |
|
|
Filter ads by activation status:
|
No |
|
|
Filter ads by archive status:
|
No |
|
|
Filter ads by labels with the specified IDs. This parameter is mutually exclusive with the |
No |
|
|
Filter ads by the specified labels. This parameter is mutually exclusive with the |
No |
|
|
Filter ads by image moderation status:
|
No |
Output data
Returns an array of BannerInfo objects containing ad parameters. The structure of the output data in JSON format is shown below.
{
"data": [
{ /* BannerInfo */
"BannerID": (long),
"CampaignID": (int),
"AdGroupID": (long),
"AdGroupName": (string),
"Type": (string),
"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),
"AdGroupID": (long),
"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),
"ContextClicks": (int),
"ContextShows": (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),
"StatusPaused": (string),
"Currency": (string),
"AuctionBids": [
{ /* PhraseAuctionBids */
"Position": (string),
"Bid": (float),
"Price": (float)
}
...
]
}
...
],
"StatusActivating": (string),
"StatusArchive": (string),
"StatusBannerModerate": (string),
"StatusPhrasesModerate": (string),
"StatusPhoneModerate": (string),
"StatusAdImageModerate": (string),
"StatusShow": (string),
"IsActive": (string),
"StatusSitelinksModerate": (string),
"Sitelinks": [
{ /* Sitelink */
"Title": (string),
"Href": (string)
}
...
],
"FixedOnModeration": (string),
"ModerateRejectionReasons": [
{ /* RejectReason */
"Type": (string),
"Text": (string)
}
...
],
"MinusKeywords": [
(string)
...
],
"AgeLabel": (string),
"AdImageHash": (string),
"AdGroupMobileBidAdjustment": (int)
}
...
]
}
The parameters are described below.
|
Parameter |
Description |
|
BannerInfo object |
|
|
|
Ad ID. To create an ad, set to 0; to modify an ad's parameters, specify its ID. |
|
|
Campaign ID. |
|
|
Ad group ID. |
|
|
Ad group name. |
|
|
Ad type: Desktop or Mobile. |
|
|
Ad title (up to 33 characters, including spaces and punctuation marks). |
|
|
Ad text (up to 75 characters, including spaces and punctuation marks). |
|
|
Link to the advertiser's website. May contain substitution variables. |
|
|
The domain that the |
|
|
IDs of regions for which impressions are enabled or disabled. ID 0 or an empty string means show in all regions (the default value). To disable serving in a region, prefix the region ID with a minus sign, for example, “1,-219” means show for Moscow and Moscow Oblast, except Chernogolovka. Regions with a minus sign cannot be used if the zero region is specified. The parameter must not consist solely of negative regions. You can get the full list of regions using the GetRegions method. |
|
|
|
|
|
Array of |
|
|
All changes have taken effect — Yes/Pending. |
|
|
Ad archive status:
|
|
|
Ad moderation result (the text and link are checked):
|
|
|
Keyword moderation result:
|
|
|
vCard moderation result:
|
|
|
Moderation result for the image linked to the ad:
|
|
|
Ad serving is enabled — Yes/No. Serving is enabled and disabled using the ResumeBanners and StopBanners methods. Enabling serving does not mean the ads are actually being served. Other conditions must also be met: a sufficient account balance, the campaign and ad have been reviewed by a moderator, and serving is enabled at the campaign level (the ResumeCampaign method). Actual serving corresponds to the value Yes in the |
|
|
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. |
|
|
Sitelink review result:
|
|
|
Array of |
|
|
An array containing markers indicating that the advertised object belongs to special categories. For such categories, ad serving is either prohibited or accompanied by a warning in accordance with the legislation of the Russian Federation. Possible groups:
|
|
|
Typos were corrected during moderation — Yes/No. |
|
|
Array of |
|
|
Array of negative keywords shared by all keywords in the ad group. A negative keyword must be specified without a minus sign before the first word. Up to 7 words per negative keyword. Each word is up to 35 characters. The total length of negative keywords in the array is up to 4,096 characters. The “!” or “+” operator before a word is not counted toward the total length. Note Negative keywords shared by all groups in a campaign should preferably be set in the corresponding campaign parameter. |
|
|
Age category. For ads belonging to the baby_food group (the corresponding value is returned in the For other ads — the age group that the informational content is intended for. Possible values: '0+', '6+', '12+', '16+', '18+'. If the ad has no age category, the parameter is not returned in responses and is ignored when you attempt to set it. Alert Through the API, you can only change the value of the age category if the ad already has one. To add or remove an age category, contact . |
|
|
Hash of the image linked to the ad. |
|
|
Bid adjustment coefficient for mobile devices. Applied to ad groups and specified as a percentage of the desktop bid. The value range is from 50 to 1300. For more information about the coefficient, see in Yandex Direct Help. Note If the coefficient is not set for the group, the campaign-level coefficient (the |
|
ContactInfo object |
|
|
|
Contact person. Up to 155 characters. |
|
|
Country. Up to 50 characters. |
|
|
Country phone code. For example, “+7” for Russia. |
|
|
City. Up to 50 characters. |
|
|
Street. Up to 55 characters. |
|
|
House number. Up to 30 characters. |
|
|
Structure or block number. Up to 10 characters. |
|
|
Apartment or office number. Up to 255 characters. |
|
|
City phone code. |
|
|
Contact phone number. |
|
|
Extension number for connecting via a PBX. |
|
|
Organization name. Up to 255 characters. |
|
|
Instant messaging network type — icq, jabber, skype, mail_agent. |
|
|
Instant messaging login. |
|
|
Additional information about the advertised product or service. Up to 200 characters. |
|
|
Email address. Up to 255 characters. |
|
|
Organization's operating hours or customer service hours. Specified as a string containing a range of weekdays, working hours, and minutes. Weekdays are denoted by numbers from 0 to 6, where 0 is Monday and 6 is Sunday. Minutes are specified in multiples of 15: 0, 15, 30, or 45. String format:
For example, the string
A schedule can consist of multiple strings in the specified format, for example: “
Round-the-clock hours are set with the string |
|
|
Primary State Registration Number (OGRN) for legal entities. |
|
|
|
|
MapPoint object |
|
|
|
Longitude of the point. From -180 to 180. |
|
|
Latitude of the point. From -90 to 90. |
|
|
Longitude of the lower-left corner of the map area. From -180 to 180. |
|
|
Latitude of the lower-left corner of the map area. From -90 to 90. |
|
|
Longitude of the upper-right corner of the map area. From -180 to 180. |
|
|
Latitude of the upper-right corner of the map area. From -90 to 90. |
|
BannerPhraseInfo object |
|
|
|
Ad ID. |
|
|
Campaign ID. |
|
|
Ad group ID. |
|
|
Keyword ID. |
|
|
Keyword. May contain negative keywords, which are specified with a minus sign before the word, for example, [lightning -thunder -rain]. Negative keywords shared by multiple keywords should preferably be set in the The length of a keyword is up to 4,096 characters. The “!” operator before a negative keyword is not counted in the keyword length (the sequence “-!” is counted as one character). Up to 7 words in a keyword, not counting stop words and negative keywords. Each word and negative keyword is up to 35 characters, not counting the minus sign before a negative keyword. |
|
|
Indicates that the keyword is a Yandex Catalog category. Always contains the value No. |
|
|
Bid on Yandex Search (in the currency specified in the |
|
|
Bid in the Yandex Advertising Network (YAN) (in the currency specified in the The parameter is available for modification in the following cases:
|
|
|
Indicates that autobroker is enabled. Always contains the value Yes. |
|
|
|
|
|
Keyword review result:
|
|
|
Keyword priority when using automatic strategies. Possible values:
|
|
|
Number of clicks on all ads in the group served on search for this keyword. Calculated over 28 days from the current date. Only days with at least one ad click are included in the calculation. |
|
|
Number of impressions of all ads in the group for this keyword on search. Calculated over 28 days from the current date. Only days with at least one impression for this keyword are included in the calculation. |
|
|
Number of clicks on all ads in the group served in the Yandex Advertising Network for this keyword. Calculated over 28 days from the current date. Only days with at least one ad click are included in the calculation. |
|
|
Number of impressions of all ads in the group for this keyword in the Yandex Advertising Network. Calculated over 28 days from the current date. Only days with at least one impression for this keyword are included in the calculation. |
|
|
Price (in the currency specified in the |
|
|
Price (in the currency specified in the |
|
|
Price (in the currency specified in the |
|
|
Price (in the currency specified in the |
|
|
The keyword has a 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. |
|
|
The keyword has been disabled on search due to a low CTR — Yes/No. Alert This parameter is no longer relevant for new keywords, since keywords are no longer disabled for low CTR. |
|
|
The keyword has been disabled on YAN sites due to a low CTR — Yes/No. Alert This parameter is no longer relevant for new keywords, since keywords are no longer disabled for low CTR. |
|
|
Array of Alert This parameter is deprecated and should not be used for bid selection. |
|
|
Array of The parameter is useful for bid selection for keywords. |
|
|
Array of minimum bids for all positions in Premium placement and in the Guaranteed placement block (in the currency specified in the |
|
|
The final cost per click after autobroker is applied (in the currency specified in the If the ad is not being served on search for this keyword, or the keyword is disabled on search due to a low CTR, the parameter returns NULL. |
|
|
Minimum price set individually for each advertiser (in the currency specified in the |
|
|
Impressions for the keyword are paused — Yes/No. Impressions can be paused and resumed using the Keyword (Live) method. |
|
|
The currency in which bids are expressed. Possible values: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN. If the parameter is absent or equals NULL, Yandex units are assumed. |
|
|
Array of |
|
CoverageInfo object |
|
|
|
Impression frequency at the bid specified in the In the |
|
|
Bid (in the currency specified in the |
|
PhraseUserParams object |
|
|
|
Value of the |
|
|
Value of the |
|
Sitelink object |
|
|
|
Sitelink text. |
|
|
Sitelink URL. May contain substitution variables. |
|
RejectReason object |
|
|
|
Type of the object rejected during moderation — Banner, Phrases, ContactInfo, Sitelink. |
|
|
Reason for rejection during moderation. |
|
PhraseAuctionBids object |
|
|
|
Impression position: P_mn_, where
For example, P12 — second position in Premium placement, P21 — first position in the Guaranteed placement block. |
|
|
Minimum bid for the specified position (in the currency specified in the |
|
|
Charged price for the specified position (in the currency specified in the |
|
Notes |
|
|
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',
'Limit': 20,
'Offset': 1
}
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',
'Limit' => 20,
'Offset' => 1
)
Perl
{
'BannerIDS' => [1974642, 20920155, 20155899, 64654],
'Filter' ={
'StatusPhoneModerate' => ['Yes'],
'StatusBannerModerate' => ['Yes'],
'StatusPhrasesModerate' => ['Yes'],
'StatusActivating' => ['Yes'],
'StatusShow' => ['Yes'],
'IsActive' => ['Yes'],
'StatusArchive' => ['No']
},
'GetPhrases' => 'WithPrices',
'Limit' => 20,
'Offset' => 1
}