Запрос: спецификация отчета

Параметры отчета указываются в теле запроса в формате JSON или XML.

Структура параметров:

{
  "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" | "FCCD" | "LSCCD" | "LYDCCD" | "AUTO" ), ... ],
      "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" ) 
  }
}

XML должен соответствовать XSD-схеме, размещенной по адресу 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>

Параметр

Тип

Описание

Обязательный

Структура ReportDefinition

SelectionCriteria

SelectionCriteria

Критерии отбора данных для отчета.

Да

Goals

array of string

Идентификаторы целей Яндекс Метрики, по которым требуется получить статистику (см. раздел Что такое цели. Типы целей помощи Яндекс Метрики). Не более 10 элементов в массиве.

Если параметр указан, то в отчете вместо полей ConversionRate, Conversions, CostPerConversion, GoalsRoi и Revenue с агрегированными данными по всем целям будут выведены аналогичные поля с именами вида <поле>_<id_цели>_<модель_атрибуции> и данными по каждой цели в отдельности.

См. также Пример: данные Яндекс Метрики.

Нет

AttributionModels

array of AttributionModelEnum

Модели атрибуции, используемые при расчете данных по целям Яндекс Метрики (см. раздел Модели атрибуции помощи Директа).
Возможные значения:

  • FC — первый переход.
  • LC — последний переход.
  • LSC — последний значимый переход.
  • LYDC — последний переход из Яндекс Директа.
  • FCCD – первый переход кросс-девайс.
  • LSCCD – последний значимый переход кросс-девайс.
  • LYDCCD – последний переход из Яндекс Директа кросс-девайс.
  • AUTO – автоматическая атрибуция.

Значение по умолчанию — AUTO.

Если указано несколько моделей атрибуции, данные будут выведены по каждой модели в отдельности.

Примечание

При использовании моделей атрибуции LYDC, LSC и FC датой визита считается не дата фактического посещения сайта, а дата клика, который является источником визита. Таким образом, визит и его данные (глубина просмотра, достижение цели, доход и т. д.) будут отражены в отчете, если дата клика попадает в период отчета.

При повторном получении отчета за тот же период с теми же параметрами данные Метрики в отчете могут измениться, если с момента предыдущего получения отчета произошли визиты, источником которых являются клики, совершенные в период отчета.

Нет

FieldNames

array of FieldEnum

Имена полей (столбцов), которые будут присутствовать в отчете.

Какие поля можно указывать, см. в разделах Допустимые поля, Несовместимые поля и зависимости.

Для типа отчета REACH_AND_FREQUENCY_PERFORMANCE_REPORT поле CampaignId обязательно.

Да

Page

Page

Ограничение на количество строк в отчете. Если не задано, используется ограничение 1 000 000.

Нет

OrderBy

array of OrderBy

Имена полей (столбцов), по которым требуется отсортировать строки в отчете.

Нет

ReportName

string

Название отчета. Выводится в первой строке отчета.

В режиме офлайн название отчета должно быть уникальным для рекламодателя. Если отчет с таким названием, но с отличающимися параметрами уже сформирован или находится в очереди, выдается ошибка.

Да

ReportType

ReportTypeEnum

Тип отчета. См. раздел Тип отчета выше.

Да

DateRangeType

DateRangeTypeEnum

Период, за который формируется отчет. См. раздел Период отчета выше.

Да

Format

FormatEnum

Формат отчета. В настоящее время поддерживается только значение TSV.

Да

IncludeVAT

YesNoEnum

Включать ли НДС в денежные суммы в отчете.

Да

IncludeDiscount

YesNoEnum

Учитывать ли скидку для денежных сумм в отчете.
Параметр утратил актуальность, с 1 сентября 2015 года скидка в Директе не предоставляется.

Нет

Структура SelectionCriteria

DateFrom

string

Начальная дата отчетного периода, YYYY-MM-DD.

При значении CUSTOM_DATE параметра DateRangeType

DateTo

string

Конечная дата отчетного периода, YYYY-MM-DD.

Примечание

Параметры DateFrom и DateTo обязательны при значении CUSTOM_DATE параметра DateRangeType и недопустимы при других значениях.

При значении CUSTOM_DATE параметра DateRangeType

Filter

array of FilterItem

Фильтры. См. раздел Фильтрация данных выше.

Нет

Структура FilterItem

Field

FieldEnum

Имя поля, которое используется для фильтрации данных. Каждое поле можно использовать только в одном фильтре: несколько фильтров с одним и тем же полем не допускается.

Какие поля можно указывать, см. в разделах Допустимые поля, Несовместимые поля и зависимости.

Да

Operator

FilterOperatorEnum

Оператор, используемый для фильтрации данных:

  • EQUALS — значение поля равно значению из Values;
  • NOT_EQUALS — значение поля не равно значению из Values;
  • IN — значение поля равно любому значению из Values;
  • NOT_IN — значение поля не равно ни одному значению из Values;
  • LESS_THAN — значение поля меньше значения из Values;
  • GREATER_THAN — значение поля больше значения из Values;
  • STARTS_WITH_IGNORE_CASE — значение поля начинается с значения из Values;
  • DOES_NOT_START_WITH_IGNORE_CASE — значение поля не начинается с значения из Values;
  • STARTS_WITH_ANY_IGNORE_CASE — значение поля начинается с любого из значений, указанных в Values;
  • DOES_NOT_START_WITH_ALL_IGNORE_CASE — значение поля не начинается ни с одного из значений, указанных в Values.

Примечание

Операторы EQUALS, NOT_EQUALS, IN, NOT_IN для полей Keyword и Query не учитывают регистр, для остальных полей — учитывают регистр.

Операторы STARTS_WITH_IGNORE_CASE, DOES_NOT_START_WITH_IGNORE_CASE, STARTS_WITH_ANY_IGNORE_CASE, DOES_NOT_START_WITH_ALL_IGNORE_CASE не учитывают регистр.

Да

Values

array of string

Значения, используемые для фильтрации данных. Не более 10 000 элементов в массиве.

Все денежные значения следует указывать в виде целых чисел: сумм в валюте, умноженных на 1 000 000 (независимо от наличия заголовка returnMoneyInMicros: false).

Да

Структура Page

Limit

int

Максимальное количество строк в отчете.

Да

Offset

int

Количество строк, которое должно быть пропущено при выборке.

Нет

Структура OrderBy

Field

FieldEnum

Имя поля, которое используется для сортировки.

Какие поля можно указывать, см. в разделах Допустимые поля, Несовместимые поля и зависимости.

Да

SortOrder

OrderBySortOrderEnum

Направление сортировки:

  • ASCENDING — по возрастанию;
  • DESCENDING — по убыванию.

Если не задано, выполняется сортировка по возрастанию.

Нет
Предыдущая
HTTP-заголовки
Следующая
Допустимые поля