GetBannerPhrasesFilter (Live)

Returns information about keywords and lets you limit what is included in returned data.

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.

New in the Live 4 version

Added the StatusPaused output parameter.

Added the ContextClicks and ContextShows output parameters.

Added the Currency input parameter and the Currency output parameter (also see the section Real currencies instead of Yandex units).

Added the AdGroupID output parameter.

Added the AuctionBids output parameter.

Restrictions

You can't get keywords from archived campaigns.

Attention. The method only supports text and image ads. To work with all types of ad keywords, use the Keywords service in version 5 of the API.

Input data

The input data structure in JSON is shown below.

{
   "method": "GetBannerPhrasesFilter",
   "param": {
      /* BannerPhrasesFilterRequestInfo */
      "BannerIDS": [
         (long)
         ...
      ],
      "FieldsNames": [
         (string)
         ...
      ],
      "ConsiderTimeTarget": (string),
      "RequestPrices": (string),
      "Currency": (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.

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 their names 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
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
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.

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 their names 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
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

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),
         "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)
            }
            ...
         ]
      }
      ...
   ]
}

Parameters are described below.

Parameter Description
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.

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
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.

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': [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'
}