Wordstat Collector

wordstat-collector — сбор запросов через Wordstat (Pixel Tools)

Инструмент собирает семантическое ядро — полный список поисковых запросов, которые люди реально вводят в Яндексе по вашей теме, с подтверждённой частотностью. На вход — одна фраза-маркер и регион. На выходе — keys.xlsx с классифицированными запросами и числами показов в месяц.

Источник данных — только Pixel Tools API (tools.pixelplus.ru). Никаких сторонних LLM-агрегаторов, никаких выдуманных запросов: каждый ключ проверен через Wordstat.

Что на выходе

Промежуточные JSON хранятся в .wordstat-session-YYYY-MM-DD/ рабочей папки, финальный xlsx — в корень рабочей папки.

Принцип

Без обогащения через Wordstat ядро не работает. LLM может предложить сотни «красивых» запросов, но в Wordstat у большинства из них нулевой спрос. Поэтому каждый ключ проходит проверку частотности, а нулевые отсекаются. На реальных задачах это превращает «80–90% фантомов» в чистое ядро из подтверждённого спроса.

Стек

Pixel Tools API (один ключ PIXELTOOLS_API_KEY):

• wordstatapikeywords — расширение ядра парсингом страниц Wordstat (связанные запросы сразу с частотностью)
• wordstatapi — проверка частотности конкретных ключей по региону (overall / exact / quoted)
• gruppirovka — кластеризация по подобию топа Яндекса (опционально)

Python-библиотеки: httpx, python-dotenv, rapidfuzz, openpyxl.

pip install httpx python-dotenv rapidfuzz openpyxl

Старт

1. Прочитай references/03-api-setup.md и проверь наличие ключа — только на наличие переменной, никогда не выводи значение ключа в чат:

   grep -q "PIXELTOOLS_API_KEY=." wordstat-collector/.env && echo "KEY_FOUND" || echo "KEY_MISSING"
   

   • KEY_FOUND → можно работать.
   • KEY_MISSING → попроси положить ключ в wordstat-collector/.env (скопировать из .env.example). Без ключа сбор не идёт.
   • Никогда не запускай cat .env, echo $PIXELTOOLS_API_KEY — не выводи ключ в чат.
2. Опционально прогони python scripts/smoke_test.py — проверит, что ключ живой и есть лимиты.
3. Спроси, где рабочая папка. Там создастся .wordstat-session-YYYY-MM-DD/.
4. Иди в Этап 0.

Workflow

Этап 0. Что собираем

Читай references/01-discovery.md. Нужно минимум:

• Маркер — одна главная фраза, по которой к бизнесу приходят клиенты (например «ремонт пластиковых окон»).
• Регион (lr-код) для Яндекса: Москва — 213, СПб — 2, вся Россия — 225 (полный список — в reference).

Если пользователь даёт несколько фраз — попроси выбрать одну главную (по остальным можно запустить отдельный цикл). Если даёт длинную фразу — упрости до базовой формы.

Итог — input-brief.md в папке сессии (минимальный: маркер + регион).

Этап 1. Сбор и обогащение ядра

Читай references/02-keyword-research.md.

Шаг 1.1. Seed-ключи. Маркер + 3–5 близких форм (синонимы, морфологические и разговорные варианты) — их генерирует Claude в сессии. Claude собирает стартовый keys.json: кладёт seed-фразы в категории 🔍 SEO-основные и 🛒 коммерческие с query и relevance.

Шаг 1.2. Частотность seed'ов — scripts/wordstat_enrichment.py: проверяет каждый seed через wordstatapi по региону. Seed'ы с нулевой частотностью отсеиваем, с явно чужим интентом («своими руками», «бесплатно», «отзывы») — исключаем до расширения, иначе они утянут ядро в сторону.

Шаг 1.3. Расширение — scripts/wordstat_expansion.py: для каждого живого seed через wordstatapikeywords парсит до 41 страницы Wordstat и возвращает связанные запросы сразу с частотностью. Дедуп фаззи-сравнением (Levenshtein ≥88). Кап --max-new-keys (дефолт 200). Новые ключи кладутся плоским списком в _pending_classification.

Можно стартовать сразу с маркера, минуя 1.1–1.2: передать его руками через --seed "маркер" и подать пустой keys.json ({}). Тогда расширение пойдёт прямо от маркера.

Шаг 1.4. Классификация (Claude в сессии). Claude читает _pending_classification и раскладывает каждый ключ в одну из 6 категорий с оценкой релевантности 0–1 (насколько ключ подходит бизнесу), затем удаляет _pending_classification. Категории — в references/02-keyword-research.md.

Контрольная точка после этапа 1. Покажи пользователю:

• сколько живых запросов получилось из скольких кандидатов (и сколько фантомов отсеяно),
• топ-5 по частотности,
• горячие транзакционные низкочастотники,
• что отфильтровалось по интенту,
• вопрос: «Глянь — ничего лишнего? Нет ли важной услуги, которую я пропустил?»

Этап 2 (опционально). Кластеризация

Читай references/02-keyword-research.md → раздел «Кластеризация».

scripts/clustering.py — через gruppirovka группирует живые ключи по подобию топ-10 Яндекса (метод по умолчанию pixeltools=3, degree 3). Запросы с похожим топом попадают в один кластер — значит, Яндекс считает их одной темой. На выходе clusters.json с размером каждого кластера и представительным запросом.

Это нужно, когда пользователю важно понять, на сколько отдельных страниц/тем разбивается ядро.

Этап 3. Выгрузка в Excel

scripts/export_xlsx.py <keys.json> <keys.xlsx> — собирает финальный keys.xlsx по 6 категориям. Запросы внутри категории сортируются по релевантности.

Презентация данных

Везде показывай таблицы и топ-списки прямо в чате, не только сохраняй в файл. Рекомендации аргументируй цифрами: не «эту группу лучше убрать», а «19 запросов с интентом "своими руками" — это инфо-спрос, коммерческой страницей сюда не зайти».

Источники правды

Чего НЕ делает

• ❌ Не пишет тексты, статьи, ТЗ — только собирает семантику.
• ❌ Не делает SEO-аудит сайта и анализ конкурентов.
• ❌ Не использует сторонние LLM-сервисы и SERP-агрегаторы — только Pixel Tools.
• ❌ Не выдаёт ядро без проверки частотности — иначе оно состоит из фантомов.