--- metadata: - name: generator content: Diplodoc Platform v5.66.1 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: https://yandex.com/dev/direct/doc/dg-v4/en/live/GetBannersStat.md type: text/markdown title: Markdown version - href: https://yandex.com/dev/direct/doc/dg-v4/en/llms.txt?revision=r22047995 rel: describedby --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.com/dev/direct/doc/dg-v4/en/llms.txt?revision=r22047995 # GetBannersStat (Live) Returns statistics for the specified campaign for a period no longer than seven days. ## 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 period, `YYYY-MM-DD`. The period must be seven days or less. | Yes || || `EndDate` | The end date of the report period, `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 ID, a retargeting ID, or a data source ID 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 serving: with image, with video, or text-only. - clDeviceType — the type of device the ad is served on. - clAveragePosition — the average ad serving position `ShowsAveragePosition` and the average position of clicks on the ad `ClicksAveragePosition`; - clROI — the revenue `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 AdditionalMetrikaCounters campaign parameter; - must be set up for the tag; - the tag code must pass the . {% endnote %} | No || || `Limit` | Total number of entries to select from the database into 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. Possible values: clDate, clPhrase, clBanner, clImage. | No || || `Currency` | The currency to use for amounts in the response. Possible 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#ErrorCode245). For campaigns in Yandex 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 with the discount applied (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 period, `YYYY-MM-DD`. || || `EndDate` | The end date of the report period, `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 date 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 . {% 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 interest, or the name of a targeting condition for dynamic ads, or the name of a filter, or the value “Automatically added keywords” (for ). 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](./#recalc) below. || || `SumContext` | The total cost of clicks in the Yandex Advertising Network (in the currency specified in the `Currency` input parameter). See [Notes](./#recalc) below. || || `Clicks` | Cumulative clicks on search and in the Yandex Advertising Network. || || `ClicksSearch` | Clicks on search. || || `ClicksContext` | Clicks in the Yandex Advertising Network. || || `Shows` | Cumulative impressions on search and in the Yandex Advertising Network. || || `ShowsSearch` | Impressions on search. || || `ShowsContext` | Impressions in the Yandex Advertising Network. || || `StatType` | Format of the ad serving. Possible values: Text (text-only), Image (with image), Video (with video). Output to the report if the `GroupByColumns` parameter has the “clImage” value. || || `DeviceType` | The type of device the ad is served on. Possible values: desktop/mobile/tablet. Output to the report if the `GroupByColumns` parameter has the value “clDeviceType”. || || `ShowsAveragePosition` | Average position where the ad is served. Calculated using only impressions 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): ![](../_assets/roi-formula.png) || || **Notes** {#recalc} || || 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'] } ```