API Яндекс Метрики: автоматизация отчётов и выгрузка данных

Каждый понедельник у меня был один и тот же ритуал: открыть Яндекс Метрику, выбрать нужные метрики, отфильтровать по источникам, выгрузить CSV, открыть в таблицах, привести в нужный формат, отправить клиенту. На каждый проект — двадцать-тридцать минут. Когда таких проектов больше десяти, понедельник превращается в день ручной аналитики вместо реальной работы с кампаниями. Именно тогда я вплотную занялся API Яндекс Метрики.

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

Масштаб экономии времени зависит от числа клиентов и сложности отчётов, но даже для одного проекта автоматизация окупается за первый месяц. Я подсчитывал на своих проектах: переход с ручных выгрузок на API-отчётность высвободил от трёх до шести часов в неделю — время, которое теперь тратится на реальный анализ данных и оптимизацию кампаний, а не на рутинное копирование цифр.

В статье разберу два основных API Яндекс Метрики — Reporting API для агрегированных отчётов и Logs API для детальных сырых данных, покажу, как получить токен доступа, и дам примеры практических запросов на Python. Статья написана с прицелом на маркетологов и аналитиков без глубокого программистского бэкграунда — если вы умеете запустить скрипт в терминале, этого достаточно для начала.

Ещё один момент, который важен до начала работы с API: убедитесь, что в Метрике правильно настроены цели. API возвращает ровно те данные о конверсиях, которые фиксируют цели в интерфейсе — если цели настроены неточно или не настроены вовсе, автоматические отчёты по конверсиям будут показывать неполную картину. Как настроить цели корректно — в статье как настроить цели в Яндекс Метрике.

Какие API есть в Яндекс Метрике

В Яндекс Метрике доступны несколько API, каждый из которых решает свою задачу. Два основных для автоматизации отчётности — Reporting API и Logs API.

Reporting API — агрегированные отчёты

Reporting API — это прямой аналог стандартных отчётов в интерфейсе Метрики, только в программном виде. Вы отправляете запрос с параметрами: номер счётчика, период дат, нужные метрики (визиты, конверсии, доход) и измерения (источник трафика, страница, регион) — и получаете уже агрегированные данные в формате JSON. Это именно те данные, которые вы видели бы в разделе «Отчёты» в интерфейсе Метрики.

Reporting API подходит для большинства задач автоматической отчётности: еженедельный отчёт по источникам трафика, ежедневный срез конверсий по кампаниям, динамика ключевых метрик за месяц. Главное ограничение — данные агрегированы: вы видите суммарные цифры по группам, но не отдельные визиты и сессии.

Logs API — сырые данные о каждом визите

Logs API отдаёт необработанные данные на уровне каждого визита или каждого события — полный лог с информацией об источнике, UTM-метках, устройстве, времени сессии, просмотренных страницах и достигнутых целях. Это значительно больший объём данных, чем агрегированный Reporting API, зато позволяет делать любые аналитические срезы, которые недоступны в стандартном интерфейсе.

Logs API используют для построения собственных дашбордов с кастомной логикой, загрузки данных в корпоративные хранилища, объединения данных Метрики с данными из CRM и других систем. Если Reporting API — это готовый отчёт из ресторана, то Logs API — это сырые продукты, из которых можно приготовить что угодно по своему рецепту.

Как получить токен доступа к API

Любой запрос к API Метрики требует авторизации через OAuth-токен. Получить его можно несколькими способами в зависимости от задачи.

Токен для своего проекта

Для автоматизации собственной аналитики проще всего получить токен напрямую через сервис Яндекс OAuth. Открываете oauth.yandex.ru, авторизуетесь под своим Яндекс-аккаунтом, в адресной строке добавляете параметры запроса на получение токена с нужными правами доступа к Метрике. Полученный токен — это строка из букв и цифр, которую вы будете передавать в заголовке каждого API-запроса.

Токен для клиентских счётчиков

Если вы работаете с Метрикой нескольких клиентов и хотите автоматизировать сбор данных по всем, нужно настроить OAuth-авторизацию с возможностью получения токена от имени разных пользователей. Это сложнее технически, но один раз настроенный процесс позволяет получать данные по любому счётчику, к которому у клиента есть доступ, без ручного входа в каждый аккаунт.

Примеры запросов к Reporting API

Базовый URL для запросов к Reporting API: https://api-metrika.yandex.net/stat/v1/data. К этому адресу добавляются параметры запроса через строку URL или тело POST-запроса.

Пример 1 — Визиты по источникам трафика за период

Этот запрос вернёт данные по визитам, уникальным пользователям и достижению целей в разбивке по источникам трафика, отсортированные по убыванию числа визитов. Поле metrics принимает список нужных метрик через запятую, dimensions — измерения, по которым происходит группировка.

Пример 2 — Конверсии по рекламным кампаниям через Директ

Если счётчик Метрики связан с кабинетом Яндекс Директа, можно получать данные о конверсиях прямо в разрезе кампаний, групп объявлений и ключевых слов — то же самое, что вы видите в Мастере отчётов Директа, только в программном виде. Для этого в параметре dimensions используются метки Директа:

Фильтр trafficSource=='ad' оставляет только рекламный трафик, размерности ym:ad:campaign, ym:ad:adGroup и ym:ad:phrase группируют данные по кампании, группе объявлений и ключевому слову соответственно. Подробнее о том, как анализировать эффективность рекламных кампаний через Метрику, я писал в статье Яндекс Метрика для анализа рекламы.

Logs API — как получить сырые данные

Работа с Logs API устроена иначе, чем с Reporting API, — это асинхронный процесс в три шага. Сначала вы создаёте запрос на выгрузку (POST-запрос с параметрами), получаете в ответ requestId. Потом периодически проверяете статус запроса, пока он не сменится с «processing» на «processed». И только после этого скачиваете готовые файлы с данными.

Что входит в Logs API

Logs API позволяет выгружать два типа данных: визиты (каждая пользовательская сессия — её источник, длительность, страницы, достигнутые цели) и просмотры страниц (каждый отдельный просмотр в рамках сессии). Поля, которые можно запросить, огромный список — более ста параметров, включая UTM-метки, идентификаторы устройства, браузер, разрешение экрана, ID клиента Метрики, и конечно же все поведенческие параметры визита.

Главное практическое применение Logs API в моей работе — соединение данных Метрики с данными из CRM. Я выгружаю из Logs API ID клиентов Метрики вместе с источниками трафика и UTM-метками, а из CRM — данные о реальных сделках, привязанных к тем же клиентам. После соединения двух источников получается полная картина: какой клик из какой рекламной кампании в итоге привёл к реальной сделке на конкретную сумму. Это и есть полноценная сквозная аналитика, о построении которой я писал в статье сквозная аналитика для интернет-магазина.

Важный технический момент по работе с Logs API — данные приходят в сжатых файлах (формат gz), и их нужно распаковывать перед обработкой. Каждая выгрузка разбивается на части, если данных много — скрипт должен обойти все части и объединить их в один файл для дальнейшей обработки. На первый взгляд это сложнее, чем Reporting API, но большинство сложностей решается один раз при написании первого скрипта, а потом тот же код используется для всех последующих выгрузок.

Отдельный практический совет по Logs API: начинайте с выгрузки небольшого периода — один-два дня — чтобы проверить, что данные выгружаются правильно и скрипт корректно обрабатывает ответ. Выгрузка за месяц на загруженном счётчике может занять часы и создать большой файл, который сложнее отлаживать, если что-то пошло не так.

Автоматическая выгрузка данных в таблицы

Самый распространённый сценарий использования API Метрики в практике маркетологов — автоматическая выгрузка данных в таблицы. Скрипт получает данные из API и записывает их в файл CSV или напрямую в Яндекс Таблицы через соответствующий API. Расписание запуска настраивается через cron на сервере или через облачные планировщики.

Пример экспорта в CSV

Этот простой скрипт выгружает данные по визитам и пользователям в разрезе источника трафика и UTM-кампании, записывает результат в CSV-файл. Параметр limit ограничивает количество строк в ответе — для больших счётчиков может потребоваться постраничная выгрузка через параметр offset.

Справочник основных метрик Reporting API, которые используются в аналитике рекламы:

Практические сценарии автоматизации

Разберу несколько конкретных задач, которые я решаю через API Метрики в реальной работе.

Еженедельный отчёт по источникам

Классическая задача для Reporting API. Скрипт запускается каждый понедельник, запрашивает данные за прошедшую неделю по источникам трафика и конверсиям, форматирует результат в читаемую таблицу и отправляет письмо на нужные адреса через smtp-библиотеку. На настройку уходит несколько часов, после чего отчёт формируется без какого-либо участия человека каждую неделю.

Мониторинг конверсий в реальном времени

Если важно оперативно замечать резкие падения конверсий — например, при сбое на посадочной странице или при остановке рекламной кампании — API Метрики позволяет настроить мониторинг с алертами. Скрипт запрашивает данные за последний час, сравнивает с историческим средним и отправляет уведомление в Telegram или на почту, если показатели отклоняются на заданный процент. Это особенно полезно для сайтов с высоким трафиком, где каждый час простоя или неработающей формы заявки обходится ощутимо.

Практический пример из работы: клиент запустил обновление сайта в пятницу вечером, форма обратной связи перестала работать, и это обнаружили только в понедельник утром — потеряли всё воскресенье. После настройки мониторинга через API подобный сбой выявляется в течение часа и уведомление приходит автоматически независимо от времени суток.

Автоматическое сравнение периодов

Популярный запрос от клиентов — «покажи, как изменились показатели по сравнению с прошлым месяцем». С API это делается легко: два отдельных запроса за разные периоды, объединение результатов, расчёт изменений в процентах. Результат — таблица с колонками «текущий период», «предыдущий период» и «изменение». Этот отчёт я сделал на три проекта за одно утро, а теперь он работает автоматически каждый первый день месяца. О том как настроить сами цели, чтобы API возвращал правильные данные о конверсиях — в статье как настроить цели в Яндекс Метрике.

Инструменты для работы с API без программирования

Написание Python-скриптов — не единственный способ использовать API Метрики. Для тех, кому программирование не близко, есть несколько более доступных вариантов.

Коннекторы для Яндекс Таблиц

Существуют готовые коннекторы, которые позволяют подключить API Метрики к Яндекс Таблицам или Google Sheets без написания кода — просто настраиваете параметры через интерфейс коннектора и данные автоматически подтягиваются в таблицу по расписанию. Это отличный вариант для маркетологов, которым нужны регулярные отчёты, но нет времени или желания разбираться с Python.

Ручные запросы через Postman

Инструмент Postman позволяет отправлять API-запросы в графическом интерфейсе без написания кода — просто указываете URL, метод, заголовки и параметры, нажимаете кнопку и получаете ответ в читаемом виде. Это удобно для разовой выгрузки нестандартных данных или для первоначального тестирования запросов перед автоматизацией. По сути Postman — это «ручной режим» работы с API, которым удобно пользоваться, когда нужен конкретный срез данных раз в квартал, а не автоматический ежедневный отчёт.

Где найти полный справочник метрик и измерений

Официальная документация API Метрики содержит полный список всех доступных метрик и измерений с описаниями. Ключевая страница для работы с Reporting API — «Справочник показателей» в документации Яндекс Метрики, где можно найти точные названия нужных полей в формате ym:s:имя_поля. Я рекомендую держать эту страницу в закладках и сверяться с ней перед написанием любого нового запроса — неверное название метрики вернёт ошибку, а правильное написание не всегда совпадает с тем, как поле называется в интерфейсе.

Для Мастера отчётов в Директе я дополнительно использую API и настройки, которые разбирал в статье Мастер отчётов Яндекс Директ — часть задач решается прямо там без необходимости писать API-запросы к Метрике.

Яндекс устанавливает лимиты на запросы к API, которые нужно учитывать при построении автоматизации. Reporting API позволяет получить не более 10 000 строк за один запрос — для счётчиков с большим числом уникальных комбинаций измерений придётся делать постраничную выгрузку с параметром offset. Для Logs API ограничение на количество запросов на выгрузку в сутки составляет несколько штук — точная цифра зависит от объёма данных счётчика.

По частоте запросов к API действует общее ограничение: не более 20 одновременных запросов на один токен. При автоматизации нескольких счётчиков через один токен нужно добавлять паузы между запросами, чтобы не упереться в лимит и не получать ошибки 429 Too Many Requests.

Частые ошибки при работе с API Метрики

Чек-лист настройки автоматизации