Метрика API: отчёт в таблицу без ручной работы

Раздел практики: Метрика и поведение.

«Каждый понедельник час сводим цифры из трёх кабинетов руками». Скрины в папку, табличка «визиты / заявки / расход», чей-то отпуск — и планёрка без цифр. Автоматизируется за вечер, если понимать, какой из API отдаёт готовые итоги, а какой — сырые строки.

Четыре API — и только один отдаёт готовые цифры

Документация Метрики делит доступ на четыре части; перепутать их дороже, чем в программировании:

• API управления — /management/v1/…: счётчики, цели, фильтры, права доступа. Нужен, чтобы создать цель скриптом, а не кликами.
• API импорта данных — наоборот, вы загружаете в Метрику: расходы, заказы из CRM, офлайн-конверсии, параметры посетителей.
• API отчётов — /stat/v1/data: те самые готовые цифры, метрики по группировкам, как в веб-интерфейсе. Для понедельничной сводки нужен именно он.
• API Logs — /management/v1/counter/{id}/logrequests: неагрегированные строки визитов и событий для своей обработки: склейка с CRM, разбор по посетителю.

Ошибка черновиков — идти в Logs за «топом страниц»: там строки, итоги по URL считаете сами. Готовые итоги — в API отчётов.

Токен: десять минут и три правила

Приложение создаётся на oauth.yandex.ru с пунктом «Для доступа к API или отладки»; сводчику нужен только доступ metrika:read — статистика и параметры счётчиков. Дальше ссылка вида https://oauth.yandex.ru/authorize?response_type=token&client_id=<ID>, один проход авторизации — и токен в руках. Правила:

• Только чтение. metrika:write (создание и изменение счётчиков) скрипту-сводчику не нужен никогда.
• Токен — вне репозитория и скриншотов: файл с правами на вашего пользователя; токен равен паролю к данным.
• Отзыв работает: на странице «Безопасность» аккаунта Яндекса снимается за клик — отзывайте всё, что раздавали подрядчикам.

Скрипт после «ведь работало же» отдаёт 401 или 403? В девяти случаях из десяти это токен: истёк, отозван или приложению не дали нужный доступ.

Первый запрос: источники за неделю

«Визиты и посетители по источникам» — один GET, ответ ложится в таблицу как есть:

curl -s -G 'https://api-metrika.yandex.net/stat/v1/data.csv' \
  -d 'ids=1234567' \
  -d 'metrics=ym:s:visits,ym:s:users' \
  -d 'dimensions=ym:s:trafficSource' \
  -d 'date1=2026-10-01' -d 'date2=2026-10-07' \
  -d 'limit=20' \
  -H 'Authorization: OAuth <ВАШ_ТОКЕН>'

Про параметры спрашивают чаще всего:

• metrics — не больше 20 метрик, dimensions — не больше 10 группировок в запросе.
• date1 и date2 принимают не только даты: yesterday и 7daysAgo удобнее для «плавающей» недели.
• limit по умолчанию 100 строк, максимум 100 000: без него «теряете хвост» и потом спорите с кабинетом.
• preset — готовые шаблоны отчётов (например, sources_summary), если не хочется собирать знакомую связку вручную.
• Группировки и метрики живут в двух множествах: ym:s: — визиты, ym:pv: — хиты; в одном запросе их не смешивают. Страницы — это хит-множество (ym:pv:URL, ym:pv:URLPathLevel1), метрики берите оттуда же, а названия полей держите в закладке со справочником: в старом и новом синтаксисе они различаются.

Тот же отчёт по дням — /stat/v1/data/bytime: им закрывают «цели по дням» и графики к планёрке.

Logs API: заказать, дождаться, скачать

Logs API работает асинхронно — из-за этого «простой curl» превращается в три шага:

1. Заказать. POST /management/v1/counter/{id}/logrequests с параметрами date1, date2, fields (список полей через запятую), source (hits или visits) и attribution (модель атрибуции). В ответе — request_id, статус и части с размерами.
2. Дождаться обработки. Статусы меняются: created, затем обработанный processed; бывают processing_failed и awaiting_retry. В момент заказа логов ещё нет, поэтому цикл «спросил и сразу скачал» без паузы не работает.
3. Скачать части. GET /management/v1/counter/{id}/logrequest/{requestId}/part/{partNumber}/download — номера частей берутся из ответа заказа. С заголовком Accept-Encoding: gzip файл приходит сжатым, его распаковывают перед разборкой.

Фильтрации на уровне запроса логов нет: просите поля и даты, а режьте уже у себя. Из полей визитов обычно берут ym:s:visitID, ym:s:startURL, ym:s:pageViews, ym:s:visitDuration, ym:s:bounce.

Квоты: почему всё «внезапно» перестало работать

Три разных отказа в чате называют одной фразой «API упал»:

• Токен — 401/403, см. выше.
• Хранилище логов — на логи одного счётчика отведено 10 ГБ, и неудалённые файлы съедают место: новые запросы встанут. Документация прямо советует удалять подготовленное и скачанное; выше квота — в Метрике Про.
• Размер запроса — период не больше года, список полей — не больше 3000 символов, а статистика текущего дня недоступна (может быть неполной): просят со вчерашнего дня.

И учтите, что свежая история «дозревает»: по документации около 99 % визитов завершаются в течение трёх дней после начала. Сводка за прошлую неделю устойчива, сводка за вчера — нет. Отсюда и различие цифр: Logs API и интерфейс считаются по-разному (интерфейс применяет свои алгоритмы, а часть полей хранится с коэффициентом — у ym:s:goalsPrice это 1000). Сходится-не-сходится проверяйте по API отчётов, а не по логам.

Типовой набор выгрузок

Когда канал отладен, хватает четырёх регламентных задач:

• Источники за неделю — поиск / соцсети / переходы (запрос выше). Рядом просится разметка меток одной схемой , иначе таблица будет спорить с кабинетом.
• Топ страниц за месяц — хит-множество: что растёт, что умерло.
• Цели по дням — bytime, отдельным листом, в связке с еженедельным обзором Метрики.
• Дашборд на экран — сегодня против прошлой недели; чаще раза в пять минут такие вещи не дёргают.

Логи подключают, когда этих четырёх мало: склейка визита с заказом из CRM, когорты, «почему у одного человека две истории». Ряды тогда хранят у себя — в таблице, в базе или в Matomo, где история длиннее чужого хранилища.

Считать трезво

Час настройки окупается арифметикой, а не любовью к автоматизации: сводка из трёх кабинетов раз в неделю — те самые ~4 часа в месяц, которые перестают зависеть от чьего-то отпуска. Если вы и так заходите в кабинет дважды в неделю по минуте — API не нужен, это игрушка. Граница тоже простая: API отдаёт то, что насчитал счётчик. Корректность установки, целей и фильтров — на стороне чеклиста кабинетов, а вопрос «можно ли вообще держать Google Analytics» разобран в материале про работу Google Analytics в России.