Введение

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

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

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

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

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

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

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

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

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

Операционная система Глубина просмотра
Windows 4,2
IOS 3,1
Linux 1,6
Операционная система Глубина просмотра
Windows 4,2
IOS 3,1
Linux 1,6

Где

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

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

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

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

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

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

https://api-metrika.yandex.net/stat/v1/data.csv?id=44147844&metrics=ym:s:avgPageViews&dimensions=ym:s:operatingSystem&limit=5

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

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.

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

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

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

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

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

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

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

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

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