GetBannersStat (Live)
Returns statistics for the specified campaign for a period no longer than seven days.
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.
Restrictions
Up to 300 method calls per day for a single campaign.
Statistics are available for the three years prior to the current month. For example: on September 15, 2016, you can get data starting from September 1, 2013.
Data on an ad's average position is available starting from November 1, 2014.
Data on the device type is available starting from November 1, 2014.
New in the Live 4 version
The Currency input parameter is required for campaigns that use a real currency.
Added the RetargetingID output parameter.
Added the StatType output parameter.
Added the input parameters Currency, IncludeVAT, and IncludeDiscount.
Added the DeviceType output parameter. Added the clDeviceType value for the GroupByColumns input parameter.
Added the ShowsAveragePosition and ClicksAveragePosition output parameters. For the GroupByColumns input parameter, the clAveragePosition value was added.
Added the Revenue and ROI output parameters. Added the clROI value for the GroupByColumns input parameter.
Added the WebpageID output parameter.
Added the Video value for the StatType output parameter.
Input data
The input data structure in JSON is shown below.
{
"method": "GetBannersStat",
"param": {
/* NewReportInfo */
"CampaignID": (int),
"StartDate": (date),
"EndDate": (date),
"GroupByColumns": [
(string)
...
],
"Limit": (int),
"Offset": (int),
"OrderBy": [
(string)
...
],
"Currency": (string),
"IncludeVAT": (string),
"IncludeDiscount": (string)
}
}
Parameters are described below.
Parameter | Description | Required |
NewReportInfo object | ||
---|---|---|
CampaignID | ID of the campaign that the report is being generated for. | Yes |
StartDate | The start date of the report, | Yes |
EndDate | The end date of the report, | Yes |
GroupByColumns | Names of fields to output in the report in addition to the statistical data. Possible values:
| No |
Limit | Total number of items from the database to display in the report. If omitted, all entries are displayed. The Limit and Offset parameters are used for selecting entries by page. | No |
Offset | Number of the entry to start the selection from. If omitted, 0 is assumed. The Limit and Offset parameters are used for selecting entries by page. | If the parameter is set Limit |
OrderBy | Names of fields to sort report entries by. Acceptable values: clDate, clPhrase, clBanner and clImage. | No |
Currency | The currency to use for amounts in the response. Acceptable values: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN. The value must match the campaign currency; otherwise, an error is returned with code 245. For campaigns in units, either omit the parameter or pass NULL. | For campaigns in a real currency |
IncludeVAT | Calculate VAT for the cost of clicks in a currency — Yes/No. When the value is Yes, amounts shown in the response will include VAT. If omitted, Yes is assumed. If the Currency parameter is omitted, the IncludeVAT parameter is ignored. | No |
IncludeDiscount | Calculate the discount for the cost of clicks in a currency — Yes/No. When the value is Yes, the report will show amounts that include the discount (in other words, the amounts that are actually deducted from the campaign balance). When the value is No, the report will show amounts before the discount is applied. If omitted, Yes is assumed. Note. For campaigns that operate in a currency, the discount is applied when the cost per click is deducted. If the Currency parameter is omitted, the "No" value is assumed. | No |
Parameter | Description | Required |
NewReportInfo object | ||
---|---|---|
CampaignID | ID of the campaign that the report is being generated for. | Yes |
StartDate | The start date of the report, | Yes |
EndDate | The end date of the report, | Yes |
GroupByColumns | Names of fields to output in the report in addition to the statistical data. Possible values:
| No |
Limit | Total number of items from the database to display in the report. If omitted, all entries are displayed. The Limit and Offset parameters are used for selecting entries by page. | No |
Offset | Number of the entry to start the selection from. If omitted, 0 is assumed. The Limit and Offset parameters are used for selecting entries by page. | If the parameter is set Limit |
OrderBy | Names of fields to sort report entries by. Acceptable values: clDate, clPhrase, clBanner and clImage. | No |
Currency | The currency to use for amounts in the response. Acceptable values: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN. The value must match the campaign currency; otherwise, an error is returned with code 245. For campaigns in units, either omit the parameter or pass NULL. | For campaigns in a real currency |
IncludeVAT | Calculate VAT for the cost of clicks in a currency — Yes/No. When the value is Yes, amounts shown in the response will include VAT. If omitted, Yes is assumed. If the Currency parameter is omitted, the IncludeVAT parameter is ignored. | No |
IncludeDiscount | Calculate the discount for the cost of clicks in a currency — Yes/No. When the value is Yes, the report will show amounts that include the discount (in other words, the amounts that are actually deducted from the campaign balance). When the value is No, the report will show amounts before the discount is applied. If omitted, Yes is assumed. Note. For campaigns that operate in a currency, the discount is applied when the cost per click is deducted. If the Currency parameter is omitted, the "No" value is assumed. | No |
Output data
The output data structure in JSON is shown below.
{
"data": {
/* GetBannersStatResponse */
"CampaignID": (int),
"StartDate": (date),
"EndDate": (date),
"Stat": [
{ /* BannersStatItem */
"StatDate": (date),
"BannerID": (long),
"PhraseID": (long),
"RubricID": (int),
"RetargetingID": (int),
"WebpageID": (int),
"Phrase": (string),
"Sum": (float),
"SumSearch": (float),
"SumContext": (float),
"Clicks": (int),
"ClicksSearch": (int),
"ClicksContext": (int),
"Shows": (int),
"ShowsSearch": (int),
"ShowsContext": (int),
"StatType": (string),
"DeviceType": (string),
"ShowsAveragePosition": (float),
"ClicksAveragePosition": (float),
"Revenue": (float),
"ROI": (float)
}
...
]
}
}
Parameters are described below.
Parameter | Description |
GetBannersStatResponse object | |
---|---|
CampaignID | The campaign ID. |
StartDate | The start date of the report, |
EndDate | The end date of the report, |
Stat | Array of BannersStatItem objects. Each object contains statistics for a single keyword for a single date in the report period. |
BannersStatItem object | |
StatDate | The data statistics are provided for. Output to the report if the GroupByColumns parameter has the value “clDate”. |
BannerID | The ad ID. |
PhraseID | ID of the keyword or autotargeting. Output in the report if the GroupByColumns parameter has the “clPhrase” value and the entry also contains information about the keyword or Yandex Catalog category (but not about retargeting). NULL — For additional relevant keywords. Note. We recommend grouping by PhraseID on the application side, because in some cases the method response may contain multiple objects with the same PhraseID in the Stat array. |
RubricID | ID of a category in Yandex Catalog. Output to the report if the GroupByColumns parameter has the value “clPhrase” and the entry contains information about a Yandex Catalog category. |
RetargetingID | ID of the retargeting. Output to the report if the GroupByColumns parameter has the value “clPhrase” and the entry contains information about retargeting. |
WebpageID | ID of the data source for generating dynamic ads:
Output to the report if the GroupByColumns parameter is set to “clPhrase” and the entry contains information about the data source for generating dynamic ads. |
Phrase | The keyword text, or the name of a Yandex Catalog category, or the name of a retargeting condition, or the name of a mobile app category, or the name of a targeting condition for dynamic ads, or the name of a filter, or the value “Automatically added keywords” (for additional relevant keywords). Output to the report if the GroupByColumns parameter is set to “clPhrase”. |
Sum | The total cost of clicks both on search and in the Yandex Advertising Network (in the currency specified in the Currency input parameter). See Notes below. |
SumSearch | The total cost of clicks on search (in the currency specified in the Currency input parameter). See Notes below. |
SumContext | The total cost of clicks in the Yandex Advertising Network (in the currency specified in the Currency input parameter). See Notes below. |
Clicks | Cumulative clicks on the search and the Yandex Advertising Network. |
ClicksSearch | Clicks on the search. |
ClicksContext | Clicks in the Yandex Advertising Network. |
Shows | Cumulative impressions on the search and the Yandex Advertising Network. |
ShowsSearch | Impressions on the search. |
ShowsContext | Impressions in the Yandex Advertising Network. |
StatType | Format of the ad impression. Possible values: Text, Image, Video. Output to the report if the GroupByColumns parameter has the “clImage” value. |
DeviceType | The type of device the ad is shown on. Acceptable values: desktop/mobile/tablet. Output to the report if the GroupByColumns parameter has the value “clDeviceType”. |
ShowsAveragePosition | Average position where the ad is displayed. Calculated using only displays on the first page of Yandex search results. The top position is assigned the number 1. Output to the report if the GroupByColumns parameter is set to “clAveragePosition”. |
ClicksAveragePosition | Average position where the ad was clicked. Calculated using only clicks on the first page of Yandex search results. Output to the report if the GroupByColumns parameter is set to “clAveragePosition”. |
Revenue | Revenue (up to two decimal places) — the total of the order prices transmitted by the Yandex Metrica tag. |
ROI | The return on investment in advertising (up to two decimal places): |
Notes | |
|
Parameter | Description |
GetBannersStatResponse object | |
---|---|
CampaignID | The campaign ID. |
StartDate | The start date of the report, |
EndDate | The end date of the report, |
Stat | Array of BannersStatItem objects. Each object contains statistics for a single keyword for a single date in the report period. |
BannersStatItem object | |
StatDate | The data statistics are provided for. Output to the report if the GroupByColumns parameter has the value “clDate”. |
BannerID | The ad ID. |
PhraseID | ID of the keyword or autotargeting. Output in the report if the GroupByColumns parameter has the “clPhrase” value and the entry also contains information about the keyword or Yandex Catalog category (but not about retargeting). NULL — For additional relevant keywords. Note. We recommend grouping by PhraseID on the application side, because in some cases the method response may contain multiple objects with the same PhraseID in the Stat array. |
RubricID | ID of a category in Yandex Catalog. Output to the report if the GroupByColumns parameter has the value “clPhrase” and the entry contains information about a Yandex Catalog category. |
RetargetingID | ID of the retargeting. Output to the report if the GroupByColumns parameter has the value “clPhrase” and the entry contains information about retargeting. |
WebpageID | ID of the data source for generating dynamic ads:
Output to the report if the GroupByColumns parameter is set to “clPhrase” and the entry contains information about the data source for generating dynamic ads. |
Phrase | The keyword text, or the name of a Yandex Catalog category, or the name of a retargeting condition, or the name of a mobile app category, or the name of a targeting condition for dynamic ads, or the name of a filter, or the value “Automatically added keywords” (for additional relevant keywords). Output to the report if the GroupByColumns parameter is set to “clPhrase”. |
Sum | The total cost of clicks both on search and in the Yandex Advertising Network (in the currency specified in the Currency input parameter). See Notes below. |
SumSearch | The total cost of clicks on search (in the currency specified in the Currency input parameter). See Notes below. |
SumContext | The total cost of clicks in the Yandex Advertising Network (in the currency specified in the Currency input parameter). See Notes below. |
Clicks | Cumulative clicks on the search and the Yandex Advertising Network. |
ClicksSearch | Clicks on the search. |
ClicksContext | Clicks in the Yandex Advertising Network. |
Shows | Cumulative impressions on the search and the Yandex Advertising Network. |
ShowsSearch | Impressions on the search. |
ShowsContext | Impressions in the Yandex Advertising Network. |
StatType | Format of the ad impression. Possible values: Text, Image, Video. Output to the report if the GroupByColumns parameter has the “clImage” value. |
DeviceType | The type of device the ad is shown on. Acceptable values: desktop/mobile/tablet. Output to the report if the GroupByColumns parameter has the value “clDeviceType”. |
ShowsAveragePosition | Average position where the ad is displayed. Calculated using only displays on the first page of Yandex search results. The top position is assigned the number 1. Output to the report if the GroupByColumns parameter is set to “clAveragePosition”. |
ClicksAveragePosition | Average position where the ad was clicked. Calculated using only clicks on the first page of Yandex search results. Output to the report if the GroupByColumns parameter is set to “clAveragePosition”. |
Revenue | Revenue (up to two decimal places) — the total of the order prices transmitted by the Yandex Metrica tag. |
ROI | The return on investment in advertising (up to two decimal places): |
Notes | |
|
Examples of input data
Python
{
'CampaignID': 1234567,
'StartDate': '2013-02-15',
'EndDate': '2013-02-21',
'GroupByColumns': ['clDate', 'clPhrase'],
'Limit': 10,
'Offset': 0,
'OrderBy': ['clDate', 'clBanner']
}
PHP
array(
'CampaignID' => 1234567,
'StartDate' => '2013-02-15',
'EndDate' => '2013-02-21',
'GroupByColumns' => array('clDate', 'clPhrase'),
'Limit' => 10,
'Offset' => 0,
'OrderBy' => array('clDate', 'clBanner')
)
Perl
{
'CampaignID' => 1234567,
'StartDate' => '2013-02-15',
'EndDate' => '2013-02-21',
'GroupByColumns' => ['clDate', 'clPhrase'],
'Limit' => 10,
'Offset' => 0,
'OrderBy' => ['clDate', 'clBanner']
}