GetBannerPhrasesFilter
Returns information about keywords and lets you limit what is included in returned data.
Disabled method. Use version 5 of the API.
For information about the compatibility of methods between versions 4 and 5, see the Migration guide.
The GetBannerPhrasesFilter (Live) version also exists for this method.
Restrictions
You can't get keywords from archived campaigns.
Input data
The input data structure in JSON is shown below.
{
"method": "GetBannerPhrasesFilter",
"param": {
/* BannerPhrasesFilterRequestInfo */
"BannerIDS": [
(long)
...
],
"FieldsNames": [
(string)
...
],
"ConsiderTimeTarget": (string),
"RequestPrices": (string)
}
}
Parameters are described below.
Parameter | Description | Required |
BannerPhrasesFilterRequestInfo object | ||
---|---|---|
BannerIDS | Array of ad IDs (no more than 1000). | Yes |
FieldsNames | An array containing the names of parameters to return in the response. If omitted, returns all available parameters. The CampaignID, BannerID and PhraseID parameters are always returned. The AutoBroker, StatusPhraseModerate, IsRubric, Price and Phrase parameters can also be returned. You can specify their names in the FieldsNames array. To return all parameters, the array is omitted. | No |
RequestPrices | Return statistics and prices — Yes/No. 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, and MinPrice. You can specify the names of these parameters in the FieldsNames array. | No |
ConsiderTimeTarget | When calculating the price for the display position, ignore bids in competitors' ads that are currently stopped by their schedule — Yes/No. The predefined value is No (all ads are factored into the calculation). | No |
Parameter | Description | Required |
BannerPhrasesFilterRequestInfo object | ||
---|---|---|
BannerIDS | Array of ad IDs (no more than 1000). | Yes |
FieldsNames | An array containing the names of parameters to return in the response. If omitted, returns all available parameters. The CampaignID, BannerID and PhraseID parameters are always returned. The AutoBroker, StatusPhraseModerate, IsRubric, Price and Phrase parameters can also be returned. You can specify their names in the FieldsNames array. To return all parameters, the array is omitted. | No |
RequestPrices | Return statistics and prices — Yes/No. 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, and MinPrice. You can specify the names of these parameters in the FieldsNames array. | No |
ConsiderTimeTarget | When calculating the price for the display position, ignore bids in competitors' ads that are currently stopped by their schedule — Yes/No. The predefined value is No (all ads are factored into the calculation). | No |
Output data
The method returns an array of BannerPhraseInfo objects with information about keywords. The output data structure in JSON 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),
}
...
]
}
Parameters are described below.
Parameter | Description |
BannerPhraseInfo object | |
---|---|
CampaignID | The campaign ID. |
BannerID | The ad ID. |
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 | The bid on Yandex search (in Yandex units). The predefined limit is 50 Yandex units. Required only if a strategy with manual bid management is selected for the campaign. |
ContextPrice | Bid in the Yandex Advertising Network (in Yandex units). The bid can be set 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 an ad that was 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 ad impressions for this keyword on the search. Calculated for the last 28 days. The calculation uses those days during which there was at least one ad impression for this keyword. |
Min | The minimum bid to get into Guaranteed Placement. |
Max | The minimum bid for the 1st position in Guaranteed Placement. |
PremiumMin | The minimum bid to get into Premium Placement. |
PremiumMax | The minimum bid for the 1st position in Premium Placement. |
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 bids for all positions in Premium Placement and Guaranteed Placement. |
CurrentOnSearch | The final CPC after applying Autobroker. 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 | Minimal price set individually for each advertiser. |
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 that the Probability parameter contains the frequency of impressions for. |
PhraseUserParams object | |
Param1 | Value of the |
Param2 | Value of the |
Notes | |
|
Parameter | Description |
BannerPhraseInfo object | |
---|---|
CampaignID | The campaign ID. |
BannerID | The ad ID. |
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 | The bid on Yandex search (in Yandex units). The predefined limit is 50 Yandex units. Required only if a strategy with manual bid management is selected for the campaign. |
ContextPrice | Bid in the Yandex Advertising Network (in Yandex units). The bid can be set 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 an ad that was 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 ad impressions for this keyword on the search. Calculated for the last 28 days. The calculation uses those days during which there was at least one ad impression for this keyword. |
Min | The minimum bid to get into Guaranteed Placement. |
Max | The minimum bid for the 1st position in Guaranteed Placement. |
PremiumMin | The minimum bid to get into Premium Placement. |
PremiumMax | The minimum bid for the 1st position in Premium Placement. |
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 bids for all positions in Premium Placement and Guaranteed Placement. |
CurrentOnSearch | The final CPC after applying Autobroker. 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 | Minimal price set individually for each advertiser. |
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 that the Probability parameter contains the frequency of impressions for. |
PhraseUserParams object | |
Param1 | Value of the |
Param2 | Value of the |
Notes | |
|
Examples of input data
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'
}