GetBannersStat (Live)

Returns statistics for the specified campaign for a period no longer than seven days.

Attention.

This method is outdated and will soon be disabled. 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, 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. 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 must be set up for the tag.
    • The code snippet must pass the order price.
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, 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.

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:
  • ID of the targeting condition 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, 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
  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)

  2. 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. For campaigns that operate in a currency, the discount is applied when the cost per click is deducted.
  3. If the campaign was run in Yandex units, the amounts are returned “as is”, without any other conversions.

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']
}