GetBanners (Live)

Returns parameters for ad groups, ads, and keywords.

Attention.

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

Attention. The method only returns text and image ads. To work with all types of ads, use the Ads service in version 5 of the API. More about ad types...

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:

  • No — Do not return keyword parameters.
  • Yes — Return abbreviated keyword information.
  • WithPrices — Return complete keyword information, including prices and statistics.

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:

  • New — Ad has not been checked (“Draft” status).
  • Pending — Moderation in progress.
  • Yes — Approved.
  • No — Rejected.
  • PreliminaryAccept — The ad has been tentatively accepted but the final result will be available later.
No
StatusPhrasesModerate

Filter ads based on results of keyword moderation:

  • New — Keywords were not checked.
  • Pending — Moderation in progress.
  • Yes — At least one keyword was approved (some keywords might have been rejected).
  • No — All keywords were rejected.
  • PreliminaryAccept — The keywords have been tentatively accepted but the final result will be available later.
No
StatusPhoneModerate

Filter ads based on results of business card moderation:

  • New — Contact info has not been checked.
  • Pending — Moderation in progress.
  • Yes — Approved.
  • No — Rejected.
No
StatusActivating

Filter ads based on how current changes are:

  • Yes — Changes have taken effect.
  • Pending — Waiting for changes to take effect.

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:

  • Yes — Display enabled.
  • No — Display disabled.

Turning the display on and off is done using methods ResumeBanners and StopBanners respectively.

No
IsActive

Filter ads based on activation status:

  • Yes — Activated ads.
  • No — Inactive ads.
No
StatusArchive

Filter ads based on archived status:

  • Yes — Archived.
  • No — Not archived.
  • CurrencyConverted — The ads were automatically archived when switching the client to using currency (see the section Real currencies instead of Yandex units).
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:
  • New — Image has not been checked.
  • Pending — Moderation in progress.
  • Yes — Approved.
  • No — Rejected.
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:

  • No — Do not return keyword parameters.
  • Yes — Return abbreviated keyword information.
  • WithPrices — Return complete keyword information, including prices and statistics.

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:

  • New — Ad has not been checked (“Draft” status).
  • Pending — Moderation in progress.
  • Yes — Approved.
  • No — Rejected.
  • PreliminaryAccept — The ad has been tentatively accepted but the final result will be available later.
No
StatusPhrasesModerate

Filter ads based on results of keyword moderation:

  • New — Keywords were not checked.
  • Pending — Moderation in progress.
  • Yes — At least one keyword was approved (some keywords might have been rejected).
  • No — All keywords were rejected.
  • PreliminaryAccept — The keywords have been tentatively accepted but the final result will be available later.
No
StatusPhoneModerate

Filter ads based on results of business card moderation:

  • New — Contact info has not been checked.
  • Pending — Moderation in progress.
  • Yes — Approved.
  • No — Rejected.
No
StatusActivating

Filter ads based on how current changes are:

  • Yes — Changes have taken effect.
  • Pending — Waiting for changes to take effect.

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:

  • Yes — Display enabled.
  • No — Display disabled.

Turning the display on and off is done using methods ResumeBanners and StopBanners respectively.

No
IsActive

Filter ads based on activation status:

  • Yes — Activated ads.
  • No — Inactive ads.
No
StatusArchive

Filter ads based on archived status:

  • Yes — Archived.
  • No — Not archived.
  • CurrencyConverted — The ads were automatically archived when switching the client to using currency (see the section Real currencies instead of Yandex units).
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:
  • New — Image has not been checked.
  • Pending — Moderation in progress.
  • Yes — Approved.
  • No — Rejected.
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:

  • Yes — Archived.
  • No — Not archived.
  • CurrencyConverted — Was automatically archived when switching the client to using currency, and cannot be unarchived (see the section Real currencies instead of Yandex units).
StatusBannerModerate

Results of ad moderation (the text and link are checked):

  • New — Ad has not been checked (“Draft” status).
  • Pending — Moderation in progress.
  • Yes — Approved.
  • No — Rejected.
  • PreliminaryAccept — The ad has been tentatively accepted but the final result will be available later.
StatusPhrasesModerate

Result of keyword moderation:

  • New — Keywords were not checked.
  • Pending — Moderation in progress.
  • Yes — At least one keyword was approved (some keywords might have been rejected).
  • No — All keywords were rejected.
  • PreliminaryAccept — The keywords have been tentatively accepted but the final result will be available later.
StatusPhoneModerate

Result of online business card moderation:

  • New — Contact info has not been checked.
  • Pending — Moderation in progress.
  • Yes — Approved.
  • No — Rejected.
StatusAdImageModerate Result of moderation for the image associated with the ad:
  • New — Image has not been checked.
  • Pending — Moderation in progress.
  • Yes — Approved.
  • No — Rejected.
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:
  • New — Sitelinks have not been checked.
  • Pending — Moderation in progress.
  • Yes — Approved.
  • No — Rejected.
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:

  • abortion — Medical services intended to artificially terminate a pregnancy.
  • alcohol — Alcohol, beer or alcoholic beverages.
  • baby_food — Baby food.
  • dietarysuppl — Dietary supplements.
  • medicine — Medicine, medical devices or equipment or medical services, including treatment methods.
  • pseudoweapon — Products that are similar to a weapon.
  • tobacco — Tobacco and tobacco products.
  • project_declaration — Shared-equity construction project.
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:

"day_from;day_to;hour_from;minute_from;hour_to;minute_to"

For example, the string "0;4;10;0;18;0" sets the following schedule:

0;4 — Monday to Friday

10;0 — from 10:00 am

18;0 — to 6:00 pm

The schedule may consist of several strings in this format, for example: "0;4;10;0;18;0;5;6;11;0;16;0". Here, in addition to the previous example, the schedule also includes:

5;6 — Saturday and Sunday

11;0 — from 11:00 am

16;0 — to 4:00 pm

A 24-hour schedule is set using the string "0;6;00;00;00;00".

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:

  1. When the MaximumCoverage strategy is selected for the Yandex Advertising Network.

  2. When the Default strategy is selected for the Yandex Advertising Network and the keyword is disabled on the search due to a low CTR.

    For new keywords this condition is irrelevant, since keywords are no longer disabled for a low CTR.

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:

  • New — Keyword has not been moderated.
  • Yes — Accepted.
  • No — Rejected.
AutoBudgetPriority

Priority of the keyword when using automatic strategies. Possible values:

  • Low — Low priority.
  • Medium — Average priority.
  • High — High priority.
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 {param1} substitution variable. No more than 255 bytes.

Param2

Value of the {param2} substitution variable. No more than 255 bytes.

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
  • m is the block number (1 is Premium Placement, 2 is Guaranteed Placement).
  • n is the position number within the block.

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
  1. If the returned bids are converted from the campaign's currency to Yandex units, they are mathematically rounded to the second decimal point (for all currencies, including the tenge).

  2. If the returned bid parameters (prices of display positions and audience coverage, and competitors' bids) are converted from the campaign's currency to Yandex units, they are rounded up to the nearest bid increment (0.01 units; also see the section Real currencies instead of Yandex units).
  3. In rare cases, prices for display positions and certain other parameters related to auction results can have the NULL value, which indicates an API error getting data. We recommend repeating the method call later.

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:

  • Yes — Archived.
  • No — Not archived.
  • CurrencyConverted — Was automatically archived when switching the client to using currency, and cannot be unarchived (see the section Real currencies instead of Yandex units).
StatusBannerModerate

Results of ad moderation (the text and link are checked):

  • New — Ad has not been checked (“Draft” status).
  • Pending — Moderation in progress.
  • Yes — Approved.
  • No — Rejected.
  • PreliminaryAccept — The ad has been tentatively accepted but the final result will be available later.
StatusPhrasesModerate

Result of keyword moderation:

  • New — Keywords were not checked.
  • Pending — Moderation in progress.
  • Yes — At least one keyword was approved (some keywords might have been rejected).
  • No — All keywords were rejected.
  • PreliminaryAccept — The keywords have been tentatively accepted but the final result will be available later.
StatusPhoneModerate

Result of online business card moderation:

  • New — Contact info has not been checked.
  • Pending — Moderation in progress.
  • Yes — Approved.
  • No — Rejected.
StatusAdImageModerate Result of moderation for the image associated with the ad:
  • New — Image has not been checked.
  • Pending — Moderation in progress.
  • Yes — Approved.
  • No — Rejected.
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:
  • New — Sitelinks have not been checked.
  • Pending — Moderation in progress.
  • Yes — Approved.
  • No — Rejected.
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:

  • abortion — Medical services intended to artificially terminate a pregnancy.
  • alcohol — Alcohol, beer or alcoholic beverages.
  • baby_food — Baby food.
  • dietarysuppl — Dietary supplements.
  • medicine — Medicine, medical devices or equipment or medical services, including treatment methods.
  • pseudoweapon — Products that are similar to a weapon.
  • tobacco — Tobacco and tobacco products.
  • project_declaration — Shared-equity construction project.
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:

"day_from;day_to;hour_from;minute_from;hour_to;minute_to"

For example, the string "0;4;10;0;18;0" sets the following schedule:

0;4 — Monday to Friday

10;0 — from 10:00 am

18;0 — to 6:00 pm

The schedule may consist of several strings in this format, for example: "0;4;10;0;18;0;5;6;11;0;16;0". Here, in addition to the previous example, the schedule also includes:

5;6 — Saturday and Sunday

11;0 — from 11:00 am

16;0 — to 4:00 pm

A 24-hour schedule is set using the string "0;6;00;00;00;00".

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:

  1. When the MaximumCoverage strategy is selected for the Yandex Advertising Network.

  2. When the Default strategy is selected for the Yandex Advertising Network and the keyword is disabled on the search due to a low CTR.

    For new keywords this condition is irrelevant, since keywords are no longer disabled for a low CTR.

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:

  • New — Keyword has not been moderated.
  • Yes — Accepted.
  • No — Rejected.
AutoBudgetPriority

Priority of the keyword when using automatic strategies. Possible values:

  • Low — Low priority.
  • Medium — Average priority.
  • High — High priority.
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 {param1} substitution variable. No more than 255 bytes.

Param2

Value of the {param2} substitution variable. No more than 255 bytes.

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
  • m is the block number (1 is Premium Placement, 2 is Guaranteed Placement).
  • n is the position number within the block.

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
  1. If the returned bids are converted from the campaign's currency to Yandex units, they are mathematically rounded to the second decimal point (for all currencies, including the tenge).

  2. If the returned bid parameters (prices of display positions and audience coverage, and competitors' bids) are converted from the campaign's currency to Yandex units, they are rounded up to the nearest bid increment (0.01 units; also see the section Real currencies instead of Yandex units).
  3. In rare cases, prices for display positions and certain other parameters related to auction results can have the NULL value, which indicates an API error getting data. We recommend repeating the method call later.

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
}