Документация
Справочник разработчика
API управления
Управление клиентами Директа
API отчетов v1
Группировки
Клики
Параметры посетителей

Введение

API отчетов позволяет получать информацию о статистике посещений сайта и другие данные, не используя интерфейс Яндекс.Метрики.

При формировании запроса к API используются группировки (dimensions) и метрики (metrics).

Группировка (dimension) — это атрибут визита или хита, по которому можно сгруппировать данные.

В запросах к API группировки задаются в параметре dimensions. Если необходимо указать несколько группировок, перечислите их через запятую.

Также возможен отчет без группировок, в этом случае будет рассчитан суммарный результат.

Метрика (metric) — числовая величина, которая рассчитывается на основе атрибута хита или визита.

В запросах к API метрики задаются в параметре metrics. Если необходимо указать несколько метрик, перечислите их через запятую.

Подробно о терминах

Предлагаем подробнее узнать о понятиях «группировка» и «метрика» на примере отчета Яндекс.Метрики по операционной системе:

Операционная системаГлубина просмотра
Windows4,2
IOS3,1
Linux1,6

Где

  • Операционная система — атрибут визита, по которому сгруппированы данные отчета (группировка).
  • Глубина просмотра — значение, рассчитанное на основе числовых атрибутов визитов (метрика), соответствующее указанному группировке.
Примечание. 

Если вы знакомы с языком SQL, группировки можно представить как колонки, по которым происходит объединение данных, а метрики — как результаты вычисления агрегатных функций.

Например, приведенный выше отчет можно представить, как запрос к гипотетической таблице визитов:

SELECT operatingSystem, avg(depth) from visits GROUP BY operatingSystem

Метрики и группировки, указанные в запросе к API позволяют формировать необходимую вам структуру отчета.

Например, чтобы получить отчет по глубине просмотра с группировкой данных по типу и версии операционной системы, используйте такой запрос:

https://api-metrika.yandex.ru/stat/v1/data.csv?id=2138128&metrics=ym:s:avgPageViews&dimensions=ym:s:operatingSystem&limit=5&oauth_token=05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037

Совместимость группировок и метрик

API поддерживает два типа группировок и метрик:

  • Визиты — имеют префикс ym:s:.
  • Хиты — имеют префикс ym:pv:.

В одном запросе нельзя использовать разные префиксы, а также указывать больше одного множества (см. раздел Множества и отношения).

Внимание! 

Вы можете указать префикс отличный от заданного в запросе и различные множества при использовании параметра filters для фильтрации полученных данных по группировкам.

Например, данный запрос формирует отчет по количеству визитов и уникальных посетителей, перешедших из поисковых систем на указанную в запросе страницу:

где

  • dimensions=ym:s:searchEngineName — группировка данных по параметру ym:s:searchEngine (типу поисковой системы);
  • metrics=ym:s:visits,ym:s:users — количество визитов и посетителей;
  • filters=ym:s:trafficSourceName=='Переходы из поисковых систем' AND ym:pv:URL=@'help' — сегментация данных по группировкам ym:s:trafficSourceName и ym:pv:URL.

Виды отчетов

Полученные данные могут быть представлены в следующих формах:

Все уровни отчета и метрики представлены в виде таблицы.

Чтобы отображать данные в виде таблицы, используйте метод /stat/v1/data.

Формирование одной ветви древовидного отчета.

Чтобы сформировать ветвь, используйте метод /stat/v1/data/drilldown.

Данные представлены с разбивкой по времени (например, по дням, неделям и месяцам). Форма удобна для построения графиков и отслеживания динамики.

Используйте метод /stat/v1/data/bytime.

Сравнение сегментов, указанных в одном запросе. Данные представлены в виде таблицы.

Используйте метод /stat/v1/data/comparison.

Сравнение сегментов, указанных в одном запросе. Данные представлены в древовидном отчете.

Используйте метод /stat/v1/data/comparison/drilldown.

Формат отчетов

API возвращает ответы в кодировке UTF-8. Ответы имеют формат JSON или CSV.

Формат указывается в запросе после пути URL:

GET https://api-metrika.yandex.ru/stat/v1/data.csv?<counter_id>&<metrics>&<dimensions>

Так как формат JSON является форматом, принятым по умолчанию, его можно не указывать:

GET https://api-metrika.yandex.ru/stat/v1/data?<counter_id>&<metrics>&<dimensions>

Раскрытие данных

Яндекс.Метрика заботится о конфиденциальности посетителей и сохраняет обезличенность собранной информации. Поэтому некоторые данные, например, социально-демографические (пол, возраст и др.) раскрываются с ограничениями. Они выдаются только в том случае, если количество посетителей в выборке больше 10.

Например, необходимо узнать долю мужчин от количества посетителей за день. На момент отправки запроса сайт посетили 5 человек (менее 10). При таком условии ответ будет содержать информацию об общем количестве посетителей за день, но данные о количестве мужчин будут недоступны.