GetBannerPhrases (Live)

Returns information about keywords.

What's new in Live version 4

Added output parameter StatusPaused.

Added output parameters ContextClicks and ContextShows.

Added output parameter AdGroupID.

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": "GetBannerPhrases",
   "param": [
      (long)
      ...
   ]
}

The param parameter contains an array of ad IDs BannerID (up to 1000).

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.

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

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 (Yandex units)1. Specified only if a manual bid management strategy is selected for the campaign.
`ContextPrice`	Bid in the Yandex Advertising Network (YAN) (Yandex units)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 (Yandex units)2 that ensures most ads in the group are shown in the lower block.
`Max`	Price (Yandex units)2 that ensures most ads in the group are shown in the first position in the lower block.
`PremiumMin`	Price (Yandex units)2 that ensures most ads in the group are shown in Premium placement.
`PremiumMax`	Price (Yandex units)2 that ensures most ads in the group are shown in the first position in Premium placement.
`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 bids for all positions in Premium placement and in the lower block (Yandex units).
`CurrentOnSearch`	The final cost per click after autobroker is applied. 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 (Yandex units)2 set individually for each advertiser.
`StatusPaused`	Impressions for the keyword are paused — Yes/No. Impressions can be paused and resumed using the Keyword (Live) method.
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 (Yandex units)2 for which the `Probability` parameter contains the impression frequency.
PhraseUserParams object
`Param1`	Value of the `{param1}` substitution variable. Up to 255 bytes.
`Param2`	Value of the `{param2}` substitution variable. Up to 255 bytes.
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.

Was the article helpful?

GetBannerPhrases

GetBannerPhrasesFilter