wordstat

wordstat выгружает отчёты из интерфейса Яндекс Вордстат через уже открытый и авторизованный Chrome и сохраняет их как типизированные Parquet-датасеты. Исходный browser-use подключается как внешняя локальная editable-зависимость из соседнего каталога ../browser-use.

Установка

cd wordstat-cli
uv venv --python 3.12
source .venv/bin/activate
uv sync --all-groups

Chrome должен быть открыт с доступным CDP endpoint. По умолчанию используется http://127.0.0.1:9222; другой endpoint передаётся через --cdp-url или переменную окружения WORDSTAT_CDP_URL.

Из учётных данных нужен только обычный аккаунт Яндекса — тот, под которым вы уже открываете Вордстат. Ни API-ключей, ни Yandex Cloud, ни биллинга: см. «Почему через браузер, а не через API».

Сбор

wordstat collect "ремонт квартир" --region "Москва" --output-dir ./wordstat-output

Каждый запуск создаёт новый каталог в wordstat-output/runs/. В нём остаются top_popular.parquet, top_related.parquet, dynamics.parquet, regions.parquet и manifest.json. Скачанный CSV — промежуточный артефакт: он парсится, конвертируется и удаляется. Флаг --keep-raw оставляет его рядом как <view>.csv.

Числовые колонки типизируются автоматически: "5 228 679" становится int64, пустая ячейка — null. Проценты и периоды ("01.2024") сознательно остаются строками. Выведенные типы записываются в manifest.json — по ним видно, если Wordstat поменял формат выгрузки.

Команда не вводит учётные данные и прекращает работу, если Wordstat показывает страницу входа. Она собирает только четыре согласованных с MVP представления: популярные и похожие запросы, динамику и регионы. Вкладка «Сайты по запросу» в первый релиз не входит.

Периоды динамики

Вид «Динамика» по умолчанию выгружается за дефолтное окно Wordstat — примерно последние два года. Явный период задаётся парой --date-from/--date-to (формат YYYY-MM-DD) вместе с --granularity:

• monthly — явный период поддержан: не меньше трёх календарных месяцев и не раньше января 2018 года;
• daily — явный период поддержан: окно не длиннее 60 дней, не дальше 60 дней в прошлое и не позже сегодняшнего дня;
• weekly — явный период не поддержан: живой прогон 2026-08-31 подтвердил, что Wordstat молча игнорирует выбранные даты и возвращает дефолтное окно (~2 года). Для weekly выгружается только дефолтное окно Wordstat — не передавайте --date-from/--date-to с этой гранулярностью.

Запрошенный и фактически выгруженный периоды фиксируются в manifest.json (requested_period/actual_period), поэтому расхождение между ними видно по манифесту.

Почему через браузер, а не через API

У Яндекса есть официальный Wordstat API (Yandex Cloud Search API v2), и через него не пришлось бы разбирать вёрстку. wordstat намеренно им не пользуется.

Для работы нужен только обычный аккаунт Яндекса — тот же почтовый ящик, с которым вы заходите в Вордстат из браузера. Больше ничего: ни сервисного аккаунта Yandex Cloud, ни API-ключа, ни привязанной карты и активного биллинга, ни доступа к рекламному кабинету Директа. Chrome уже открыт и авторизован пользователем, wordstat лишь управляет им по CDP и не хранит учётных данных.

Официальный API требует всего перечисленного: заведения сервисного аккаунта, выпуска ключа и включённого платного биллинга в Yandex Cloud.

Низкий порог входа — и есть смысл существования проекта. Из проанализированных публичных проектов (см. docs/REFERENCES.md) на официальном API работает подавляющее большинство — переход туда сделал бы wordstat двадцать первым в переполненной нише и стёр бы единственное отличие. Плата за это решение — зависимость от вёрстки Вордстата; она осознанная и локализована в collector.py, где каждый селектор проверяется на «ровно один элемент» и при несовпадении бросается InterfaceChangedError.

Поэтому миграция на Search API v2 — не улучшение, а смена продукта.

Аналоги

Ландшафт публичных инструментов для Вордстата и место wordstat среди них — в docs/REFERENCES.md.