---
metadata:
- name: generator
content: Diplodoc Platform v5.52.0
alternate:
- https://yandex.com/dev/direct/doc/dg-v4/en/live/GetBannersStat.md
- https://yandex.com/dev/direct/doc/dg-v4/ru/live/GetBannersStat.md
- href: en/live/GetBannersStat.md
type: text/markdown
title: Markdown version
- href: ../llms.txt
type: text/markdown
title: llms.txt
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.com/dev/direct/doc/dg-v4/en/llms.txt
# GetBannersStat (Live)
Returns statistics for the specified campaign for a period no longer than seven days.
{% note alert %}
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](https://yandex.com/dev/direct/doc/migration/concepts/methods.md).
{% endnote %}
## Restrictions {#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 {#input}
The input data structure in JSON is shown below.
```javascript
{
"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, `YYYY-MM-DD`. The period must be seven days or less.
|
Yes
||
||
`EndDate`
|
The end date of the report, `YYYY-MM-DD`. The period must be seven days or less.
|
Yes
||
||
`GroupByColumns`
|
Names of fields to output in the report in addition to the statistical data. Possible values:
- clDate — Date when statistics were collected, `statDate`.
- clPhrase — A keyword ID, a Yandex Catalog category, a retargeting, or a data source for generating dynamic ads.
- clBanner — ID of the ad. The clBanner value does not have to be specified, since it is automatically added to input data so that ad IDs are always output to the report. This value can be used in the `OrderBy` parameter for sorting lines in the report.
- clImage — Format of the ad display: image, video, or text.
- clDeviceType — The type of device the ad is shown on.
- clAveragePosition — The average ad display position `ShowsAveragePosition` and the average position of clicks on the ad `СlicksAveragePosition`.
- clROI — The income `Revenue` and return on investment `ROI`.
{% note info %}
In order to get the revenue and ROI values:
- A Yandex Metrica tag must be installed on the website.
- The tag must be linked to the advertising campaign in Yandex Direct (you must specify the tag ID in the AdditionalMetricaCounters campaign parameter).
- [Goals](https://yandex.ru/support/metrika/general/goals.html)[Goals](https://yandex.com/support/metrica/general/goals.html) must be set up for the tag.
- The code snippet must pass the [order price](https://yandex.ru/support/metrika/reports/e-commerce.html)[order price](https://yandex.com/support/metrica/reports/e-commerce.html).
{% endnote %}
|
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](https://yandex.com/dev/direct/doc/dg-v4/en/reference/ErrorCodes.md#BadCurrency).
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 info %}
For campaigns that operate in a currency, the discount is applied when the cost per click is deducted.
{% endnote %}
If the `Currency` parameter is omitted, the "No" value is assumed.
|
No
||
|#
## Output data {#output}
The output data structure in JSON is shown below.
```javascript
{
"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, `YYYY-MM-DD`.
||
||
`EndDate`
|
The end date of the report, `YYYY-MM-DD`.
||
||
`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](https://yandex.ru/support/direct/keywords/related-keywords.html)[additional relevant keywords](https://yandex.com/support/direct/keywords/related-keywords.html).
{% note info %}
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.
{% endnote %}
||
||
`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](https://yandex.com/dev/direct/doc/dg-v4/en/concepts/retargeting.md#ret-params).
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:
- ID of the [targeting condition](https://yandex.com/dev/direct/doc/dg/objects/dynamictextadtarget.md) for dynamic ads, if the data source is website pages.
- ID of the filter, if the data source is a feed with product offers. You can only manage filters in the web interface at this time.
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](https://yandex.com/dev/direct/doc/dg-v4/en/concepts/retargeting.md#ret-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](https://yandex.ru/support/direct/keywords/related-keywords.html)[additional relevant keywords](https://yandex.com/support/direct/keywords/related-keywords.html)).
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](#recalc) below.
||
||
`SumSearch`
|
The total cost of clicks on search (in the currency specified in the `Currency` input parameter).
See [Notes](https://yandex.com/dev/direct/doc/dg-v4/en/live/GetBannersStat.md#recalc) below.
||
||
`SumContext`
|
The total cost of clicks in the Yandex Advertising Network (in the currency specified in the `Currency` input parameter).
See [Notes](https://yandex.com/dev/direct/doc/dg-v4/en/live/GetBannersStat.md#recalc) 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](https://yandex.ru/support/direct-tooltips/average-position.html)[Average position](https://yandex.com/support/direct-tooltips/average-position.html) 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](https://yandex.ru/support/direct-tooltips/average-position.html)[Average position](https://yandex.com/support/direct-tooltips/average-position.html) 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**
||
||
1. The cost of clicks that is expressed in a currency may include or exclude VAT, depending on the value of the IncludeVAT input parameter.
_Cost of clicks with VAT_ = _Cost of clicks without VAT_ × (1 + _VAT rate_)
1. The cost of clicks that is expressed in a currency may or may not include the discount, depending on the value of the IncludeDiscount input parameter.
_Cost of clicks before applying the discount_ = _Cost of clicks actually deducted from the balance_ / (1 – _Discount_)
{% note info %}
For campaigns that operate in a currency, the discount is applied when the cost per click is deducted.
{% endnote %}
1. If the campaign was run in Yandex units, the amounts are returned “as is”, without any other conversions.
||
|#
## Examples of input data {#example}
## Python
```python
{
'CampaignID': 1234567,
'StartDate': '2013-02-15',
'EndDate': '2013-02-21',
'GroupByColumns': ['clDate', 'clPhrase'],
'Limit': 10,
'Offset': 0,
'OrderBy': ['clDate', 'clBanner']
}
```
## PHP
```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
```perl
{
'CampaignID' => 1234567,
'StartDate' => '2013-02-15',
'EndDate' => '2013-02-21',
'GroupByColumns' => ['clDate', 'clPhrase'],
'Limit' => 10,
'Offset' => 0,
'OrderBy' => ['clDate', 'clBanner']
}
```