CreateNewReport
Generates a campaign statistics report on the server.
Disabled method. Use version 5 of the API.
For information about the compatibility of methods between versions 4 and 5, see the Migration guide.
The CreateNewReport (Live) version also exists for this method.
Instead of reporting, it is preferable to receive statistics by using the methods GetSummaryStat and GetBannersStat, if they give you enough data.
The method returns the ID of the future report. With this ID, you can find out whether the report is ready and get a link for downloading the report file (using the GetReportList method). The average time for generating a report is one to two minutes.
Restrictions
For a single campaign, a maximum of 300 calls of the CreateNewReport method are allowed per day.
For a single user, no more than five reports are stored on the server. On an attempt to create a sixth report, an error message is returned with error code 31. Reports are stored on the server for five hours, then deleted automatically. Use the DeleteReport method to delete a report manually.
- Report period
-
The report period set by the StartDate and EndDate parameters must not be more than:
- 367 days, for reports with data grouped by ads (clBanner), by keywords (clPhrase), by impression type (clImage) and/or by days.
- 31 days, for reports with any other grouping.
If a longer report period is set, an error message is returned with code 5.
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.
- Goals and conversions
-
To get data about visitors' behavior on the site (goal_id, session_depth, goal_conversion, goal_cost, goal_conversions_num, revenue, and roi), a Yandex Metrica tag must be installed on the advertiser's site. The tag ID must be specified in the AdditionalMetrikaCounters campaign parameter.
For goal_id, goal_conversion, goal_cost, goal_conversions_num, revenue, and roi it is also required that the tag has goals set up. For revenue and roi, the code snippet must transmit the order price.
- Average position
-
Data on an ad's average position is available starting from November 1, 2014.
- Device type
-
Data on the device type is available starting from November 1, 2014.
- User's gender and age group
-
Data on the user's gender and age group is available starting from July 22, 2015.
- Type of operating system and type of connection
-
OS type data is available starting from September 15, 2015.
Connection type data is available starting from October 16, 2015.
- Bid adjustment
-
Data for a retargeting condition used for applying bid adjustments for website users is available starting from July 22, 2016.
Input data
The input data structure in JSON is shown below.
{
"method": "CreateNewReport",
"param": {
/* NewReportInfo */
"CampaignID": (int),
"StartDate": (date),
"EndDate": (date),
"GroupByColumns": [
(string)
...
],
"Limit": (int),
"Offset": (int),
"GroupByDate": (string),
"OrderBy": [
(string)
...
],
"TypeResultReport": (string),
"CompressReport": (int),
"Filter": {
/* NewReportFilterInfo */
"PageType": (string),
"PositionType": (string),
"Banner": [
(long)
...
],
"Geo": [
(int)
...
],
"Phrase": [
(string)
...
],
"PageName": [
(string)
...
],
"StatGoals": [
(int)
...
],
"WithImage": (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 indicators to output in the report in addition to the statistical data. Possible values:
| No |
GroupByDate | Calculate cumulative statistics by time period:
This parameter should be set if the GroupByColumns array has the clDate value; otherwise, the parameter is ignored. | No |
OrderBy | Names of indicators to sort report entries by. Acceptable values are listed in the description for the GroupByColumns parameter. | No |
Limit | Total number of items from the database to display in the report (more than zero). The Limit and Offset parameters are used for selecting entries by page. | No |
Offset | Entry number to start the selection from (numbering starts from zero). The Limit and Offset parameters are used for selecting entries by page. | If the Limit parameter is set |
TypeResultReport | Report format. Currently, only the “xml” value is used. | No |
CompressReport | Method for compressing the report:
| No |
Filter | A NewReportFilterInfo object with parameters for filtering entries for the report. If omitted, entries will not be filtered. | No |
NewReporFiltertInfo object | ||
PageType | Filter entries by the type of site where ads are displayed:
| No |
PositionType | Filter entries based on the display block:
| No |
Banner | Array of ad IDs. Selects entries about the display of the specified ads. | No |
Geo | Array of region IDs. Selects entries about ad displays in the specified regions. | No |
Phrase | Array of strings. Selects entries about ad displays for the keywords that contain any of the specified strings as substrings (not case-sensitive). Note.
| No |
PageName | Array of site names. Selects entries about ad displays on the specified sites. The Yandex search site has the name “Yandex”. For other sites, the domains are specified that are registered in Yandex Direct, such as “mail.ru” and “nigma.ru”. | No |
StatGoals | ID of the Yandex Metrica goal (specified as an array item). More than one ID is not allowed. If omitted, the Yandex Metrica indicators in the report contain aggregated data for all goals. Use the GetStatGoals (Live) method to obtain a list of goals. | No |
WithImage | Select entries about ad displays either with or without images. Possible values: yes – with images; no – text; both – all (text, image, and video). | No |
DeviceType | Select entries about ad displays on a specific type of device. Acceptable values: desktop/mobile/tablet. | No |
Age | Select entries about ad displays to users in the specified age groups. The array can have the following values: AGE_0_17, AGE_18_24, AGE_25_34, AGE_35_44, AGE_45, AGE_UNKNOWN. | No |
Gender | Select entries about ad displays to users of the specified gender. The array can have the following values: GENDER_MALE, GENDER_FEMALE, GENDER_UNKNOWN. | No |
MobilePlatform | Select entries about ad displays on devices with the specified type of OS. The array can have the following values: ANDROID, IOS, OS_TYPE_UNKNOWN. Filtration by the OS type is available only for campaigns with the type “Ads for mobile apps”. | No |
CarrierType | Select entires about ad displays on the specified type of connection. The array can have the following values: CELLULAR (mobile), STATIONARY (wi-fi), CARRIER_TYPE_UNKNOWN. Filtration by the connection type is available only for campaigns with the type “Ads for mobile apps”. | 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 indicators to output in the report in addition to the statistical data. Possible values:
| No |
GroupByDate | Calculate cumulative statistics by time period:
This parameter should be set if the GroupByColumns array has the clDate value; otherwise, the parameter is ignored. | No |
OrderBy | Names of indicators to sort report entries by. Acceptable values are listed in the description for the GroupByColumns parameter. | No |
Limit | Total number of items from the database to display in the report (more than zero). The Limit and Offset parameters are used for selecting entries by page. | No |
Offset | Entry number to start the selection from (numbering starts from zero). The Limit and Offset parameters are used for selecting entries by page. | If the Limit parameter is set |
TypeResultReport | Report format. Currently, only the “xml” value is used. | No |
CompressReport | Method for compressing the report:
| No |
Filter | A NewReportFilterInfo object with parameters for filtering entries for the report. If omitted, entries will not be filtered. | No |
NewReporFiltertInfo object | ||
PageType | Filter entries by the type of site where ads are displayed:
| No |
PositionType | Filter entries based on the display block:
| No |
Banner | Array of ad IDs. Selects entries about the display of the specified ads. | No |
Geo | Array of region IDs. Selects entries about ad displays in the specified regions. | No |
Phrase | Array of strings. Selects entries about ad displays for the keywords that contain any of the specified strings as substrings (not case-sensitive). Note.
| No |
PageName | Array of site names. Selects entries about ad displays on the specified sites. The Yandex search site has the name “Yandex”. For other sites, the domains are specified that are registered in Yandex Direct, such as “mail.ru” and “nigma.ru”. | No |
StatGoals | ID of the Yandex Metrica goal (specified as an array item). More than one ID is not allowed. If omitted, the Yandex Metrica indicators in the report contain aggregated data for all goals. Use the GetStatGoals (Live) method to obtain a list of goals. | No |
WithImage | Select entries about ad displays either with or without images. Possible values: yes – with images; no – text; both – all (text, image, and video). | No |
DeviceType | Select entries about ad displays on a specific type of device. Acceptable values: desktop/mobile/tablet. | No |
Age | Select entries about ad displays to users in the specified age groups. The array can have the following values: AGE_0_17, AGE_18_24, AGE_25_34, AGE_35_44, AGE_45, AGE_UNKNOWN. | No |
Gender | Select entries about ad displays to users of the specified gender. The array can have the following values: GENDER_MALE, GENDER_FEMALE, GENDER_UNKNOWN. | No |
MobilePlatform | Select entries about ad displays on devices with the specified type of OS. The array can have the following values: ANDROID, IOS, OS_TYPE_UNKNOWN. Filtration by the OS type is available only for campaigns with the type “Ads for mobile apps”. | No |
CarrierType | Select entires about ad displays on the specified type of connection. The array can have the following values: CELLULAR (mobile), STATIONARY (wi-fi), CARRIER_TYPE_UNKNOWN. Filtration by the connection type is available only for campaigns with the type “Ads for mobile apps”. | No |
Output data
The method returns the ID of the future report, as shown in the following example.
{
"data": 137456
}
Examples of input data
Python
{
'CampaignID': 1327944,
'StartDate': '2013-05-01',
'EndDate': '2013-05-31',
'GroupByColumns': [
'clBanner',
'clStatGoals',
'clGoalConversionsNum',
'clAveragePosition',
'clROI'
],
'Filter': {
'PageType': 'search',
'PositionType': 'other',
'Banner': [1974642, 20920155, 20155899, 64654],
'Geo': [213],
'Phrase': [u'refrigerator'],
'PageName': [u'Yandex','nigma.ru'],
'StatGoals': [18565]
},
'Limit': 5000,
'Offset': 30000,
'GroupByDate': 'week',
'OrderBy': ['clBanner'],
'TypeResultReport': 'xml',
'CompressReport': 1
}
PHP
array(
'CampaignID' => 1327944,
'StartDate' => '2013-05-01',
'EndDate' => '2013-05-31',
'GroupByColumns' => array(
'clBanner',
'clStatGoals',
'clGoalConversionsNum',
'clAveragePosition',
'clROI'
),
'Filter' => array(
'PageType' => 'search',
'PositionType' => 'other',
'Banner' => array(1974642, 20920155, 20155899, 64654),
'Geo' => array(213),
'Phrase' => array('refrigerator'),
'PageName' => array('Yandex','nigma.ru'),
'StatGoals' => array(18565)
),
'Limit' => 5000,
'Offset' => 30000,
'GroupByDate' => 'week',
'OrderBy' => array('clBanner'),
'TypeResultReport' => 'xml',
'CompressReport' => 1
)
Perl
{
'CampaignID' => 1327944,
'StartDate' => '2013-05-01',
'EndDate' => '2013-05-31',
'GroupByColumns' => [
'clBanner',
'clStatGoals',
'clGoalConversionsNum',
'clAveragePosition',
'clROI'
],
'Filter' => {
'PageType' => 'search',
'PositionType' => 'other',
'Banner' => [1974642, 20920155, 20155899, 64654],
'Geo' => [213],
'Phrase' => ['refrigerator'],
'PageName' => ['Yandex','nigma.ru'],
'StatGoals' => [18565]
},
'Limit' => 5000,
'Offset' => 30000,
'GroupByDate' => 'week',
'OrderBy' => ['clBanner'],
'TypeResultReport' => 'xml',
'CompressReport' => 1
}
Sample report
A sample report in XML format is shown below.
<?xml version="1.0" encoding="UTF-8" ?>
<report>
<reportID>1234</reportID>
<campaignID>1234567</campaignID>
<startDate>2013-05-01</startDate>
<endDate>2013-05-31</endDate>
<phrasesDict>
<phrase type="phrase" phraseID="2" value="морозильное оборудование" />
<phrase type="retargeting" DictID="912" value="ретаргетинг: незавершенный заказ" />
</phrasesDict>
<stat>
<row bannerID="123456"
phraseID{stat}="2"
statDate="2013-05-15"
sum_search="10"
sum_context="2"
shows_search="1000"
shows_context="123"
clicks_search="100"
clicks_context="23"
sum="12"
shows="1234"
clicks="123"
regionID="1"
placeName="Yandex"
placeType="search"
goal_id="18565"
goal_conversion="25.91"
goal_cost="1.54"
session_depth="9.35"
goal_conversions_num="28"
position_type="premium"
stat_type="Text"
shows_average_position="4.87"
clicks_average_position="4.95"/>
<row bannerID="123457"
DictID{stat}="912"
RetargetingID="3097"
statDate="2013-05-25"
sum_search="0"
sum_context="96.35"
shows_search="0"
shows_context="755"
clicks_search="0"
clicks_context="57"
sum="96.35"
shows="755"
clicks="57"
regionID="1"
placeName="catalog.tut.by"
placeType="context"
goal_id="18777"
goal_conversion="28.88"
session_depth="9.39"
position_type="other"
stat_type="Image"/>
</stat>
</report>
Descriptions of report elements are provided below.
Element/attribute | Description | Output condition |
report element | ||
---|---|---|
reportID | ID of the report. | |
campaignID | The campaign ID. | |
startDate | The start date of the report, YYYY-MM-DD . | |
endDate | The end date of the report, YYYY-MM-DD . | |
phrasesDict | Keyword dictionary. Contains information about objects in the report: keywords, Yandex Catalog categories, retargetings, and targeting conditions for dynamic text ads. | |
stat | Statistical data. | |
phrasesDict element | ||
phrase | Information about the keyword, category, or retargeting in the attributes type, phraseID, DictID, and value. | |
type | Contains the value “phrase” in entries about keywords, “rubric” in entries about Yandex Catalog categories, or “retargeting” in entries about retargetings. | |
phraseID | ID of the keyword in the report. The phraseID identifier exists only within the report and does not match the keyword ID in Yandex Direct. It is used for standardizing report data and links the phrase and row elements. | |
rubricID | ID of the category in the report. Exists only within the report and does not match the category ID in Yandex Direct. Used for standardizing report data; links the phrase and row elements. | |
DictID | ID of the retargeting in the report. Exists only within the report and does not match the retargeting ID in Yandex Direct. Used for standardizing report data; links the phrase and row elements. | |
value | Either the text of the keyword, the number of the Yandex Catalog category, or the retargeting description in the report. | |
stat element | ||
row | Keyword statistics for one day in the report period. | |
sum | Cost of clicks deducted from the balance of the campaign 1 . | |
shows | Number of impressions 1 . | |
clicks | Number of clicks 1 . | |
bannerID | The ad ID. | In the GroupByColumns parameter, the value of “clBanner” or “clImage” is specified. |
phraseID | The keyword ID in the report (see the phrasesDict element). The phraseID identifier exists only within the report and does not match the keyword ID in Yandex Direct. It is used for standardizing report data and links the phrase and row elements. | In the GroupByColumns parameter, the value “clPhrase” is specified and the entry contains information about the keyword (not about the Yandex Catalog category or retargeting). |
rubricID | ID of the Yandex Catalog category in the report (see the phrasesDict element). Exists only within the report and does not match the category ID in Yandex Direct. Used for standardizing report data; links the phrase and row elements. | In the GroupByColumns parameter, the value “clPhrase” is specified and the entry contains information about the keyword, not about the Yandex Catalog category. |
DictID | The retargeting ID in the report (see the phrasesDict element). Exists only within the report and does not match the retargeting ID in Yandex Direct. Used for standardizing report data; links the phrase and row elements. | In the GroupByColumns parameter, the “clPhrase” value is specified and the entry contains information about retargeting. |
RetargetingID | Retargeting ID in Yandex Direct. | In the GroupByColumns parameter, the “clPhrase” value is specified and the entry contains information about retargeting. |
statDate | The data statistics are provided for. If the GroupByDate input parameter has the value “week” or “month”, the first date of the week or month is specified. | In the GroupByColumns array, the value “clDate” is present. |
sum_search | Cost of clicks in the search. | The PageType input parameter is omitted or has the value “all”. |
sum_context | Cost of clicks in the Yandex Advertising Network. | |
shows_search | Number of impressions in the search. | |
shows_context | Number of impressions in the Yandex Advertising Network. | |
clicks_search | Number of clicks in the search. | |
clicks_context | Number of clicks in the Yandex Advertising Network. | |
regionID | ID of the display region. | In the GroupByColumns array, the “clGeo” value is present. |
placeName | Name of the site where the ad is being displayed. | In the GroupByColumns array, the value “clPage” is present. |
placeType | Type of display platform: “search” — the search platform (including Yandex search and search sites in the Yandex Advertising Network), or “context” — a site in the Yandex Advertising Network. | |
goal_id | The ID of the goal in Yandex Metrica, if it was passed in the StatGoals input parameter. 0 — If the ID was not passed. In this case, the other Yandex Metrica indicators contain aggregated data for all goals. | In the GroupByColumns array, the value “clStatGoals” is present. |
goal_conversion | The percentage of goal visits as part of the total number of visits. | |
goal_cost | The average cost of a goal visit: the relationship of revenue to the number of goal visits. | |
session_depth | Session depth for the site. | |
goal_conversions_num | Number of goal visits (conversions). | In the GroupByColumns array, the value “clGoalConversionsNum” is present. |
position_type | The ad display block: “premium” for Premium Placement, or “other” for other ad blocks. | In the GroupByColumns array, the value “clPositionType” is present. |
stat_type | Type of ad display: with or without an image. Possible values: Image/Text. | In the GroupByColumns array, the “clImage” value is present. |
shows_average_position | Average display position of the ad. Calculated using only displays on the first page of Yandex search results. The top position is assigned the number 1. | In the GroupByColumns array, the value “clAveragePosition” is present. |
clicks_average_position | Average position where the ad was clicked. Calculated using only clicks on the first page of Yandex search results. | |
Notes | ||
|
Element/attribute | Description | Output condition |
report element | ||
---|---|---|
reportID | ID of the report. | |
campaignID | The campaign ID. | |
startDate | The start date of the report, YYYY-MM-DD . | |
endDate | The end date of the report, YYYY-MM-DD . | |
phrasesDict | Keyword dictionary. Contains information about objects in the report: keywords, Yandex Catalog categories, retargetings, and targeting conditions for dynamic text ads. | |
stat | Statistical data. | |
phrasesDict element | ||
phrase | Information about the keyword, category, or retargeting in the attributes type, phraseID, DictID, and value. | |
type | Contains the value “phrase” in entries about keywords, “rubric” in entries about Yandex Catalog categories, or “retargeting” in entries about retargetings. | |
phraseID | ID of the keyword in the report. The phraseID identifier exists only within the report and does not match the keyword ID in Yandex Direct. It is used for standardizing report data and links the phrase and row elements. | |
rubricID | ID of the category in the report. Exists only within the report and does not match the category ID in Yandex Direct. Used for standardizing report data; links the phrase and row elements. | |
DictID | ID of the retargeting in the report. Exists only within the report and does not match the retargeting ID in Yandex Direct. Used for standardizing report data; links the phrase and row elements. | |
value | Either the text of the keyword, the number of the Yandex Catalog category, or the retargeting description in the report. | |
stat element | ||
row | Keyword statistics for one day in the report period. | |
sum | Cost of clicks deducted from the balance of the campaign 1 . | |
shows | Number of impressions 1 . | |
clicks | Number of clicks 1 . | |
bannerID | The ad ID. | In the GroupByColumns parameter, the value of “clBanner” or “clImage” is specified. |
phraseID | The keyword ID in the report (see the phrasesDict element). The phraseID identifier exists only within the report and does not match the keyword ID in Yandex Direct. It is used for standardizing report data and links the phrase and row elements. | In the GroupByColumns parameter, the value “clPhrase” is specified and the entry contains information about the keyword (not about the Yandex Catalog category or retargeting). |
rubricID | ID of the Yandex Catalog category in the report (see the phrasesDict element). Exists only within the report and does not match the category ID in Yandex Direct. Used for standardizing report data; links the phrase and row elements. | In the GroupByColumns parameter, the value “clPhrase” is specified and the entry contains information about the keyword, not about the Yandex Catalog category. |
DictID | The retargeting ID in the report (see the phrasesDict element). Exists only within the report and does not match the retargeting ID in Yandex Direct. Used for standardizing report data; links the phrase and row elements. | In the GroupByColumns parameter, the “clPhrase” value is specified and the entry contains information about retargeting. |
RetargetingID | Retargeting ID in Yandex Direct. | In the GroupByColumns parameter, the “clPhrase” value is specified and the entry contains information about retargeting. |
statDate | The data statistics are provided for. If the GroupByDate input parameter has the value “week” or “month”, the first date of the week or month is specified. | In the GroupByColumns array, the value “clDate” is present. |
sum_search | Cost of clicks in the search. | The PageType input parameter is omitted or has the value “all”. |
sum_context | Cost of clicks in the Yandex Advertising Network. | |
shows_search | Number of impressions in the search. | |
shows_context | Number of impressions in the Yandex Advertising Network. | |
clicks_search | Number of clicks in the search. | |
clicks_context | Number of clicks in the Yandex Advertising Network. | |
regionID | ID of the display region. | In the GroupByColumns array, the “clGeo” value is present. |
placeName | Name of the site where the ad is being displayed. | In the GroupByColumns array, the value “clPage” is present. |
placeType | Type of display platform: “search” — the search platform (including Yandex search and search sites in the Yandex Advertising Network), or “context” — a site in the Yandex Advertising Network. | |
goal_id | The ID of the goal in Yandex Metrica, if it was passed in the StatGoals input parameter. 0 — If the ID was not passed. In this case, the other Yandex Metrica indicators contain aggregated data for all goals. | In the GroupByColumns array, the value “clStatGoals” is present. |
goal_conversion | The percentage of goal visits as part of the total number of visits. | |
goal_cost | The average cost of a goal visit: the relationship of revenue to the number of goal visits. | |
session_depth | Session depth for the site. | |
goal_conversions_num | Number of goal visits (conversions). | In the GroupByColumns array, the value “clGoalConversionsNum” is present. |
position_type | The ad display block: “premium” for Premium Placement, or “other” for other ad blocks. | In the GroupByColumns array, the value “clPositionType” is present. |
stat_type | Type of ad display: with or without an image. Possible values: Image/Text. | In the GroupByColumns array, the “clImage” value is present. |
shows_average_position | Average display position of the ad. Calculated using only displays on the first page of Yandex search results. The top position is assigned the number 1. | In the GroupByColumns array, the value “clAveragePosition” is present. |
clicks_average_position | Average position where the ad was clicked. Calculated using only clicks on the first page of Yandex search results. | |
Notes | ||
|