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

Параметры отчета указываются в теле запроса в формате 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" ) 
  }
}
Параметр Тип Описание Обязательный
Структура 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 и недопустимы при других значениях.
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 — по убыванию.

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

Нет
Параметр Тип Описание Обязательный
Структура 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 и недопустимы при других значениях.
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 — по убыванию.

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

Нет