GetBannerPhrasesFilter (Live)

Returns information about keywords and allows limiting the set of returned data.

What's new in Live version 4

Added output parameter StatusPaused.

Added output parameters ContextClicks and ContextShows.

Added input parameter Currency and output parameter Currency.

Added output parameter AdGroupID.

Added output parameter AuctionBids.

Restrictions

Retrieving keywords from archived campaigns is not available.

Alert

The method only supports “Text & Image Ads”. To work with keywords for all ad types, use the Keywords service in API version 5.

Input data

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

{
   "method": "GetBannerPhrasesFilter",
   "param": {
      /* BannerPhrasesFilterRequestInfo */
      "BannerIDS": [
         (long)
         ...
      ],
      "FieldsNames": [
         (string)
         ...
      ],
      "ConsiderTimeTarget": (string),
      "RequestPrices": (string),
      "Currency": (string)
   }
}

The parameters are described below.

Parameter	Description	Required
BannerPhrasesFilterRequestInfo object
`BannerIDS`	An array of ad IDs (up to 1000).	Yes
`FieldsNames`	An array containing the names of parameters to return in the response. If not specified, all available parameters are returned. The parameters `CampaignID`, `BannerID`, `PhraseID` are always returned.	No
`RequestPrices`	Return statistics and prices — Yes/No. The default value is Yes. Statistics and prices are returned in the parameters `ContextPrice`, `Clicks`, `Shows`, `Min`, `Max`, `PremiumMin`, `PremiumMax`, `LowCTRWarning`, `LowCTR`, `ContextLowCTR`, `Coverage`, `ContextCoverage`, `Prices`, `CurrentOnSearch`, `MinPrice`. Their names can be specified in the `FieldsNames` array.	No
`ConsiderTimeTarget`	Calculate impression position prices without considering bids from competitors' ads that are paused (paused according to a schedule) — Yes/No. The default value is No (all ads are considered).	No
`Currency`	The currency in which bids should be expressed in the response. Possible values: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN. The value must match the campaign currency. If the parameter is absent or equals NULL, Yandex units are assumed. In this case, if the campaign uses a real currency, the returned values are converted from the campaign currency to Yandex units. If the value is not NULL and does not match the currency of the campaign (or one of the campaigns), an error with code 245 is returned.	No

Output data

The method returns an array of BannerPhraseInfo objects with information about keywords. The structure of the output data in JSON format is shown below.

Note

The following parameters are in the WSDL but are only returned in the response of the GetForecast method: FirstPlaceClicks: (int), PremiumClicks: (int), CTR: (float), FirstPlaceCTR: (float), PremiumCTR: (float)

{
   "data": [
      {  /* 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)
            }
            ...
         ]
      }
      ...
   ]
}

The parameters are described below.

Parameter	Description
BannerPhraseInfo object
`BannerID`	Ad ID.
`CampaignID`	Campaign ID.
`AdGroupID`	Ad group ID.
`PhraseID`	Keyword ID.
`Phrase`	Keyword. May contain negative keywords, which are specified with a minus sign before the word, for example, [lightning -thunder -rain]. Negative keywords shared by multiple keywords should preferably be set in the `MinusKeywords` ad group parameter. The length of a keyword is up to 4,096 characters. The “!” operator before a negative keyword is not counted in the keyword length (the sequence “-!” is counted as one character). Up to 7 words in a keyword, not counting stop words and negative keywords. Each word and negative keyword is up to 35 characters, not counting the minus sign before a negative keyword.
`IsRubric`	Indicates that 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 manual bid management strategy is selected for the campaign.
`ContextPrice`	Bid in the Yandex Advertising Network (YAN) (in the currency specified in the `Currency` parameter)1. The parameter is available for modification in the following cases: The MaximumCoverage strategy is selected for Yandex Advertising Network (YAN). The Default strategy is selected for YAN and the keyword is disabled on search due to a low click-through rate (CTR). This condition does not apply to new keywords, since keywords are no longer disabled for low CTR.
`AutoBroker`	Indicates that autobroker is enabled. Always contains the value Yes.
`UserParams`	`PhraseUserParams` object. Contains the values of substitution variables for generating the link to the website.
`StatusPhraseModerate`	Keyword review result: New — the keyword has not been reviewed; Yes — accepted; No — rejected;
`AutoBudgetPriority`	Keyword priority when using automatic strategies. Possible values: Low — low priority; Medium — medium priority; High — high priority.
`Clicks`	Number of clicks on all ads in the group served on search for this keyword. Calculated over 28 days from the current date. Only days with at least one ad click are included in the calculation.
`Shows`	Number of impressions of all ads in the group for this keyword on search. Calculated over 28 days from the current date. Only days with at least one impression for this keyword are included in the calculation.
`ContextClicks`	Number of clicks on all ads in the group served in the Yandex Advertising Network for this keyword. Calculated over 28 days from the current date. Only days with at least one ad click are included in the calculation.
`ContextShows`	Number of impressions of all ads in the group for this keyword in the Yandex Advertising Network. Calculated over 28 days from the current date. Only days with at least one impression for this keyword are included in the calculation.
`Min`	Price that ensures most ads in the group are shown in the Guaranteed placement block — in the currency specified in the `Currency` parameter. If the returned auction parameters (impression position prices, audience reach prices, competitor bids) are converted from the campaign currency to Yandex units, they are rounded up to the nearest bidding increment (0.01 Yandex units).
`Max`	Price that ensures most ads in the group are shown in the first position in the Guaranteed placement block — in the currency specified in the `Currency` parameter. If the returned auction parameters (impression position prices, audience reach prices, competitor bids) are converted from the campaign currency to Yandex units, they are rounded up to the nearest bidding increment (0.01 Yandex units).
`PremiumMin`	Price that ensures most ads in the group are shown in Premium placement — in the currency specified in the `Currency` parameter. If the returned auction parameters (impression position prices, audience reach prices, competitor bids) are converted from the campaign currency to Yandex units, they are rounded up to the nearest bidding increment (0.01 Yandex units).
`PremiumMax`	Price that ensures most ads in the group are shown in the first position in Premium placement — in the currency specified in the `Currency` parameter. If the returned auction parameters (impression position prices, audience reach prices, competitor bids) are converted from the campaign currency to Yandex units, they are rounded up to the nearest bidding increment (0.01 Yandex units).
`LowCTRWarning`	The keyword has a low CTR and may be disabled soon — Yes/No. Alert This parameter is no longer relevant for new keywords, since keywords are no longer disabled for low CTR.
`LowCTR`	The keyword has been disabled on search due to a low CTR — Yes/No. Alert This parameter is no longer relevant for new keywords, since keywords are no longer disabled for low CTR.
`ContextLowCTR`	The keyword has been disabled on YAN sites due to a low CTR — Yes/No. Alert This parameter is no longer relevant for new keywords, since keywords are no longer disabled for low CTR.
`Coverage`	Array of `CoverageInfo` objects indicating the predicted audience reach on search. Alert This parameter is deprecated and should not be used for bid selection.
`ContextCoverage`	Array of `CoverageInfo` objects indicating the predicted audience reach in YAN. The parameter is useful for bid selection for keywords.
`Prices`	Array of minimum bids for all positions in Premium placement and in the Guaranteed placement block (in the currency specified in the `Currency` parameter). If the returned auction parameters (impression position prices, audience reach prices, competitor bids) are converted from the campaign currency to Yandex units, they are rounded up to the nearest bidding increment (0.01 Yandex units).
`CurrentOnSearch`	The final cost per click after autobroker is applied (in the currency specified in the `Currency` parameter). If the returned auction parameters (impression position prices, audience reach prices, competitor bids) are converted from the campaign currency to Yandex units, they are rounded up to the nearest bidding increment (0.01 Yandex units). If the ad is not being served on search for this keyword, or the keyword is disabled on search due to a low CTR, the parameter returns NULL.
`MinPrice`	Minimum price set individually for each advertiser (in the currency specified in the `Currency` parameter). If the returned auction parameters (impression position prices, audience reach prices, competitor bids) are converted from the campaign currency to Yandex units, they are rounded up to the nearest bidding increment (0.01 Yandex units).
`StatusPaused`	Impressions for the keyword are paused — Yes/No. Impressions can be paused and resumed using the Keyword (Live) method.
`Currency`	The currency in which bids are expressed. Possible values: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN. If the parameter is absent or equals NULL, Yandex units are assumed.
`AuctionBids`	Array of `PhraseAuctionBids` objects containing auction results for the keyword: the bid for each position in Premium placement and in the Guaranteed placement block, as well as the charged price for each position.
CoverageInfo object
`Probability`	Impression frequency at the bid specified in the `Price` parameter. In the `ContextCoverage` array, expressed as a percentage from 0 to 100. Used for bid selection.
`Price`	Bid for which the `Probability` parameter contains the impression frequency (in the currency specified in the `Currency` parameter). If the returned auction parameters (impression position prices, audience reach prices, competitor bids) are converted from the campaign currency to Yandex units, they are rounded up to the nearest bidding increment (0.01 Yandex units).
PhraseUserParams object
`Param1`	Value of the `{param1}` substitution variable. Up to 255 bytes.
`Param2`	Value of the `{param2}` substitution variable. Up to 255 bytes.
PhraseAuctionBids object
`Position`	Impression position: P_mn_, where m — block number (1 — Premium placement, 2 — Guaranteed placement block); n — position number within the block. For example, P12 — second position in Premium placement, P21 — first position in the Guaranteed placement block.
`Bid`	Minimum bid for the specified position (in the currency specified in the `Currency` parameter). If the returned auction parameters (impression position prices, audience reach prices, competitor bids) are converted from the campaign currency to Yandex units, they are rounded up to the nearest bidding increment (0.01 Yandex units).
`Price`	Charged price for the specified position (in the currency specified in the `Currency` parameter). If the returned auction parameters (impression position prices, audience reach prices, competitor bids) are converted from the campaign currency to Yandex units, they are rounded up to the nearest bidding increment (0.01 Yandex units).
Notes
If the returned bids are converted from the campaign currency to Yandex units, they are rounded according to standard mathematical rules to two decimal places (for all currencies, including tenge). If the returned auction parameters (impression position prices, audience reach prices, competitor bids) are converted from the campaign currency to Yandex units, they are rounded up to the nearest bidding increment (0.01 Yandex units). In rare cases, impression position prices and some other parameters related to auction results may have a NULL value, which indicates an error retrieving data on the API side. It is recommended to retry the method call after some time.

Input data examples

Python

{
   'BannerIDS': [20155899],
   'FieldsNames': ['Phrase','Price','Phrase','MinPrice','Clicks'],
   'RequestPrices': 'Yes',
   'ConsiderTimeTarget': 'Yes'
}

PHP

array(
   'BannerIDS' => array(20155899),
   'FieldsNames' => array('Phrase','Price','Phrase','MinPrice','Clicks'),
   'RequestPrices' => 'Yes',
   'ConsiderTimeTarget' ='Yes'
)

Perl

{
   'BannerIDS' => [20155899],
   'FieldsNames' => ['Phrase','Price','Phrase','MinPrice','Clicks'],
   'RequestPrices' => 'Yes',
   'ConsiderTimeTarget' ='Yes'
}

Was the article helpful?

GetBannerPhrasesFilter

ModerateBanners