Request: report specification
The report parameters are specified in JSON or XML format in the request body.
Structure of parameters:
{
"params" : { /* ReportDefinition */
"SelectionCriteria": { /* SelectionCriteria */
"DateFrom": (string),
"DateTo": (string),
"Filter": [{ /* FilterItem*/
"Field": ( "AdGroupId" | ... | "Year" ), /* required */
"Operator": ( "EQUALS" | ... | "STARTS_WITH_IGNORE_CASE" ), /* required */
"Values": [(string), ... ] /* required */
}, ... ]
}, /* required */
"Goals": [(string), ... ],
"AttributionModels": [( "FC" | "LC" | "LSC" | "LYDC" ), ... ],
"FieldNames": [( "AdGroupId" | ... | "Year" ), ... ], /* required */
"Page": { /* Page*/
"Limit": (int) /* required */
"Offset": (int)
}
"OrderBy": [{ /* OrderBy*/
"Field": ( "AdGroupId" | ... | "Year" ), /* required */
"SortOrder": ( "ASCENDING" | "DESCENDING" )
}, ... ],
"ReportName": (string), /* required */
"ReportType": ( "ACCOUNT_PERFORMANCE_REPORT" | ... | "SEARCH_QUERY_PERFORMANCE_REPORT" ), /* required */
"DateRangeType": ( "ALL_TIME" | ... | "YESTERDAY" ), /* required */
"Format": ( "TSV" ), /* required */
"IncludeVAT": ( "YES" | "NO" ), /* required */
"IncludeDiscount": ( "YES" | "NO" )
}
}
The XML must conform to the XSD schema located at: https://api.direct.yandex.com/v5/reports.xsd.
<?xml version="1.0" encoding="UTF-8"?>
<ReportDefinition xmlns="http://api.direct.yandex.com/v5/reports">
<SelectionCriteria>
<DateFrom>(string)</DateFrom>
<DateTo>(string)</DateTo>
<Filter>
<Field>( AdGroupId | ... | Year )</Field>
<Operator>( EQUALS | ... | STARTS_WITH_IGNORE_CASE )</Operator>
<Values>(string)</Values>
...
<Values>(string)</Values>
</Filter>
...
<Filter> ... </Filter>
</SelectionCriteria>
<Goals>(string)</Goals>
...
<Goals>(string)</Goals>
<AttributionModels>( FC | LC | LSC | LYDC | FCCD | LSCCD | LYDCCD | AUTO )</AttributionModels>
...
<AttributionModels>( FC | LC | LSC | LYDC | FCCD | LSCCD | LYDCCD | AUTO )</AttributionModels>
<FieldNames>( AdGroupId | ... | Year )</FieldNames>
...
<FieldNames>( AdGroupId | ... | Year )</FieldNames>
<Page>
<Limit>(int)</Limit>
</Page>
<OrderBy>
<Field>( AdGroupId | ... | Year )</Field>
<SortOrder>( ASCENDING | DESCENDING )</SortOrder>
</OrderBy>
...
<OrderBy> ... </OrderBy>
<ReportName>(string)</ReportName>
<ReportType>( ACCOUNT_PERFORMANCE_REPORT | ... | SEARCH_QUERY_PERFORMANCE_REPORT )</ReportType>
<DateRangeType>( ALL_TIME | ... | YESTERDAY )</DateRangeType>
<Format>TSV</Format>
<IncludeVAT>( YES | NO )</IncludeVAT>
<IncludeDiscount>( YES | NO )</IncludeDiscount>
</ReportDefinition>
Parameter | Type | Description | Required |
ReportDefinition structure | |||
---|---|---|---|
SelectionCriteria | SelectionCriteria | Criteria for selecting data to show in the report. | Yes |
Goals | array of string | IDs of Yandex Metrica goals to get statistics for (see What are goals? Types of goals in Help for Yandex Metrica). Maximum of 10 items in the array. If this parameter is specified, instead of the ConversionRate, Conversions, CostPerConversion, GoalsRoi and Revenue fields with aggregated data for all goals, the report will show the same fields with names in the format and separate data for each goal. See also Example: Yandex Metrica data. | No |
AttributionModels | array of AttributionModelEnum | Attribution models used for calculating data on Yandex Metrica goals (see Attribution in Help for Yandex Direct). Possible values:
The default value is AUTO. If multiple attribution models are specified, data is output separately for each model. Attention. When using the LSC and FC attribution models, the session date is not the date the site was actually visited, but the date of the click that was the source of the session. This means that a session and its data (page depth, conversion, revenue, etc.) are reflected in the report if the date of the click falls within the report period. If you generate the report again for the same period with the same parameters, the Yandex.Metrica data in the report may change if there have been sessions since the last time the report was created that came from clicks made during the report period. | No |
FieldNames | array of FieldEnum | Names of fields (columns) that will be in the report. To see which fields you can specify, see the sections Allowed fields and Incompatible fields and dependencies. For the REACH_AND_FREQUENCY_PERFORMANCE_REPORT report type, the CampaignId field is required. | Yes |
Page | Page | Restriction on number of rows in the report. If omitted, the limit is 1,000,000. | No |
OrderBy | array of OrderBy | Names of fields (columns) to sort the report rows by. | No |
ReportName | string | Name of the report. Shown in the first row in the report. In offline mode, the report name must be unique for the advertiser. If a report with the same name but different parameters has already been generated or is in the queue, an error is returned. | Yes |
ReportType | ReportTypeEnum | Report type. See Report type. | Yes |
DateRangeType | DateRangeTypeEnum | The period that the report is generated for. See Report period. | Yes |
Format | FormatEnum | Report format. Currently, only the TSV value is supported. | Yes |
IncludeVAT | YesNoEnum | Whether to include VAT in the monetary amounts in the report. | Yes |
IncludeDiscount | YesNoEnum | Whether to include the discount for monetary amounts in the report. This parameter is deprecated because the discount is no longer available in Yandex Direct as of September 1, 2015. | No |
SelectionCriteria structure | |||
DateFrom | string | The start date of the report, YYYY-MM-DD. | When the DateRangeType parameter has the value CUSTOM_DATE |
DateTo | string | The end date of the report, YYYY-MM-DD. Note. The DateFrom and DateTo parameters are required when the DateRangeType parameter is set to CUSTOM_DATE. They are not allowed when other values are set. | |
Filter | array of FilterItem | Filters. See Filtering data. | No |
FilterItem structure | |||
Field | FieldEnum | The name of the field used for filtering data. Each field can only be used in one filter. Multiple filters with the same field are not allowed. To see which fields you can specify, see the sections Allowed fields and Incompatible fields and dependencies. | Yes |
Operator | FilterOperatorEnum | The operator to use for filtering data:
Note. The EQUALS, NOT_EQUALS, IN, and NOT_IN operators are not case-sensitive for the Keyword and Query fields. For the other fields, they are case-sensitive. The STARTS_WITH_IGNORE_CASE, DOES_NOT_START_WITH_IGNORE_CASE, STARTS_WITH_ANY_IGNORE_CASE, and DOES_NOT_START_WITH_ALL_IGNORE_CASE operators are not case-sensitive. | Yes |
Values | array of string | Values to use for filtering data. Maximum of 10,000 items in the array. All monetary values should be specified as integers: the amount in the currency, multiplied by 1,000,000 (regardless of the .returnMoneyInMicros: false header). | Yes |
Page structure | |||
Limit | int | The maximum number of rows in the report. | Yes |
Offset | int | Number of rows to skip when getting the selection. | No |
OrderBy structure | |||
Field | FieldEnum | The name of the field used for sorting rows. To see which fields you can specify, see the sections Allowed fields and Incompatible fields and dependencies. | Yes |
SortOrder | OrderBySortOrderEnum | The sorting direction:
If omitted, ascending order is used. | No |
Parameter | Type | Description | Required |
ReportDefinition structure | |||
---|---|---|---|
SelectionCriteria | SelectionCriteria | Criteria for selecting data to show in the report. | Yes |
Goals | array of string | IDs of Yandex Metrica goals to get statistics for (see What are goals? Types of goals in Help for Yandex Metrica). Maximum of 10 items in the array. If this parameter is specified, instead of the ConversionRate, Conversions, CostPerConversion, GoalsRoi and Revenue fields with aggregated data for all goals, the report will show the same fields with names in the format and separate data for each goal. See also Example: Yandex Metrica data. | No |
AttributionModels | array of AttributionModelEnum | Attribution models used for calculating data on Yandex Metrica goals (see Attribution in Help for Yandex Direct). Possible values:
The default value is AUTO. If multiple attribution models are specified, data is output separately for each model. Attention. When using the LSC and FC attribution models, the session date is not the date the site was actually visited, but the date of the click that was the source of the session. This means that a session and its data (page depth, conversion, revenue, etc.) are reflected in the report if the date of the click falls within the report period. If you generate the report again for the same period with the same parameters, the Yandex.Metrica data in the report may change if there have been sessions since the last time the report was created that came from clicks made during the report period. | No |
FieldNames | array of FieldEnum | Names of fields (columns) that will be in the report. To see which fields you can specify, see the sections Allowed fields and Incompatible fields and dependencies. For the REACH_AND_FREQUENCY_PERFORMANCE_REPORT report type, the CampaignId field is required. | Yes |
Page | Page | Restriction on number of rows in the report. If omitted, the limit is 1,000,000. | No |
OrderBy | array of OrderBy | Names of fields (columns) to sort the report rows by. | No |
ReportName | string | Name of the report. Shown in the first row in the report. In offline mode, the report name must be unique for the advertiser. If a report with the same name but different parameters has already been generated or is in the queue, an error is returned. | Yes |
ReportType | ReportTypeEnum | Report type. See Report type. | Yes |
DateRangeType | DateRangeTypeEnum | The period that the report is generated for. See Report period. | Yes |
Format | FormatEnum | Report format. Currently, only the TSV value is supported. | Yes |
IncludeVAT | YesNoEnum | Whether to include VAT in the monetary amounts in the report. | Yes |
IncludeDiscount | YesNoEnum | Whether to include the discount for monetary amounts in the report. This parameter is deprecated because the discount is no longer available in Yandex Direct as of September 1, 2015. | No |
SelectionCriteria structure | |||
DateFrom | string | The start date of the report, YYYY-MM-DD. | When the DateRangeType parameter has the value CUSTOM_DATE |
DateTo | string | The end date of the report, YYYY-MM-DD. Note. The DateFrom and DateTo parameters are required when the DateRangeType parameter is set to CUSTOM_DATE. They are not allowed when other values are set. | |
Filter | array of FilterItem | Filters. See Filtering data. | No |
FilterItem structure | |||
Field | FieldEnum | The name of the field used for filtering data. Each field can only be used in one filter. Multiple filters with the same field are not allowed. To see which fields you can specify, see the sections Allowed fields and Incompatible fields and dependencies. | Yes |
Operator | FilterOperatorEnum | The operator to use for filtering data:
Note. The EQUALS, NOT_EQUALS, IN, and NOT_IN operators are not case-sensitive for the Keyword and Query fields. For the other fields, they are case-sensitive. The STARTS_WITH_IGNORE_CASE, DOES_NOT_START_WITH_IGNORE_CASE, STARTS_WITH_ANY_IGNORE_CASE, and DOES_NOT_START_WITH_ALL_IGNORE_CASE operators are not case-sensitive. | Yes |
Values | array of string | Values to use for filtering data. Maximum of 10,000 items in the array. All monetary values should be specified as integers: the amount in the currency, multiplied by 1,000,000 (regardless of the .returnMoneyInMicros: false header). | Yes |
Page structure | |||
Limit | int | The maximum number of rows in the report. | Yes |
Offset | int | Number of rows to skip when getting the selection. | No |
OrderBy structure | |||
Field | FieldEnum | The name of the field used for sorting rows. To see which fields you can specify, see the sections Allowed fields and Incompatible fields and dependencies. | Yes |
SortOrder | OrderBySortOrderEnum | The sorting direction:
If omitted, ascending order is used. | No |