GetBanners (Live)
Returns parameters for ad groups, ads, and keywords.
Disabled method. Use version 5 of the API.
For information about the compatibility of methods between versions Live 4 and 5, see the Migration guide.
The method returns parameters of groups, ads and keywords. Keyword parameters are returned in either abbreviated or full format (see the GetPhrases parameter).
Restrictions
New in the Live 4 version
Added the Limit and Offset input parameters. They are used for paginated selection of ads from the database.
Add the input parameters Tags and TagIDS for filtering ads by tags and tag IDs.
Added the FieldsNames input parameter, which lets you limit what is included in returned data.
Added the output parameters StatusPaused, ContextClicks, and ContextShows for keywords.
Added the output parameter AgeLabel for ads.
Added the input parameter StatusAdImageModerate and output parameters AdImageHash and StatusAdImageModerate.
Added the Currency input parameter and the Currency output parameter (also see the section Real currencies instead of Yandex units).
Added the output parameters AdGroupID and AdGroupName.
Added the AdGroupMobileBidAdjustment output parameter.
Added the Type output parameter.
Added the AuctionBids input parameter and the AuctionBids output parameter.
Input data
The input data structure in JSON 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)
}
}
Parameters are described below.
Parameter | Description | Required |
GetBannersInfo object | ||
---|---|---|
CampaignIDS | Array of campaign IDs (no more than 10 IDs). The method returns the parameters of the ads that belong to the specified campaign. | One of the parameters: CampaignIDS or BannerIDS |
BannerIDS | Array of ad IDs. No more than 2000 IDs may be specified. This parameter overrides CampaignIDS: if both parameters are specified, ads are selected based on the IDs in the BannerIDS array. | |
Filter | Contains the BannersFilterInfo object, which defines the criteria for selecting ads. | No |
FieldsNames | Names of top-level parameters that must be received (the other parameters are not returned). If the array is omitted, returns all parameters. Note. It is a good idea to restrict the set of returned parameters if data is being requested for a large number of ads. Such requests create a high load on the API and might be processed very slowly, even to the point of not being processed at all. | No |
GetPhrases | Whether to return parameters for the keywords in the Phrases array:
If the GetPhrases parameter is omitted, the Yes value is assumed. | No |
Limit | Total number of ads to output parameters for in the response (a number greater than zero). When combined with the Offset parameter, this allows you to organize paginated selections from the database. The Limit and Offset parameters are used only when sorting by campaign IDs (CampaignIDS), and are ignored when sorting by ad IDs (BannerIDS). | No |
Offset | The number (position) of an ad in the selection from the database (a number greater than zero). In the response, ads are output starting from the specified number. Use the Limit parameter to specify the number of ads to return at a time. | No |
Currency | The currency to use for bids in the response. Acceptable values: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN. The value must match the campaign's currency. If this parameter is omitted or NULL, Yandex units are used. In this case, if the campaign operates using a real currency, returned values are converted from the campaign's currency to Yandex units (see the section Real currencies instead of Yandex units). If the value is something other than NULL but it does not match the currency of the campaign or one of the campaigns, an error is returned with code 245. | No |
AuctionBids | Whether to return auction results (the AuctionBids array) in the report — Yes/No. If omitted, No is assumed. | No |
BannersFilterInfo object | ||
StatusBannerModerate | Filter ads based on moderation results:
| No |
StatusPhrasesModerate | Filter ads based on results of keyword moderation:
| No |
StatusPhoneModerate | Filter ads based on results of business card moderation:
| No |
StatusActivating | Filter ads based on how current changes are:
After making changes to ads, it takes some time for the changes to take effect. This time is usually less than 40 minutes, but at high load times it can take up to three hours. | No |
StatusShow | Filter out ads that should be displayed or should not be displayed:
Turning the display on and off is done using methods ResumeBanners and StopBanners respectively. | No |
IsActive | Filter ads based on activation status:
| No |
StatusArchive | Filter ads based on archived status:
| No |
TagIDS | Filter ads by tags with the specified IDs. This parameter is incompatible with the Tags parameter. | No |
Tags | Filter ads based on the specified tags. This parameter is incompatible with the TagIDS parameter. | No |
StatusAdImageModerate | Filter ads based on image moderation status:
| No |
Parameter | Description | Required |
GetBannersInfo object | ||
---|---|---|
CampaignIDS | Array of campaign IDs (no more than 10 IDs). The method returns the parameters of the ads that belong to the specified campaign. | One of the parameters: CampaignIDS or BannerIDS |
BannerIDS | Array of ad IDs. No more than 2000 IDs may be specified. This parameter overrides CampaignIDS: if both parameters are specified, ads are selected based on the IDs in the BannerIDS array. | |
Filter | Contains the BannersFilterInfo object, which defines the criteria for selecting ads. | No |
FieldsNames | Names of top-level parameters that must be received (the other parameters are not returned). If the array is omitted, returns all parameters. Note. It is a good idea to restrict the set of returned parameters if data is being requested for a large number of ads. Such requests create a high load on the API and might be processed very slowly, even to the point of not being processed at all. | No |
GetPhrases | Whether to return parameters for the keywords in the Phrases array:
If the GetPhrases parameter is omitted, the Yes value is assumed. | No |
Limit | Total number of ads to output parameters for in the response (a number greater than zero). When combined with the Offset parameter, this allows you to organize paginated selections from the database. The Limit and Offset parameters are used only when sorting by campaign IDs (CampaignIDS), and are ignored when sorting by ad IDs (BannerIDS). | No |
Offset | The number (position) of an ad in the selection from the database (a number greater than zero). In the response, ads are output starting from the specified number. Use the Limit parameter to specify the number of ads to return at a time. | No |
Currency | The currency to use for bids in the response. Acceptable values: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN. The value must match the campaign's currency. If this parameter is omitted or NULL, Yandex units are used. In this case, if the campaign operates using a real currency, returned values are converted from the campaign's currency to Yandex units (see the section Real currencies instead of Yandex units). If the value is something other than NULL but it does not match the currency of the campaign or one of the campaigns, an error is returned with code 245. | No |
AuctionBids | Whether to return auction results (the AuctionBids array) in the report — Yes/No. If omitted, No is assumed. | No |
BannersFilterInfo object | ||
StatusBannerModerate | Filter ads based on moderation results:
| No |
StatusPhrasesModerate | Filter ads based on results of keyword moderation:
| No |
StatusPhoneModerate | Filter ads based on results of business card moderation:
| No |
StatusActivating | Filter ads based on how current changes are:
After making changes to ads, it takes some time for the changes to take effect. This time is usually less than 40 minutes, but at high load times it can take up to three hours. | No |
StatusShow | Filter out ads that should be displayed or should not be displayed:
Turning the display on and off is done using methods ResumeBanners and StopBanners respectively. | No |
IsActive | Filter ads based on activation status:
| No |
StatusArchive | Filter ads based on archived status:
| No |
TagIDS | Filter ads by tags with the specified IDs. This parameter is incompatible with the Tags parameter. | No |
Tags | Filter ads based on the specified tags. This parameter is incompatible with the TagIDS parameter. | No |
StatusAdImageModerate | Filter ads based on image moderation status:
| No |
Output data
Returns an array of BannerInfo objects containing the ad parameters. The output data structure in JSON 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)
}
...
],
"AdWarnings": [
(string)
...
],
"FixedOnModeration": (string),
"ModerateRejectionReasons": [
{ /* RejectReason */
"Type": (string),
"Text": (string)
}
...
],
"MinusKeywords": [
(string)
...
],
"AgeLabel": (string),
"AdImageHash": (string),
"AdGroupMobileBidAdjustment": (int)
}
...
]
}
Parameters are described below.
Parameter | Description |
BannerInfo object | |
---|---|
BannerID | The ad ID. To create an ad, set 0; to change the parameters of an ad, set its ID. |
CampaignID | The campaign ID. |
AdGroupID | ID of the ad group. |
AdGroupName | Name of the ad group. |
Type | Type of ad: Desktop or Mobile. |
Title | Title of the ad (up to 33 characters, including spaces and punctuation). |
Text | Text of the ad (up to 75 characters, including spaces and punctuation). |
Href | Link to the advertiser's website. It can contain wildcard variables (see section Links to the site). |
Domain | The domain that the Href link goes to. The domain is set automatically. If the link points to a redirect, the parameter specifies the end-domain. |
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. |
ContactInfo | The ContactInfo object with the advertiser's contact information (business card). |
Phrases | Array of BannerPhraseInfo objects with keyword parameters. Output if the GetPhrases input parameter has the value “Yes” or “WithPrices”, or is omitted. |
StatusActivating | Whether all changes made have taken effect — Yes/Pending. |
StatusArchive | Ad archive status:
|
StatusBannerModerate | Results of ad moderation (the text and link are checked):
|
StatusPhrasesModerate | Result of keyword moderation:
|
StatusPhoneModerate | Result of online business card moderation:
|
StatusAdImageModerate | Result of moderation for the image associated with the ad:
|
StatusShow | Whether ad impressions are enabled — Yes/No. Use the ResumeBanners and StopBanners methods to enable and disable impressions. Allowing displays does not mean that the ad is actually displayed. For impressions, other conditions must be met as well: sufficient funds, moderator approval of the campaign and ad, and enabled displays on the campaign level (the ResumeCampaign method). An actual impression corresponds to the Yes value in the IsActive parameter. |
IsActive | Whether the ad is active — Yes/No. "Active" is defined as the ad state in which impressions are turned on and off automatically, according to the time targeting settings or depending on the campaign balance. Ads are "inactive" when impressions are disabled by the user or Yandex manager, and cannot be enabled automatically. |
StatusSitelinksModerate | Result of sitelinks moderation:
|
Sitelinks | Array of Sitelink objects with sitelinks. The array must contain from 1 to 4 Sitelink objects, or be omitted. |
AdWarnings | An array containing flags for advertised objects belonging to special categories. For these categories, displaying ads is either prohibited, or must be accompanied by a warning in accordance with legislation of the Russian Federation. Possible groups:
|
FixedOnModeration | Whether typos were corrected during moderation — Yes/No. |
ModerateRejectionReasons | Array of RejectReason objects. These objects describe the reasons for rejecting the text of an ad, keyword, contact information, or sitelink. |
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. |
AgeLabel | Age category. For ads related to the baby_food group (the corresponding value is returned in the AdWarnings array), the age of the child in months: '0months', '1months', '2months', ..., '12months'. For all other ads, it is the age that the informational product is appropriate for. Possible values: '0+', '6+', '12+', '16+', '18+'. If an ad does not have an age category, this parameter is not returned in responses and is ignored during attempts to set it. Restriction. The API can only be used to change the value of the age category, if the ad has one. In order to change whether an ad has or doesn't have an age category, contact the Support service for Yandex Direct. |
AdImageHash | The hash for the image associated with the ad. |
AdGroupMobileBidAdjustment | Coefficient for setting bids on mobile devices. Used for ad groups and set as a percent of the desktop bid. A range of values from 50 to 1300. For more information about the coefficient, see Bid adjustments in the Help for Yandex Direct. Note. If the coefficient is not set for a group, calculations for bid prices on mobile devices use the coefficient for the campaign (the MobileBidAdjustment parameter), if available. |
ContactInfo object | |
ContactPerson | Contact person. A maximum of 155 characters. |
Country | Country. A maximum of 50 characters. |
CountryCode | The country code for the phone number. For example, “+7” for Russia. |
City | The city. A maximum of 50 characters. |
Street | Street. A maximum of 55 characters. |
House | House number. A maximum of 30 characters. |
Build | The building or unit number. A maximum of 10 characters. |
Apart | The apartment or office number. Maximum of 255 characters. |
CityCode | The area code or city code for the phone number. |
Phone | The contact phone number. |
PhoneExt | The phone extension, if an office PBX system is used. |
CompanyName | Name of the organization. Maximum of 255 characters. |
IMClient | The type of instant messaging network — icq, jabber, skype or mail_agent. |
IMLogin | The user name for the instant messaging network. |
ExtraMessage | Additional information on the advertised product or service. Maximum of 200 characters. |
ContactEmail | Email address. Maximum of 255 characters. |
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 |
OGRN | The OGRN code for a business registered in Russia. |
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. |
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 region on the map. From -180 to 180. |
y1 | Latitude of the lower-left corner of the region on the map. From -90 to 90. |
x2 | Longitude of the upper-right corner of the region on the map. From -180 to 180. |
y2 | Latitude of the upper-right corner of the region on the map. From -90 to 90. |
BannerPhraseInfo object | |
BannerID | The ad ID. |
CampaignID | The campaign ID. |
AdGroupID | ID of the ad group. |
PhraseID | The keyword ID. |
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. |
IsRubric | Whether the keyword is a Yandex Catalog category. Always contains the value No. |
Price | Bid on Yandex search (in the currency specified in the Currency parameter) 1 . Used only if a strategy with manual bid management is selected for the campaign. |
ContextPrice | Bid in the Yandex Advertising Network (in the currency specified in the Currency parameter) 1 . The parameter is available for editing in the following cases:
|
AutoBroker | Indicates that Autobroker is enabled. Always contains the value Yes. |
UserParams | PhraseUserParams object. Contains values of substitution variables for the website links (see the section Site links). |
StatusPhraseModerate | Results of moderation of the keyword:
|
AutoBudgetPriority | Priority of the keyword when using automatic strategies. Possible values:
|
Clicks | Number of clicks on all the group's ads that were shown on the search for this keyword. Calculated for the last 28 days. The calculation uses those days during which there was at least one click on an ad. |
Shows | Number of impressions for this keyword on the search, for all ads in the ad group. Calculated for the last 28 days. The calculation uses those days during which there was at least one ad impression for this keyword. |
ContextClicks | Number of clicks on all the group's ads that were shown in the Yandex Advertising Network for this keyword. Calculated for the last 28 days. The calculation uses those days during which there was at least one click on an ad. |
ContextShows | Number of impressions for this keyword in the Yandex Advertising Network, for all ads in the ad group. Calculated for the last 28 days. The calculation uses those days during which there was at least one ad impression for this keyword. |
Min | Price (in the currency specified in the Currency parameter) 2 that secures impressions in the Guaranteed Placement block for most of the ads in the group. |
Max | Price (in the currency specified in the Currency parameter) 2 that secures impressions in the top position in the Guaranteed Placement block for most of the ads in the group. |
PremiumMin | Price (in the currency specified in the Currency parameter) 2 that secures impressions in Premium Placement for most of the ads in the group. |
PremiumMax | Price (in the currency specified in the Currency parameter) 2 that secures impressions in the top position in Premium Placement for most of the ads in the group. |
LowCTRWarning | The keyword has a low CTR and may be disabled soon — Yes/No. Restriction. This parameter is no longer relevant for new keywords, since keywords are no longer excluded for a low CTR. |
LowCTR | The keyword is disabled in the search due to a low CTR — Yes/No. Restriction. This parameter is no longer relevant for new keywords, since keywords are no longer excluded for a low CTR. |
ContextLowCTR | The keyword is disabled on Yandex Advertising Network sites due to a low CTR — Yes/No. Restriction. This parameter is no longer relevant for new keywords, since keywords are no longer excluded for a low CTR. |
Coverage | Array of CoverageInfo objects, which indicate the projected audience coverage on the search. Restriction. This parameter is no longer relevant and should not be used for selecting bids. |
ContextCoverage | Array of CoverageInfo objects, which indicate the projected audience coverage in the Yandex Advertising Network. This parameter is useful for bid selection for keywords. |
Prices | Array of minimum bids for all positions in Premium Placement and Guaranteed Placement (in the currency specified in the Currency parameter) 2 . |
CurrentOnSearch | The final CPC when Autobroker is used (in the currency specified in the Currency parameter) 2 . If the keyword does not generate impressions on the search, or the keyword is disabled on the search due to a low CTR, the NULL value is returned in the parameter. |
MinPrice | Minimum price, set for each advertiser individually (in the currency specified in the Currency parameter) 2 . |
StatusPaused | Impressions are paused for the keyword — Yes/No. To pause and resume impressions, use the Keyword (Live) method. |
Currency | The currency that bids are shown in. Acceptable values: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN. If this parameter is omitted or NULL, Yandex units are used. |
AuctionBids | Array of PhraseAuctionBids objects containing auction results for the keyword: the bid for each position in Premium Placement and in the lower block, along with the actual CPC for each position. |
CoverageInfo object | |
Probability | Frequency of impressions for the bid from the Price parameter. It is specified in the ContextCoverage array as a percent from 0 to 100. Used for selecting bids. |
Price | The bid (in the currency specified in the Currency parameter) 2 for which the Probability parameter contains the frequency of impressions. |
PhraseUserParams object | |
Param1 | Value of the |
Param2 | Value of the |
Sitelink object | |
Title | Sitelink text. |
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. |
RejectReason object | |
Type | Type of object rejected during moderation: Banner, Phrases, ContactInfo or Sitelink. |
Text | Reason for rejection during moderation. |
PhraseAuctionBids object | |
Position | Display position: Pmn, where
For example, P12 is the second position in Premium Placement, and P21 is the top position in Guaranteed Placement. |
Bid | Minimum bid for the specified position (in the currency set in the Currency parameter) 2 . |
Price | Actual CPC for the specified position (in the currency set in the Currency parameter) 2 . |
Notes | |
|
Parameter | Description |
BannerInfo object | |
---|---|
BannerID | The ad ID. To create an ad, set 0; to change the parameters of an ad, set its ID. |
CampaignID | The campaign ID. |
AdGroupID | ID of the ad group. |
AdGroupName | Name of the ad group. |
Type | Type of ad: Desktop or Mobile. |
Title | Title of the ad (up to 33 characters, including spaces and punctuation). |
Text | Text of the ad (up to 75 characters, including spaces and punctuation). |
Href | Link to the advertiser's website. It can contain wildcard variables (see section Links to the site). |
Domain | The domain that the Href link goes to. The domain is set automatically. If the link points to a redirect, the parameter specifies the end-domain. |
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. |
ContactInfo | The ContactInfo object with the advertiser's contact information (business card). |
Phrases | Array of BannerPhraseInfo objects with keyword parameters. Output if the GetPhrases input parameter has the value “Yes” or “WithPrices”, or is omitted. |
StatusActivating | Whether all changes made have taken effect — Yes/Pending. |
StatusArchive | Ad archive status:
|
StatusBannerModerate | Results of ad moderation (the text and link are checked):
|
StatusPhrasesModerate | Result of keyword moderation:
|
StatusPhoneModerate | Result of online business card moderation:
|
StatusAdImageModerate | Result of moderation for the image associated with the ad:
|
StatusShow | Whether ad impressions are enabled — Yes/No. Use the ResumeBanners and StopBanners methods to enable and disable impressions. Allowing displays does not mean that the ad is actually displayed. For impressions, other conditions must be met as well: sufficient funds, moderator approval of the campaign and ad, and enabled displays on the campaign level (the ResumeCampaign method). An actual impression corresponds to the Yes value in the IsActive parameter. |
IsActive | Whether the ad is active — Yes/No. "Active" is defined as the ad state in which impressions are turned on and off automatically, according to the time targeting settings or depending on the campaign balance. Ads are "inactive" when impressions are disabled by the user or Yandex manager, and cannot be enabled automatically. |
StatusSitelinksModerate | Result of sitelinks moderation:
|
Sitelinks | Array of Sitelink objects with sitelinks. The array must contain from 1 to 4 Sitelink objects, or be omitted. |
AdWarnings | An array containing flags for advertised objects belonging to special categories. For these categories, displaying ads is either prohibited, or must be accompanied by a warning in accordance with legislation of the Russian Federation. Possible groups:
|
FixedOnModeration | Whether typos were corrected during moderation — Yes/No. |
ModerateRejectionReasons | Array of RejectReason objects. These objects describe the reasons for rejecting the text of an ad, keyword, contact information, or sitelink. |
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. |
AgeLabel | Age category. For ads related to the baby_food group (the corresponding value is returned in the AdWarnings array), the age of the child in months: '0months', '1months', '2months', ..., '12months'. For all other ads, it is the age that the informational product is appropriate for. Possible values: '0+', '6+', '12+', '16+', '18+'. If an ad does not have an age category, this parameter is not returned in responses and is ignored during attempts to set it. Restriction. The API can only be used to change the value of the age category, if the ad has one. In order to change whether an ad has or doesn't have an age category, contact the Support service for Yandex Direct. |
AdImageHash | The hash for the image associated with the ad. |
AdGroupMobileBidAdjustment | Coefficient for setting bids on mobile devices. Used for ad groups and set as a percent of the desktop bid. A range of values from 50 to 1300. For more information about the coefficient, see Bid adjustments in the Help for Yandex Direct. Note. If the coefficient is not set for a group, calculations for bid prices on mobile devices use the coefficient for the campaign (the MobileBidAdjustment parameter), if available. |
ContactInfo object | |
ContactPerson | Contact person. A maximum of 155 characters. |
Country | Country. A maximum of 50 characters. |
CountryCode | The country code for the phone number. For example, “+7” for Russia. |
City | The city. A maximum of 50 characters. |
Street | Street. A maximum of 55 characters. |
House | House number. A maximum of 30 characters. |
Build | The building or unit number. A maximum of 10 characters. |
Apart | The apartment or office number. Maximum of 255 characters. |
CityCode | The area code or city code for the phone number. |
Phone | The contact phone number. |
PhoneExt | The phone extension, if an office PBX system is used. |
CompanyName | Name of the organization. Maximum of 255 characters. |
IMClient | The type of instant messaging network — icq, jabber, skype or mail_agent. |
IMLogin | The user name for the instant messaging network. |
ExtraMessage | Additional information on the advertised product or service. Maximum of 200 characters. |
ContactEmail | Email address. Maximum of 255 characters. |
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 |
OGRN | The OGRN code for a business registered in Russia. |
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. |
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 region on the map. From -180 to 180. |
y1 | Latitude of the lower-left corner of the region on the map. From -90 to 90. |
x2 | Longitude of the upper-right corner of the region on the map. From -180 to 180. |
y2 | Latitude of the upper-right corner of the region on the map. From -90 to 90. |
BannerPhraseInfo object | |
BannerID | The ad ID. |
CampaignID | The campaign ID. |
AdGroupID | ID of the ad group. |
PhraseID | The keyword ID. |
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. |
IsRubric | Whether the keyword is a Yandex Catalog category. Always contains the value No. |
Price | Bid on Yandex search (in the currency specified in the Currency parameter) 1 . Used only if a strategy with manual bid management is selected for the campaign. |
ContextPrice | Bid in the Yandex Advertising Network (in the currency specified in the Currency parameter) 1 . The parameter is available for editing in the following cases:
|
AutoBroker | Indicates that Autobroker is enabled. Always contains the value Yes. |
UserParams | PhraseUserParams object. Contains values of substitution variables for the website links (see the section Site links). |
StatusPhraseModerate | Results of moderation of the keyword:
|
AutoBudgetPriority | Priority of the keyword when using automatic strategies. Possible values:
|
Clicks | Number of clicks on all the group's ads that were shown on the search for this keyword. Calculated for the last 28 days. The calculation uses those days during which there was at least one click on an ad. |
Shows | Number of impressions for this keyword on the search, for all ads in the ad group. Calculated for the last 28 days. The calculation uses those days during which there was at least one ad impression for this keyword. |
ContextClicks | Number of clicks on all the group's ads that were shown in the Yandex Advertising Network for this keyword. Calculated for the last 28 days. The calculation uses those days during which there was at least one click on an ad. |
ContextShows | Number of impressions for this keyword in the Yandex Advertising Network, for all ads in the ad group. Calculated for the last 28 days. The calculation uses those days during which there was at least one ad impression for this keyword. |
Min | Price (in the currency specified in the Currency parameter) 2 that secures impressions in the Guaranteed Placement block for most of the ads in the group. |
Max | Price (in the currency specified in the Currency parameter) 2 that secures impressions in the top position in the Guaranteed Placement block for most of the ads in the group. |
PremiumMin | Price (in the currency specified in the Currency parameter) 2 that secures impressions in Premium Placement for most of the ads in the group. |
PremiumMax | Price (in the currency specified in the Currency parameter) 2 that secures impressions in the top position in Premium Placement for most of the ads in the group. |
LowCTRWarning | The keyword has a low CTR and may be disabled soon — Yes/No. Restriction. This parameter is no longer relevant for new keywords, since keywords are no longer excluded for a low CTR. |
LowCTR | The keyword is disabled in the search due to a low CTR — Yes/No. Restriction. This parameter is no longer relevant for new keywords, since keywords are no longer excluded for a low CTR. |
ContextLowCTR | The keyword is disabled on Yandex Advertising Network sites due to a low CTR — Yes/No. Restriction. This parameter is no longer relevant for new keywords, since keywords are no longer excluded for a low CTR. |
Coverage | Array of CoverageInfo objects, which indicate the projected audience coverage on the search. Restriction. This parameter is no longer relevant and should not be used for selecting bids. |
ContextCoverage | Array of CoverageInfo objects, which indicate the projected audience coverage in the Yandex Advertising Network. This parameter is useful for bid selection for keywords. |
Prices | Array of minimum bids for all positions in Premium Placement and Guaranteed Placement (in the currency specified in the Currency parameter) 2 . |
CurrentOnSearch | The final CPC when Autobroker is used (in the currency specified in the Currency parameter) 2 . If the keyword does not generate impressions on the search, or the keyword is disabled on the search due to a low CTR, the NULL value is returned in the parameter. |
MinPrice | Minimum price, set for each advertiser individually (in the currency specified in the Currency parameter) 2 . |
StatusPaused | Impressions are paused for the keyword — Yes/No. To pause and resume impressions, use the Keyword (Live) method. |
Currency | The currency that bids are shown in. Acceptable values: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN. If this parameter is omitted or NULL, Yandex units are used. |
AuctionBids | Array of PhraseAuctionBids objects containing auction results for the keyword: the bid for each position in Premium Placement and in the lower block, along with the actual CPC for each position. |
CoverageInfo object | |
Probability | Frequency of impressions for the bid from the Price parameter. It is specified in the ContextCoverage array as a percent from 0 to 100. Used for selecting bids. |
Price | The bid (in the currency specified in the Currency parameter) 2 for which the Probability parameter contains the frequency of impressions. |
PhraseUserParams object | |
Param1 | Value of the |
Param2 | Value of the |
Sitelink object | |
Title | Sitelink text. |
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. |
RejectReason object | |
Type | Type of object rejected during moderation: Banner, Phrases, ContactInfo or Sitelink. |
Text | Reason for rejection during moderation. |
PhraseAuctionBids object | |
Position | Display position: Pmn, where
For example, P12 is the second position in Premium Placement, and P21 is the top position in Guaranteed Placement. |
Bid | Minimum bid for the specified position (in the currency set in the Currency parameter) 2 . |
Price | Actual CPC for the specified position (in the currency set in the Currency parameter) 2 . |
Notes | |
|
Examples of input data
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
}