yandex-direct

yandex-direct

Работа с Yandex Direct API v5. Отчёты по кампаниям, расходам, конверсиям, ключевым словам, поисковым запросам. Аудит работы агентств.

Config

Требуется YANDEX_DIRECT_TOKEN в config/.env. Инструкция: config/README.md.

Получение токена (быстрый способ)

1. Откройте в браузере:

   https://oauth.yandex.ru/authorize?response_type=token&client_id=764119e8c8be4c39b6e2d3e6e9dab3c2
   

2. Авторизуйтесь в Яндексе (под аккаунтом с доступом к Директу)
3. Скопируйте access_token из URL после редиректа
4. Добавьте в config/.env:

   YANDEX_DIRECT_TOKEN=ваш_токен
   

Агентские аккаунты

Для работы через агентский аккаунт добавьте логин рекламодателя:

YANDEX_DIRECT_LOGIN=advertiser_login

Или передайте при вызове: --login advertiser_login

Philosophy

1. Cache-first — отчёты кешируются по ключу dates+params. Перед API-запросом всегда проверяем кеш.
2. Context window hygiene — stdout ограничен 30 строками. Полные данные в CSV/файл.
3. Аудит агентств — встроенный agency_audit.sh даёт полную картину: расходы, CTR, конверсии, ключевые слова, поисковые запросы.
4. Reports API — TSV-формат, без заголовка/итога, returnMoneyInMicros=false (деньги в рублях).

Workflow

STOP! Перед любым анализом:

1. Получи список кампаний:

   bash scripts/campaigns.sh
   

2. Спроси пользователя (если не очевидно):

   "О каком аккаунте/клиенте идёт речь?
   Нужен ли логин рекламодателя (--login)?"
   

3. Определи период анализа — по умолчанию последние 30 дней.

4. Запускай нужные отчёты по задаче пользователя.

Типовые сценарии

Быстрый аудит агентства

bash scripts/agency_audit.sh --date1 2026-03-01 --date2 2026-03-27

Выдаёт: кампании по расходу, дневная динамика, топ-20 ключевых слов, топ-20 поисковых запросов.

Проверка расходов по кампаниям

bash scripts/report.sh --date1 2026-03-01 --type campaign

Дневная динамика

bash scripts/report.sh --date1 2026-03-01 --type daily

Ключевые слова — где сливается бюджет

bash scripts/keywords.sh --date1 2026-03-01 --sort cost --limit 30

Поисковые запросы — что ищут люди

bash scripts/search_queries.sh --date1 2026-03-01 --limit 50

Минус-слова — проверить настройку

bash scripts/negatives.sh --campaigns 12345,67890

Scripts

Script	Description	Key params
campaigns.sh	Список кампаний с статусом и бюджетом	--search, --status
report.sh	Отчёт по метрикам (клики, CTR, расход, конверсии)	--type campaign|daily|adgroup|search_query, --campaigns
keywords.sh	Ключевые фразы и их эффективность	--sort cost|clicks|ctr, --limit, --campaigns
search_queries.sh	Поисковые запросы пользователей	--limit, --campaigns
agency_audit.sh	Полный аудит: 4 отчёта за один вызов	--csv для экспорта
negatives.sh	Минус-слова по кампаниям	--campaigns (обязательно)

Common params

Все скрипты поддерживают:

• --date1 YYYY-MM-DD — начало периода (дефолт: 30 дней назад)
• --date2 YYYY-MM-DD — конец периода (дефолт: сегодня)
• --login LOGIN — логин рекламодателя (для агентских аккаунтов)
• --campaigns 123,456 — фильтр по ID кампаний
• --csv path.csv — экспорт в CSV
• --no-cache — игнорировать кеш, запросить свежие данные

Metrics reference

Поле в отчёте	Описание
Impressions	Показы
Clicks	Клики
Ctr	CTR (%)
Cost	Расход (руб. с НДС)
AvgCpc	Средняя цена клика
Conversions	Конверсии
CostPerConversion	Цена конверсии
BounceRate	Процент отказов
AvgImpressionPosition	Средняя позиция показа

Red flags при аудите агентства

На что обратить внимание:

1. Высокий расход, 0 конверсий — кампания не работает или цели не настроены
2. CTR < 3% на поиске — плохие объявления или нерелевантные ключевые слова
3. Много кликов с высоким отказом (>50%) — трафик нецелевой
4. Нет минус-слов — агентство не чистит трафик
5. Поисковые запросы не по теме — широкое соответствие без минус-слов
6. Бюджет сконцентрирован в 1-2 кампаниях — нет диверсификации
7. Нет конверсий, но есть клики — проблема с посадочной или аудиторией