Список клиентских логинов агентства с валютой и остатком средств.

Отсюда берётся client_login для остальных тулов. Вызывается без заголовка Client-Login — это агентский метод.

Кампании клиента: id, имя, тип, статус. Нужен для маппинга CampaignId → имя и чтобы понять, какие кампании вообще стоит тянуть в отчёт.

Коды регионов Директа по названию и обратная проверка готовых кодов.

Вызывать всегда, когда в geo_ids (direct_wordstat) или RegionIds (direct_campaign_setup) уходит регион: Директ коды НЕ проверяет. Неверный код не вызовет ошибку — он молча даст данные и показы не по тому региону, и заметно это станет только по статистике.

query: часть названия, например "Москва", "Ростов", "Татарстан". Регистр и «ё» не важны. Совпадения возвращаются с путём до корня (path), потому что названия неуникальны: «Москва» — это и город 213, и «Москва и область» 1. ids: коды для обратной проверки. Вернёт названия, а отсутствующие в справочнике коды — отдельным списком unknown_ids. client_login: нужен только агентскому токену — Директ требует заголовок Client-Login на клиентских методах. Подойдёт любой логин из direct_list_clients. limit: сколько совпадений вернуть, 1–200.

Нужен хотя бы один из query / ids: справочник целиком тул не отдаёт. Загружается он один раз на процесс, повторные вызовы баллов не тратят.

Настройки кабинета, которых нет в отчётах: корректировки ставок, условия ретаргетинга, общие наборы минус-фраз.

Нужен при разборе «почему кампания не работает» и перед выводами по срезам отчёта. Reports API покажет статистику по Device, Gender, Age, но не покажет выставленный коэффициент, а это разные диагнозы: «нет мобильных конверсий» и «на мобильные стоит −100%».

sections: какие секции читать. Доступны bid_modifiers, retargeting_lists, negative_keyword_sets. Пусто — все три. campaign_ids: для каких кампаний смотреть корректировки. Пусто — сервер сам возьмёт неархивные кампании клиента, но не более 50; если их больше, в ответе будет truncated и число пропущенных.

Секции независимы: ошибка в одной приходит полем error внутри неё, а остальные возвращаются как есть. Корректировки перемножаются между собой — как их читать, описано в direct://kb/targeting-adjustments.

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

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

campaign_ids / ad_group_ids / ad_ids: чем сузить выборку. Пусто — все объявления клиента. include_archived: включить архивные, по умолчанию нет. limit: сколько объявлений забрать за вызов, 1–10000.

В ответе landing_pages — сводка по уникальным URL с числом объявлений, кампаниями и разобранными UTM; domains — домены, на которые идёт реклама. Запрашивается блок TextAd: у графических, видео и смарт-объявлений href придёт пустым, их число видно в ads_without_href.

Выгрузить статистику через Reports API. Пишет TSV на диск, возвращает путь + итоги + первые строки.

client_login: клиентский логин (см. direct_list_clients) date_from / date_to: YYYY-MM-DD. Статистика доступна за 3 последних года. fields: колонки отчёта, например ["Date","CampaignName","Impressions","Clicks","Cost"]. Набор допустимых полей зависит от report_type. Внимание: поля разных классов — сегмент (даёт группировку), метрика, атрибут, фильтр (используется только в filters и в отчёт не выводится, напр. Keyword). report_type: CUSTOM_REPORT (самый общий, по умолчанию) | ACCOUNT_PERFORMANCE_REPORT | CAMPAIGN_PERFORMANCE_REPORT | ADGROUP_PERFORMANCE_REPORT | AD_PERFORMANCE_REPORT | CRITERIA_PERFORMANCE_REPORT | SEARCH_QUERY_PERFORMANCE_REPORT | REACH_AND_FREQUENCY_PERFORMANCE_REPORT goals: ID целей Метрики, например ["12345678"]. Без них не будет Conversions. attribution_models: FC | LC | LSC | LYDC | FCCD | LSCCD | LYDCCD | AUTO. Работает только вместе с goals; по умолчанию LSC. Несколько моделей → данные выводятся по каждой отдельно. filters: [{"Field":"CampaignId","Operator":"IN","Values":["123","456"]}] order_by: [{"Field":"Cost","SortOrder":"DESCENDING"}] limit: ограничение строк. Требует сортировки — если не задана, подставим по первому полю. include_vat: суммы с НДС (True) или без (False).

Постранично прочитать уже выгруженный отчёт по пути из direct_report. Без повторного обращения к API и без расхода баллов.

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

Нужен на сборке семантики (что брать в кампанию, где спрос есть, а где нет), на разборе «мало показов» и когда в отчёте надо отделить падение спроса от падения кампании.

phrases: до 50 фраз за вызов. Операторы Директа работают: «!» фиксирует словоформу, кавычки ограничивают фразу, «+» держит стоп-слово. geo_ids: регионы Директа, например [225] — Россия, [213] — Москва. Пусто — без ограничения по региону. Директ коды не проверяет: неверный код молча вернёт данные не по тому региону. min_shows: отбросить подсказки с частотностью ниже порога. top: сколько подсказок каждого вида показать в ответе, 1–100.

client_login не нужен: данные Вордстата общие для всех кабинетов. Значение Shows — спрос в поиске за месяц, а не прогноз показов кампании. В песочнице метод недоступен.