API Яндекс Метрики: как вытащить свои цифры, когда интерфейс их не показывает

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

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

Зачем всё это малому бизнесу

Четыре задачи, ради которых владельцу сайта имеет смысл связываться с выгрузками, и все четыре встречаются в обычной жизни.

Сводка по нескольким сайтам в одной таблице. Если у вас основной сайт, лендинг под рекламу и пара поддоменов по городам, интерфейс заставляет ходить по счётчикам поочерёдно. Выгрузка кладёт всё в одну таблицу: сразу видно, кто растёт, а кто просел.

Длинная история. В интерфейсе вы каждый раз заново выставляете период и сравниваете глазами. В своей таблице данные копятся строками: тридцать шесть месяцев подряд, и сезонность видна сразу.

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

Разбор сырых визитов. Этого интерфейс не умеет в принципе. Когда надо понять, что за волна трафика пришла во вторник ночью, помогает не диаграмма, а список отдельных визитов с адресами, временем, источником и признаками робота. Это территория Logs API и главная причина, по которой к нему приходят. Похожая логика работает и с логами сервера, только там записи другие.

Три разных API, которые постоянно путают

В документации Метрики их ровно три, и различаются они не сложностью, а тем, что отдают.

Management API — управление счётчиком. Создать счётчик, изменить настройки, завести цель, выдать доступ, посмотреть параметры. Данных о посещаемости он не отдаёт вообще. Нужен тем, у кого счётчиков десятки и настройки меняются пачками.

API отчётов — агрегированная статистика, та же, что в отчётах интерфейса. Вы задаёте период, набор метрик и набор группировок и получаете таблицу. Ответ отдаётся в UTF-8 в формате JSON или CSV.

Logs API — неагрегированные данные. Не «за вторник было 412 визитов», а 412 строк, по строке на визит, с полями этого визита. Обрабатывать их вы будете сами, зато и вопросы можно задавать любые.

Различие между вторым и третьим принципиальное. API отчётов отвечает на вопрос, сформулированный заранее. Logs API даёт материал, на котором можно задать вопрос, который вы заранее не придумали.

Что нужно для доступа

Доступ к любому из трёх API даёт OAuth-токен. Порядок такой: в OAuth-консоли Яндекса создаётся приложение с вариантом «Для доступа к API или отладки», заполняются название и контактная почта, выбираются права. Дальше берётся ClientID приложения и подставляется в адрес вида https://oauth.yandex.ru/authorize?response_type=token&client_id=идентификатор — по этой ссылке Яндекс покажет токен, который и подставляется в запросы.

Права называются так: metrika:read — получение статистики и чтение параметров своих и доверенных счётчиков; metrika:write — создание счётчиков и изменение параметров. Есть ещё специализированные, для загрузки расходов, пользовательских параметров и офлайн-данных, и право на запись их функциональность включает. Для чтения отчётов и для Logs API достаточно metrika:read — то есть для задач, описанных выше, токен на запись вам не нужен, и выдавать его подрядчику незачем.

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

Токен не вечный. По документации он продлевается сам, если им пользуются, а неактивный перестаёт работать примерно через год; ещё он слетает при смене пароля на аккаунте, для которого был выпущен. Практический вывод: если недельный отчёт вдруг перестал приходить, первым делом проверяйте токен, а не скрипт.

API отчётов: как выглядит запрос

Ручка одна: https://api-metrika.yandex.net/stat/v1/data. Обязательных параметров два — ids (номер счётчика) и metrics (что считаем). Остальное по желанию: dimensions (по чему группируем), date1 и date2 (период), filters, sort, limit и offset для постраничной выдачи.

Названия метрик и группировок устроены единообразно. Метрики: ym:s:visits — визиты, ym:s:users — посетители, ym:s:bounceRate — показатель отказов, ym:s:pageviews — просмотры, ym:s:goal<номер цели>conversionRate — конверсия по конкретной цели. Группировки: ym:s:date — по дням, ym:s:trafficSource — по типу источника, ym:s:searchEngine — по поисковой системе, ym:s:regionCityName — по городу, ym:s:browser — по браузеру. Кроме основной ручки есть соседние: /stat/v1/data/bytime для разбивки по времени и /stat/v1/data/comparison для сравнения периодов.

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

Вопрос владельца	Что запрашивать	Чем это в интерфейсе
Как менялась посещаемость по дням	Метрика визитов, группировка по дате	Отчёт «Посещаемость»
Откуда приходят люди	Визиты и отказы, группировка по типу источника	«Источники, сводка»
Сколько заявок и по какой цели	Достижения и конверсия по номеру цели	Отчёт «Конверсии»
Из каких городов приходят	Визиты, группировка по названию города	«География»
Какие страницы принимают трафик	Визиты, группировка по странице входа	«Страницы входа»
Три сайта в одной таблице	Тот же запрос, разные номера счётчиков	Никак, только вручную
Что происходило в отдельном визите	Logs API, таблица визитов	Вебвизор, но выборочно и вручную
Массовое изменение настроек счётчиков	Management API	Руками по каждому счётчику

Logs API: сырые визиты, и как их забирают

Logs API устроен не как обычный запрос-ответ, а как заказ выгрузки. Последовательность по документации такая: сначала можно оценить возможность выгрузки через logrequests/evaluate, затем создаётся запрос методом POST /management/v1/counter/{counterId}/logrequests и в ответ приходит его идентификатор. Дальше вы периодически спрашиваете статус этого запроса и ждёте состояния processed. Когда готово — скачиваете результат частями через .../part/{partNumber}/download, а потом вызываете clean, чтобы освободить место под следующие выгрузки.

Ограничения, о которых лучше знать заранее, перечислены во введении к Logs API. Период в одном запросе — не больше года. Данные текущего дня недоступны: они могут быть неполными, и в документации прямо рекомендуется запрашивать вчерашний день и раньше. Более того, визиты продолжают уточняться по мере поступления информации, и 99% визитов завершаются в течение трёх дней — то есть выгрузка за вчера и та же выгрузка за то же вчера, сделанная через неделю, могут слегка различаться. Список запрашиваемых полей ограничен по длине: параметр с их перечислением — до 3000 символов. И есть квота хранилища: 10 ГБ на счётчик, расширяется подпиской Метрика Про.

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

Именно последнее поле и делает Logs API интересным для владельца, которому кажется, что его «крутят». Вместо спора с диаграммами вы смотрите список визитов глазами: с каких адресов, в какие минуты, с какой страницей входа. Как это выглядит на практике, разобрано в материале про определение ботов на сайте. Второе частое применение — свести визиты с продажами; кому это реально нужно, есть отдельный разбор.

Лимиты и квоты: что будет, если увлечься

Метрика ограничивает не объём данных, а интенсивность обращений. При превышении квот API отвечает кодом 429 Too Many Requests и сообщает, какая именно квота исчерпана.

Ограничение	Значение по документации	Что это значит на практике
Запросов в секунду с одного IP	30 к API, 10 к Logs API	Скрипт в цикле без пауз упрётся в это первым
Параллельных запросов от пользователя	3	Выгружать десять счётчиков одновременно не получится
Запросов в сутки от пользователя	5000	Недельному отчёту хватает с большим запасом
Запросов к отчётам за 5 минут	200 от пользователя и 200 на счётчик	Ограничение на «перебрать всё сразу»
Период в одном запросе Logs API	не более 1 года	Три года выгружаются тремя заказами
Длина перечня полей Logs API	3000 символов	Брать все поля подряд не стоит, только нужные
Хранилище выгрузок	10 ГБ на счётчик	После скачивания выгрузку нужно удалять
Ответ при превышении	HTTP 429	Суточная квота снимается в 00:00 GMT, пятиминутная — через 5 минут

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

Почему числа из выгрузки не сошлись с интерфейсом

Классическая история: скрипт отдал одну цифру визитов, отчёт на экране — другую, человек решает, что сломался скрипт. Чаще всего не сломалось ничего.

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

Второе. Данные дозревают. Если сравнивать выгрузку за вчера со вчерашним же отчётом, открытым сегодня утром, часть визитов ещё уточняется.

Третье, самое неожиданное. Некоторые сочетания группировок Метрика считает чувствительными — например, пол вместе с возрастом. В таких ответах появляется признак contains_sensitive_data, и показываются только строки, за которыми стоит не меньше десяти посетителей. Остальное просто не приходит, и итог по таблице не сходится с общим числом. Лечится расширением периода или отказом от чувствительной группировки.

Четвёртое и самое частое: сравнивают разное. Разные периоды, разный часовой пояс, в одном случае с роботами, в другом без. Прежде чем искать ошибку в коде, убедитесь, что спрошено одно и то же.

Когда нужен разработчик, а когда нет

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

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

Отдельно про здравый смысл. Автоматизация окупается там, где отчёт нужен часто и по нему принимают решения. Если сводка открывается раз в квартал и никто по ней ничего не делает, скрипт этого не исправит. Какие отчёты по рекламе стоит держать перед глазами, разобрано в материале про аналитику Директа в Метрике.

Когда это не сработает и когда нужен специалист

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

Не поможет она и там, где вопрос не в цифрах, а в их толковании. Выгрузка показывает: по переходам из поиска тридцать заявок, по рекламе двадцать. Что делать — увеличивать бюджет, менять страницу или закрывать канал — из таблицы не следует. Тут нужен человек, который видел сотни таких таблиц и знает, какие расхождения обычные, а какие означают поломку.

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

Частые вопросы

Нужно ли платить за доступ к API?

Сам доступ входит в Метрику. Платной подпиской Метрика Про расширяются квоты — например, объём хранилища выгрузок Logs API и число запросов. Для задач малого бизнеса базовых квот обычно хватает с запасом.

Можно ли получить данные за сегодня?

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

Что делать, если пришёл ответ 429?

Подождать и повторить запрос. В ответе указано, какая квота исчерпана: пятиминутные ограничения снимаются через пять минут, суточное — в 00:00 по GMT. Если 429 приходит постоянно, дело не в квотах Яндекса, а в скрипте, который бьёт в цикле без пауз.

Можно ли выгрузить данные за период до установки счётчика?

Нет. API отдаёт то, что счётчик собрал. Если счётчик поставили в марте, февраля не будет ни в каком виде.

Безопасно ли отдавать токен подрядчику?

Лучше не отдавать. Правильный порядок — выдать гостевой доступ к счётчику на его аккаунт, а токен он выпустит себе сам. Доступ потом отзывается одним действием, а чужой токен от вашего аккаунта — это ключ не только к статистике.

Заменяет ли выгрузка работу с отчётами?

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

Коротко

У Метрики три API: Management для управления счётчиками, API отчётов для агрегированной статистики и Logs API для неагрегированных данных по отдельным визитам. Новых данных ни один из них не открывает — меняется только форма выдачи.

Доступ даёт OAuth-токен, выпущенный на приложение с правом metrika:read. Для чтения отчётов и выгрузок этого достаточно, право на запись нужно только для управления счётчиками и загрузки данных извне.

API отчётов — это адрес /stat/v1/data с параметрами: номер счётчика, метрики, группировки, период. Ответ приходит в JSON или CSV и открывается таблицей.

Logs API работает заказом: создали запрос, дождались готовности, скачали частями, очистили. Период — до года, данных за сегодня нет, визиты дозревают несколько дней, хранилище ограничено 10 ГБ на счётчик.

Квоты ограничивают интенсивность, а не объём: при превышении приходит 429. Обычной отчётности малого бизнеса до этих границ очень далеко.

Расхождения с интерфейсом чаще всего объясняются дополнительной обработкой в интерфейсе, дозреванием данных, защитой чувствительных сочетаний группировок и тем, что сравнивают разные периоды. Программу надо проверять в последнюю очередь.

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