GetBannersStat (Live)

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

Attention.

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.


_{NewReportInfo object}
^Parameter	^Description	^Required
`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


_{NewReportInfo object}
^Parameter	^Description	^Required
`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.


_{GetBannersStatResponse object}
^Parameter	^Description
`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
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) 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. If the campaign was run in Yandex units, the amounts are returned “as is”, without any other conversions.


_{GetBannersStatResponse object}
^Parameter	^Description
`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
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) 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. 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']
}

Was the article useful?

Please tell us what you didn't like about this article:

GetBalance (Live) (disabled)

GetSummaryStat (disabled)

GetBalance (Live) (disabled)

GetSummaryStat (disabled)