AdPump — Reports API на практике: формирование запросов и загрузка отчётов в базу

Практическое руководство по Reports API — как собрать запрос под конкретный отчёт (источники, UTM, сводка по Директу, пол/возраст) и организовать регулярную загрузку результата в свою базу данных.

Коротко: Запрос к Reports API состоит из метрик, измерений, периода и счётчика — те же элементы, что видны в конструкторе отчётов интерфейса. Для регулярной загрузки данных используется скрипт с постраничной обработкой большого ответа и сохранением результата в таблицу СУБД по расписанию.

← Каталог: Метрика · Введение · Системы аналитики · Счётчик и код · Безопасность данных · Основы HTML/JS · Карта настройки · Типы целей · Цели · Автоцели и ecommerce · ЯТМ на практике · Тег Менеджер · Фильтры и операции · Доступы и роли · Вебвизор и карты · Карты и формы · Семплирование · Отчёты · Стандартные отчёты · Атрибуция · Сегментация · Офлайн-конверсии · ClientID и идентификаторы · Measurement Protocol · CRM и интеграции · Битрикс24 и Albato · Мессенджеры · Воронки · AppMetrica · API: введение · API: возможности · API: архитектура · API: окружение · API: Logs · DataLens · Чек-лист · Справка Яндекс Метрики

Содержание

Анатомия запроса к Reports API
Типовые отчёты и их параметры
Постраничная загрузка больших выгрузок
Загрузка результата в базу
Частые ошибки при первой настройке

Анатомия запроса к Reports API

Любой запрос к Reports API строится из четырёх основных частей: счётчик (ID), метрики (что считать — визиты, конверсии, доход), измерения (по чему группировать — источник, UTM-метка, дата) и период (с какого по какое число). Это прямой аналог того, что задаётся кликами в конструкторе отчётов интерфейса, только оформленное как параметры HTTP-запроса.

Типовые отчёты и их параметры

Отчёт	Ключевые измерения	Ключевые метрики
Источники — сводка	Источник трафика, канал	Визиты, посетители, конверсии по цели
По меткам UTM	utm_source, utm_medium, utm_campaign	Визиты, конверсии, доход (для ecommerce)
Директ — сводка	Кампания, группа объявлений	Визиты, расход, конверсии, см. Отчёты
Директ — расходы	Кампания, дата	Расход, клики, показы
Пол	Пол посетителя	Визиты, конверсии
Возраст	Возрастная группа	Визиты, конверсии
Пол и возраст	Пол + возрастная группа (комбинированно)	Визиты, конверсии

Постраничная загрузка больших выгрузок

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

Важно: Не забывайте про семплирование — при большом объёме данных в одном запросе Reports API может вернуть оценочные, а не точные цифры, точно так же, как в интерфейсе.

Загрузка результата в базу

Типовой скрипт для регулярной выгрузки: запрос к API за нужный период -> разбор JSON-ответа -> запись строк в таблицу СУБД (см. Выбор окружения) -> запуск по расписанию (например, раз в сутки за прошедший день). При повторном запуске за уже загруженный период стоит либо перезаписывать данные за этот день, либо явно проверять на дубликаты перед вставкой.

Частые ошибки при первой настройке

Запрашивать слишком большой период одним запросом вместо разбивки по дням — увеличивает риск семплирования и таймаутов.
Не учитывать часовой пояс счётчика при сравнении данных API с интерфейсом — цифры могут не совпадать из-за смещения границ суток.
Забыть про лимиты API (число запросов в сутки/секунду) при частом запуске скрипта — лучше заранее уточнить текущие лимиты в документации, чем упереться в ошибку на проде.

Чек-лист перед запуском регулярной выгрузки

Запрос разбит на разумные периоды (например, по дням), а не один большой диапазон
Учтён часовой пояс счётчика при сравнении с интерфейсом
Обработана пагинация для больших ответов
Предусмотрена защита от дублей при повторном запуске скрипта за тот же период
Проверены текущие лимиты API, если скрипт запускается часто

Комментарий эксперта

Роман Скороходов «Директ — мой вайб»
Руководитель отдела контекстной рекламы Monster Context, рекомендованный специалист Яндекса.

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

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

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

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

Нужно ли переавторизовываться перед каждым запросом?
Нет, OAuth-токен переиспользуется для множества запросов до его истечения или отзыва; получать новый токен на каждый вызов не требуется.

См. также: Logs API, DataLens.

Материал подготовлен редакцией AdPump совместно со специалистами Monster Context (m-context.ru) на основе практики ведения аккаунтов Яндекс Директа и обновлений Яндекс Метрики 2026 года.

Перейти в инструмент