Рекламу в Яндекс Директе ведут многие, а вот забирать данные к себе в базу умеют не все. Собрать статистику за полгода, построить дашборд в Power BI, свести расходы с продажами из CRM - всё это требует хранения данных на своей стороне.
В этой статье покажу, как забирать данные из Яндекс Директа через API на Python и складывать их в базу данных: ClickHouse, PostgreSQL или MySQL. Использовать будем бесплатную библиотеку morin, а начнём с простой демонстрации, которую можно запустить локально без сервера и без Docker.
Зачем выгружать данные из Яндекс Директа
Интерфейс Директа хорош для оперативного управления, но плох для аналитики. Как только задач становится много, упираешься в потолок:
- История ограничена, а хочется хранить данные за все годы.
- Свести Директ с другими источниками (Метрика, CRM) внутри интерфейса нельзя.
- Строить сложные срезы и свои метрики неудобно.
- Автоматизировать выгрузку под дашборд руками невозможно.
Решение одно: забрать данные из Яндекс Директа через API в свою базу данных и работать там. В базе хранится вся история, к ней подключается любой BI-инструмент, а данные обновляются автоматически.
Что такое API Яндекс Директа
API Яндекс Директа - интерфейс, через который программа получает данные рекламного аккаунта напрямую, без захода в интерфейс. Через Директ API можно вытянуть список кампаний, статистику по дням (клики, показы, расход), список объявлений и множество других параметров и показателей.
Работает яндекс директ API так: вы отправляете HTTP-запрос с токеном авторизации, а в ответ получаете данные. Статистика приходит в виде отчёта (формат TSV), справочные данные вроде кампаний и объявлений - в JSON. Библиотека morin прячет эти детали внутри, отдавая на выходе готовые строки для базы данных.
Как устроены отчёты и запросы к ним, подробно описано в справке API Яндекс Директа по отчётам.
Получаем доступ к API: токен и логин
Для работы с API Яндекс Директа нужны две вещи:
- OAuth-токен - ключ авторизации.
- Client-Login - логин рекламного аккаунта, данные которого забираем.
Токен получить просто - по готовой ссылке, регистрировать своё приложение и слать заявку на доступ не нужно:
- Перейдите по ссылке для получения токена.
- Авторизуйтесь под аккаунтом Яндекса, к которому привязан Директ, и подтвердите доступ.
- Вас перекинет на страницу с токеном - длинной строкой вида y0_Ag... Скопируйте её, это и есть ваш OAuth-токен.
Client-Login - это логин того аккаунта, чью статистику собираете (например, my-agency-client). Токен привязан к аккаунту и действует ограниченное время (обычно около года), после чего получается заново по той же ссылке.
Токен даёт доступ к вашему рекламному аккаунту, поэтому храните его в секрете. Посмотреть, каким приложениям выдан доступ, и при необходимости отозвать токены можно на странице доступа аккаунта Яндекса.
Устанавливаем библиотеку morin
morin - бесплатная библиотека для получения данных из разных API (Директ, Метрика, WB, OZON и другие) и загрузки в базу. Ставится обычным pip:
pip install morin
Дополнительно поставьте драйвер той базы, куда будете грузить данные:
pip install clickhouse-connect # для ClickHouse
pip install psycopg2-binary # для PostgreSQL
pip install pymysql # для MySQLДля первой демонстрации без базы данных хватит одной morin.
Бесплатный старт: получаем данные Директа на Python
Начнём с самого простого - просто вытащим данные Директа в Python и посмотрим на них. Никакой базы и Docker пока не нужно, всё запускается локально и бесплатно.
Создаём объект коннектора с токеном и логином:
from morin import YDbyDate
yd = YDbyDate(
login='ВАШ_CLIENT_LOGIN', # логин рекламного аккаунта
token='ВАШ_OAUTH_ТОКЕН', # OAuth-токен Яндекс Директа
start='2025-01-01', # с какой даты собирать статистику
columns='Date,Clicks,Cost,Impressions', # какие поля нужны
report='date',
)Список кампаний. Проверим, что доступ работает, получив кампании аккаунта:
campaigns = yd.get_campaigns()
for c in campaigns:
print(c['Id'], c['Name'])Статистика по дням. Главный отчёт - цифры по кликам, расходам и показам за период с start по вчерашний день:
stats = yd.get_data()
for row in stats:
print(row)
# Каждая строка - словарь:
{'Date': '2025-01-15', 'Clicks': 120, 'Cost': 3450.5, 'Impressions': 8900}На выходе - список словарей, по одному на строку отчёта. Это и есть статистика Яндекс Директа, готовая к анализу: можно сразу закинуть в pandas, посчитать суммы или сохранить.
Объявления. Отдельным методом забираем тексты объявлений по всем кампаниям:
ads = yd.collect_campaign_ads()
for ad in ads[:5]:
print(ad['CampaignName'], ad['Title'], ad['Href'])Всё это работает без базы данных - чистое получение данных из Яндекс Директа на Python. Уже на этом этапе библиотеку можно использовать как обычный клиент директ API.
Какие поля можно запросить
В параметре columns перечисляются поля отчёта Яндекс Директа. Самые ходовые:
Date- дата.CampaignName,CampaignId- кампания.Impressions- показы.Clicks- клики.Cost- расход.Conversions- конверсии (нужны цели, параметрgoals).
Типичная таблица в БД по данным Яндекс Директа выглядит так:
Полный список полей есть в документации по параметрам и показателям Яндекс Директа. Библиотека сама определит типы столбцов, поэтому при добавлении новых полей код менять не нужно.
Расчётные поля типа CPC или CTR лучше всего рассчитывать в самом отчёте, так как они будут зависеть от выбранного списка параметров - дат, кампаний, итд и по API их обычно не получают. Ведь тот же CTR обычно интересен в разрезе Поиск/РСЯ, а не по каждому объявлению и дате.
Загрузка данных Яндекс Директа в ClickHouse
Теперь самое интересное - сложим статистику в базу данных. Начнём с ClickHouse, популярной аналитической СУБД (про неё у нас есть отдельные статьи). Нужен запущенный ClickHouse: локально его поднимают одной командой Docker или ставят на сервер.
Добавляем в конструктор параметры подключения к базе и вызываем один метод:
from morin import YDbyDate
yd = YDbyDate(
subd='clickhouse', # тип базы данных
host='localhost', port='8123',
username='default', password='',
database='direct',
add_name='client1', # префикс таблиц этого аккаунта
login='ВАШ_CLIENT_LOGIN',
token='ВАШ_OAUTH_ТОКЕН',
start='2025-01-01',
backfill_days=3, # сколько последних дней пересобирать
columns='Date,Clicks,Cost,Impressions',
report='date',
)
yd.collecting_manager()Что делает collecting_manager:
- сам создаёт таблицу в ClickHouse и определяет столбцы по данным отчёта;
- работает по принципу Airflow - в служебной таблице фиксирует, за какие дни данные уже собраны;
- при повторном запуске догружает только недостающие дни, а не тянет всё заново;
- параметр
backfill_daysзаставляет перезабрать несколько последних дней (статистика Директа задним числом уточняется).
После запуска в базе появится таблица со статистикой по дням. Дальше к ней подключается любой дашборд.
То же самое в PostgreSQL и MySQL
Главный плюс morin: чтобы грузить не в ClickHouse, а в PostgreSQL или MySQL, меняется ровно один параметр - subd. Весь остальной код и логика те же.
Для PostgreSQL:
yd = YDbyDate(
subd='postgresql',
host='localhost', port='5432',
username='postgres', password='postgres',
database='direct',
add_name='client1',
login='ВАШ_CLIENT_LOGIN', token='ВАШ_OAUTH_ТОКЕН',
start='2025-01-01', backfill_days=3,
columns='Date,Clicks,Cost,Impressions',
report='date',
)
yd.collecting_manager()Для MySQL меняем subd на 'mysql' и порт на 3306:
yd = YDbyDate(
subd='mysql',
host='localhost', port='3306',
username='root', password='',
database='direct',
add_name='client1',
login='ВАШ_CLIENT_LOGIN', token='ВАШ_OAUTH_ТОКЕН',
start='2025-01-01', backfill_days=3,
columns='Date,Clicks,Cost,Impressions',
report='date',
)
yd.collecting_manager()morin сама переведёт типы столбцов под выбранную базу данных и создаст таблицу. То есть один и тот же коннектор Яндекс Директа умеет наполнять три разные СУБД.
Какие отчёты умеет получать коннектор
У коннектора Директа три режима, они задаются параметром report:
date- статистика по дням (клики, расходы, показы). Обновляется инкрементально по датам, это основной отчёт.ads- объявления: тексты, заголовки, ссылки. Обновляется целиком.nodate- сводная статистика за весь период без разбивки по дням.
Для регулярного сбора обычно используют date: он копит историю день за днём и не перегружает API повторными запросами.
Автоматизация через Docker
Скрипты выше запускаются руками, что не совсем удобно. Чтобы данные Яндекс Директа обновлялись сами, morin разворачивают в Docker - это позволяет запускать скрипт по расписанию, с логами и уведомлениями в Telegram. Мы подробно разобрали такой сценарий в статье про коннекторы к API в ClickHouse на Docker.
У нас есть удобный excel-файл для заполнения настроек подключения, а также конфиг для clickhouse.
Всё это доступно на нашей платформе по подписке "базовый уровень". Но при желании вы можете сами написать похожий скрипт используя примеры из этой статьи - все функции загрузки данных бесплатны и доступны после установки библиотеки morin.
FAQ
Как получить данные из Яндекс Директа через API на Python?
Установите библиотеку morin (pip install morin), создайте объект YDbyDate с OAuth-токеном и Client-Login и вызовите методы get_campaigns, get_data (статистика) или collect_campaign_ads. Данные вернутся списком словарей.
Бесплатно ли пользоваться API Яндекс Директа?
Да, сам API Яндекс Директа бесплатный, библиотека morin тоже. Платить нужно только за сервер и базу данных, если вынесете сбор в облако. Для теста всё запускается локально без затрат.
В какую базу данных можно грузить данные Директа?
Коннектор morin умеет ClickHouse, PostgreSQL и MySQL. База выбирается одним параметром subd, остальной код не меняется.
Чем директ API лучше выгрузки из интерфейса?
Через API данные забираются автоматически, за любой период и сразу в базу. Это снимает ручную работу и позволяет строить дашборды и сводить Директ с другими источниками.
Как обновлять статистику Яндекс Директа инкрементально?
morin запоминает собранные дни в служебной таблице и при следующем запуске догружает только новые даты. Параметр backfill_days дополнительно перезабирает несколько последних дней, потому что статистика Директа уточняется задним числом.
Заключение
Мы разобрали, как забирать данные и статистику из Яндекс Директа через API на Python и грузить их в ClickHouse, PostgreSQL или MySQL с помощью бесплатной библиотеки morin. Начали с простой локальной демонстрации без сервера, а затем одной строкой направили те же данные в базу.
Главное: получение данных Директа сводится к паре методов, а выбор базы данных - к одному параметру. Дальше остаётся подключить к базе дашборд и автоматизировать сбор. По такому же принципу morin работает и с другими источниками - Метрикой, WB, OZON, VK, о них будут отдельные статьи.
