Надежный сборщик Yandex Wordstat
Yandex Wordstat Collector
CLI-сборщик частот Yandex Wordstat с восстановлением после сбоев: null-результат никогда не считается завершенными данными
Средний риск
Средний уровень ставим, когда инструмент запускает код, ходит в сеть или читает файлы проекта. Перед установкой посмотрите, что именно он делает.
Почему такой уровень
- Каждый запрос тратит платный лимит Yandex Search API с биллингом на сервисном аккаунте
- Ключ API с правом search-api.webSearch.user хранится в переменной окружения или файле на диске
Установка
Ручная установка
npm test && node ./bin/wordstat.js --phrases "куда вложить деньги,робо эдвайзер" --regions 225,213 --out-dir docs/analysis/wordstat --max-requests 20Установка из исходников, ключ читается из WORDSTAT_API_KEY, YANDEX_SEARCH_API_KEY или файла в ~/.config/codex-tools/.
Это чужой код. Посмотрите файлы в репозитории перед установкой.
Что делает
Инструмент собирает частотность фраз через инструмент topRequests официального Yandex Search API с повторами при 429 и 5xx с задержкой и джиттером. Состояние сбора хранится в wordstat-state-v2.json тремя корзинами: завершено, не завершено, ошибка, плюс учет квоты. Ключевая идея: результат с totalCount: null никогда не считается завершенными данными, а помечается как подлежащий повтору или исчерпанный после нескольких попыток. Прерванный сбор можно продолжить командой --retry-incomplete. В комплекте Codex-скилл skills/wordstat, который при SEO-запросе дополнительно строит словарь из 25 существительных, прилагательных и глаголов, 25 примеров фраз и 10 приоритетных рекомендаций для связки заголовок плюс подзаголовок.
Для кого. Для тех, кто собирает большие списки ключевых слов из Wordstat и не хочет получить на выходе тихо неполные данные.
Подходит, если
- Нужен сбор частот по большому списку фраз с возможностью продолжить после сбоя
- Важно отличать честный ноль от временной ошибки API (null-результат)
- Нужен Codex-скилл, который сам собирает частоты и строит SEO-словарь по запросу
Не подходит, если
- Нужны данные по динамике или сезонности (dynamics), пока не реализовано, только в roadmap
- Нет сервисного аккаунта Yandex Cloud с ролью search-api.webSearch.user и активным биллингом
Пример запроса к агенту
Собери частотность Wordstat для фраз купить окна и установка окон под ключ в регионах Москва и Санкт-ПетербургОграничения
Требует не просто любой ключ AI Studio, а сервисный аккаунт с ролью search-api.webSearch.user на каталоге и ключ со скоупом yc.search-api.execute при активном биллинге. Поддержки regions и dynamics пока нет, MCP-обертки и публикации в npm тоже нет. Wordstat принимает не больше 100 запросов в час.
Как отключить. Удалите склонированный репозиторий и, если ставили Codex-скилл, папку ~/.codex/skills/wordstat.
Проверка безопасности
- Каждый запрос тратит платный лимит Yandex Search API с биллингом на сервисном аккаунте
- Ключ API с правом search-api.webSearch.user хранится в переменной окружения или файле на диске
Коротко о README
Двуязычное README описывает философию инструмента (не просто получить данные, а знать, действительно ли они собраны), возможности: retry с backoff, resumable state, quota ledger, null-result policy, atomic writes. Показаны быстрый старт, настройка сервисного аккаунта Yandex Cloud с точными ролями и скоупами, CLI-флаги надежности, формат состояния и summary, а также встроенный Codex-скилл с субагентной оркестрацией.
Частые вопросы
Что делать, если часть фраз упала с ошибкой?
Запустить node ./bin/wordstat.js --retry-incomplete --out-dir docs/analysis/wordstat, инструмент подхватит только незавершенные и ошибочные пары фраза-регион из сохраненного состояния.
Почему null-результат не считается готовыми данными?
Автор объясняет: если частотность влияет на SEO-страницы или продуктовые ставки, строка с totalCount: null не прогресс, а риск, поэтому такие результаты попадают в отдельную корзину на повтор.
Похожие
Скиллы DataLens
DataLens Skills
Официальные скиллы DataLens (Яндекс) для Claude Code, Codex и OpenCode: SDK, HTML-отчеты и разбор прав RLS
MCP Яндекс Метрики со всеми 108 методами API
Yandex Metrika MCP Server
MCP-сервер Яндекс Метрики, порожденный из спеки API: 108 методов, по умолчанию 10 инструментов, прозрачные фильтры и метаданные ответа
Открытый MCP-сервер и набор агентских скиллов для SEO: keyword research, конкуренты, обратные ссылки и аудит сайта по данным DataForSEO
Плагин Claude Code для SEO-аудита: технический SEO, E-E-A-T, schema, локальный и AI-поиск силами параллельных агентов