/yandex-direct

Статистика и позиции в Яндекс Директе

Команда scripts/report.py получает отчёты и сохраняет полные данные в местный кэш. Она не меняет рекламу. Запускайте примеры из директории скилла; логин, ID кампании, даты и цели заменяйте на выбранные для задачи.

Сначала выбрать ценные цели

Перед оценкой эффективности выясните, какие действия пользователь считает результатом: заказ, оплата, заявка, звонок или несколько таких действий. Получите доступные цели и покажите их названия вместе с ID:

uv run scripts/report.py --account client-login --campaign 123456 --list-goals

Список приходит из GetStatGoals по выбранной кампании. Без --campaign опрашиваются неархивные кампании кабинета. Сегменты ретаргетинга в список целей статистики не добавляются. Метод работает в версии Live 4, как указано в таблице соответствия методов API.

Спросите пользователя, какие цели считать ценными, и дождитесь выбора. Цель стратегии, первая цель в списке или «все конверсии» не заменяют этот выбор. Если пользователь уже выбрал цели для этой кампании в текущем разговоре, используйте тот же набор и назовите его рядом с результатом. Не переносите выбор на другой кабинет или кампанию без основания.

uv run scripts/report.py --account client-login --campaign 123456 \
  --preset campaigns --period LAST_30_DAYS --goals 20002,20003 --attribution AUTO

Все готовые отчёты с конверсиями требуют --goals. Без него команда покажет доступные цели и завершится с кодом 2, не запрашивая статистику по всем целям. Если название цели не пришло или список пуст, проверьте счётчик и права доступа; можно передать ID, который явно назвал пользователь.

До выбора целей можно получить показы, клики и расход:

uv run scripts/report.py --account client-login --campaign 123456 \
  --preset campaigns --period LAST_30_DAYS --traffic-only

По такому отчёту нельзя делать вывод об окупаемости или стоимости заявки.

Готовые отчёты

uv run scripts/report.py --list
uv run scripts/report.py --preset daily --campaign 123456 \
  --period 2026-08-01:2026-08-31 --goals 20002 --attribution AUTO
uv run scripts/report.py --preset placements --campaign 123456 \
  --filter 'AdNetworkType EQUALS AD_NETWORK' --goals 20002 --attribution AUTO

Период по умолчанию — LAST_30_DAYS. Для повторяемого сравнения лучше указать точные даты. --compare previous берёт такой же интервал непосредственно перед заданными датами. Можно передать второй интервал явно:

uv run scripts/report.py --preset campaigns --campaign 123456 \
  --period 2026-08-01:2026-08-31 --compare previous \
  --goals 20002 --attribution AUTO --json

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

Пример: исторически ценные запросы и текущие верхние позиции

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

Сначала определите историю: квартал или последние 180 дней. Затем выберите недавний период для проверки позиций, обычно 14–30 полных дней. Назовите оба периода в ответе. Поисковые запросы доступны только за последние 180 дней; календарное полугодие иногда длиннее. Если часть запрошенной истории уже недоступна, сообщите фактическое покрытие и используйте сохранённые выгрузки, если они есть. Ограничения Reports.

1. Получите исторические запросы с выбранными целями. Отберите их по числу целевых визитов, доле конверсий и цене результата. Укажите фактические пороги отбора; одна конверсия сама по себе не доказывает устойчивый результат.
2. Получите тот же отчёт за недавний период. Сопоставьте строки по кампании, группе, запросу и условию показа. Отсутствие строки означает отсутствие данных в выгрузке, а не нулевую позицию.
3. По отобранным условиям показа проверьте распределение показов между блоками в search_positions. Связь с запросами — через CampaignId, AdGroupId, CriterionId и CriterionType. Пустой ID не связывайте наугад.
4. Прочитайте действующую стратегию, ставки и ограничения бюджета. Объясните, что именно ограничивает показы и какое изменение может помочь.

# История: задайте даты квартала или интервала до 180 дней.
uv run scripts/report.py --account client-login --campaign 123456 \
  --preset search_queries --period 2026-04-01:2026-06-30 \
  --goals 20002 --attribution AUTO --csv /tmp/direct-history.tsv

# Текущие позиции тех же запросов.
uv run scripts/report.py --account client-login --campaign 123456 \
  --preset search_queries --period LAST_14_DAYS \
  --goals 20002 --attribution AUTO --csv /tmp/direct-current.tsv

# Распределение показов по блокам: далее сопоставьте нужные условия по ID.
uv run scripts/report.py --account client-login --campaign 123456 \
  --preset search_positions --period LAST_14_DAYS \
  --goals 20002 --attribution AUTO --csv /tmp/direct-positions.tsv

AvgImpressionPosition — средняя позиция показа, AvgClickPosition — средняя позиция клика; обе учитывают первую страницу поиска, позиция 1 — самая высокая. AvgTrafficVolume описывает средний объём трафика с занятых позиций. Это не процент выкупленных показов. Описание показателей.

Slot=PREMIUMBLOCK означает спецразмещение. Его доля — показы этого блока / все показы выбранного условия на поиске × 100%. ALONE и остальные блоки показывайте отдельно. Такая доля описывает фактические показы, а не долю всех доступных аукционов. API не даёт Slot в отчёте по запросам: результат по условию нельзя выдавать за точную долю конкретного запроса. Допустимые поля.

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

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

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

Как читать конверсии и деньги

Общие формулы и правила расчёта применяются к одному отбору, периоду, валюте и модели атрибуции. Для каждой выбранной цели используются её целевые визиты Conversions_g. В Метрике CR может рассчитываться от визитов или посетителей; перед сравнением с Директом проверьте знаменатель.

В одном запросе можно указать до 10 целей. API возвращает отдельные столбцы вида Conversions_20002_AUTO, ConversionRate_20002_AUTO, CostPerConversion_20002_AUTO, Revenue_20002_AUTO.

Выгрузку search_queries с выбранными целями можно сразу передать в подбор минус-фраз — добавлять или переименовывать столбец Conversions не нужно:

uv run scripts/keywords_write.py --account client-login negative from-report \
  --report /tmp/direct-history.tsv --campaign 123456 --min-clicks 20

Команда показывает, какие столбцы конверсий проверяет. Запрос становится кандидатом только при явном нуле по каждой цели и модели из файла во всех его строках для выбранной кампании или группы. Даже дробная конверсия исключает запрос. По пустой ячейке или прочерку команда не делает вывод, что конверсий не было, и такой запрос тоже не предлагает. Цели и модели не суммируются. Чтобы рассмотреть другой набор целей или одну модель, выгрузите отчёт с соответствующими --goals и --attribution. Обычный столбец Conversions также поддерживается. Без --phrase команда только предлагает запросы; запись выбранных минус-фраз требует --apply.

По умолчанию скилл использует AUTO — автоматическую атрибуцию. Если при анализе обнаружилась другая модель кампании или стратегии, предложите выбрать модель отчёта. Например: «В кампании стоит LC. Смотреть по AUTO, как обычно, по LC для сопоставления со стратегией или сравнить обе модели?» Объясните, что конверсии и CPA при разных моделях могут отличаться. Уже сделанный выбор не уточняйте повторно.

Выбранную модель или несколько моделей задавайте через --attribution, например --attribution LC или --attribution AUTO,LC. Доступны LC, LSCCD, FCCD, AUTO. Для сравнения периодов используйте одинаковую модель и называйте её в ответе. Если пользователь предпочитает AUTO, можно отдельно предложить сменить настройку кампании с LC на AUTO: это самостоятельная правка, а не следствие выбора модели отчёта. Порядок — в практиках.

Для отчётов с --goals команда явно передаёт выбранную модель, включая AUTO по умолчанию: сам API без параметра использует LC. Без целей параметр AttributionModels не передаётся, даже если указан --attribution. Это относится и к --traffic-only, и к расходу в аудите объявлений: для показов, кликов и расхода модель не нужна. Параметры отчёта.

Один визит может достичь нескольких целей. Покажите каждую цель отдельно: сумма конверсий по целям не равна числу уникальных клиентов или заявок. CPA каждой цели — расход / конверсии этой цели. Доход по выбранным целям тоже не складывайте без проверки пересечений. Значения -- и пустые ячейки означают отсутствие показателя, их нельзя превращать в нули. Содержание отчёта.

В сводке деньги показаны в валюте кабинета, НДС по умолчанию учтён (--vat YES). JSON и TSV сохраняют документированные денежные поля в миллионных долях валюты: 125000000 означает 125 единиц. Для отчёта по поисковым запросам отдельный общий итог не запрашивается: отчёт без разреза по запросам имеет другой состав данных. В остальных отчётах общий расход считается отдельным запросом; средние цены и проценты не складываются. У каждого кабинета своя валюта, расходы разных валют не суммируются.

Готовые отчёты не выводят Profit: это общий показатель API. Если нужна прибыль по конкретной цели, считайте её из дохода этой цели и расхода. В собственном отчёте PurchaseRevenue, PurchaseProfit, PurchaseGoalsRoi требуют явного фильтра PurchaseGoals IN ID[,ID]: это отдельный выбор целей покупок, параметр --goals его не заменяет.

Собственный отчёт и выгрузка

uv run scripts/report.py --account client-login --campaign 123456 \
  --type CUSTOM_REPORT --fields CampaignId,Date,Clicks,Cost \
  --period 2026-08-01:2026-08-31 --order-by Date:asc --csv /tmp/direct.tsv

--filter можно повторять для разных полей. Пример: --filter 'Query EQUALS ремонт квартиры' в отчёте по запросам. Денежные значения фильтров передавайте обычными суммами, например --filter 'Cost GREATER_THAN 500': команда переводит их в формат API. Набор полей и операторов хранится в report_presets.json; неподходящие сочетания отклоняются до отправки отчёта.

--json выдаёт параметры, первые 200 строк, общее число строк и путь к полным данным в кэше. --csv ФАЙЛ сохраняет всю полученную таблицу в TSV (разделитель — табуляция). Для анализа большой кампании читайте выгрузку, не делайте выводы только по первым строкам краткого вывода.

Отчёт по запросам формируется в очереди. Команда ждёт до 300 секунд; срок можно изменить через --wait. Если отчёт ещё готовится, повторите ту же команду: она продолжит ожидание. --no-cache обновляет местные данные. Свежесть выгрузки, период, модель атрибуции, валюта и НДС показываются в сводке.

Коды завершения: 0 — данные получены; 1 — ошибка выполнения; 2 — ошибка аргументов или нужно выбрать цели.