GetBannerPhrasesFilter

Returns information about keywords and allows limiting the composition of returned data.
A GetBannerPhrasesFilter (Live) version of this method exists.

Restrictions

Retrieving keywords from archived campaigns is not available.

Alert

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

Input data

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

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

The parameters are described below.

^Parameter	^Description	^Required
_{BannerPhrasesFilterRequestInfo object}
`BannerIDS`	Array of ad IDs (no more than 1000).	Yes
`FieldsNames`	Array containing names of parameters returned in the response. If not specified, all provided parameters are returned. The parameters `CampaignID`, `BannerID`, `PhraseID` are always returned. Additionally, the parameters `AutoBroker`, `StatusPhraseModerate`, `IsRubric`, `Price`, `Phrase` may be returned. Their names can be specified in the `FieldsNames` array. To return all parameters, do not specify the array.	No
`RequestPrices`	Return statistics and prices — Yes/No. Default value Yes. Statistics and prices are returned in the parameters `ContextPrice`, `Clicks`, `Shows`, `Min`, `Max`, `PremiumMin`, `PremiumMax`, `LowCTRWarning`, `LowCTR`, `ContextLowCTR`, `Coverage`, `ContextCoverage`, `Prices`, `CurrentOnSearch`, `MinPrice`. The names of these parameters can be specified in the `FieldsNames` array.	No

Output data

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

{
   "data": [
      {  /* BannerPhraseInfo */
         "BannerID": (long),
         "CampaignID": (int),
         "PhraseID": (long),
         "Phrase": (string),
         "IsRubric": (string),
         "Price": (float),
         "ContextPrice": (float),
         "AutoBroker": (string),
         "UserParams": {
            /* PhraseUserParams */
            "Param1": (string),
            "Param2": (string)
         }
         "StatusPhraseModerate": (string),
         "AutoBudgetPriority": (string),
         "Clicks": (int),
         "Shows": (int),
         "Min": (float),
         "Max": (float),
         "PremiumMin": (float),
         "PremiumMax": (float),
         "LowCTRWarning": (string),
         "LowCTR": (string),
         "ContextLowCTR": (string),
         "Coverage": [
            {  /* CoverageInfo */
               "Probability": (float),
               "Price": (float)
            }
            ...
         ],
         "ContextCoverage": [
            {  /* CoverageInfo */
               "Probability": (float),
               "Price": (float)
            }
            ...
         ],
         "Prices": [
            (float)
            ...
         ],
         "CurrentOnSearch": (float),
         "MinPrice": (float),
      }
      ...
   ]
}

The parameters are described below.

^Parameter	^Description
_{BannerPhraseInfo object}
`CampaignID`	Campaign ID.
`BannerID`	Ad ID.
`PhraseID`	Keyword ID.
`Phrase`	Keyword. May contain negative words, which are specified with a minus sign before the word, for example [lightning -thunder -rain]. Negative words common to several keywords should preferably be specified in the ad group's `MinusKeywords` parameter. Keyword length — no more than 4096 characters. The "!" operator before a negative word is not counted in the keyword length (the sequence "-!" is counted as one character). No more than 7 words in a keyword, excluding stop words and negative words. Each word and negative word — no more than 35 characters, excluding the minus before the negative word.
`IsRubric`	Indicator that the keyword is a Yandex Catalog category. Always contains the value No.
`Price`	Bid on Yandex search Yandex units. Default limit — 50 Yandex units. Returned only if a manual bid management strategy is selected for the campaign.
`ContextPrice`	Bid in the Yandex Advertising Network Yandex units. The bid can be specified in the following cases: The IndependentControl strategy is used on search. This strategy can only be selected through the Direct web interface. Any manual strategy is used on search and the keyword is disabled for low CTR. For new keywords, this condition is not relevant, since keywords are no longer disabled for low CTR.
`AutoBroker`	Indicator of enabled auto-broker. Always contains the value Yes.
`UserParams`	`PhraseUserParams` object. Contains values of substitution variables for forming the website link.
`StatusPhraseModerate`	Keyword check result: New — keyword not checked; Yes — accepted; No — rejected;
`AutoBudgetPriority`	Keyword priority when using automatic strategies. Possible values: Low — low priority; Medium — medium priority; High — high priority.
`Clicks`	Number of clicks on the ad shown in search for this keyword. Calculated for 28 days from the current date. Days during which there was at least one click on the ad are selected for calculation.
`Shows`	Number of ad impressions for this keyword in search. Calculated for 28 days from the current date. Days during which there was at least one ad impression for this keyword are selected for calculation.
`Min`	Minimum bid for entry into the guaranteed impressions block.
`Max`	Minimum bid for 1st position in the guaranteed impressions block.
`PremiumMin`	Minimum bid for entry into premium placement.
`PremiumMax`	Minimum bid for 1st position in premium placement.
`LowCTRWarning`	Keyword has low CTR and may be disabled soon — Yes/No. Alert This parameter is no longer relevant for new keywords, since keywords are no longer disabled for low CTR.
`LowCTR`	Keyword disabled in search for low CTR — Yes/No. Alert This parameter is no longer relevant for new keywords, since keywords are no longer disabled for low CTR.
`ContextLowCTR`	Keyword disabled on Yandex Advertising Network sites for low CTR — Yes/No. Alert This parameter is no longer relevant for new keywords, since keywords are no longer disabled for low CTR.
`Coverage`	Array of `CoverageInfo` objects that indicate the predicted audience reach in search. Alert The parameter is no longer relevant and should not be used for bid selection.
`ContextCoverage`	Array of `CoverageInfo` objects that indicate the predicted audience reach in the Yandex Advertising Network. The parameter is useful for bid selection for keywords.
`Prices`	Array of bids for all positions in premium placement and in the guaranteed impressions block.
`CurrentOnSearch`	Final click price taking into account auto-broker. If the ad is not being shown in search for the keyword or the keyword is disabled in search for low CTR, the parameter returns the value NULL.
`MinPrice`	Minimum price, assigned individually for each advertiser.
_{CoverageInfo object}
`Probability`	Impression frequency at the bid from the `Price` parameter. In the `ContextCoverage` array, specified as a percentage from 0 to 100. Used for bid selection.
`Price`	Bid for which the `Probability` parameter contains the impression frequency.
_{PhraseUserParams object}
`Param1`	Value of the `{param1}` substitution variable. No more than 255 bytes.
`Param2`	Value of the `{param2}` substitution variable. No more than 255 bytes.
Notes
In rare cases, impression position prices and some other parameters related to auction results may have a NULL value, which indicates an error retrieving data on the API side. It is recommended to retry the method call after some time.

Input data examples

Python

{
   'BannerIDS': [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?

GetBannerPhrases (Live)

GetBannerPhrasesFilter (Live)