wordstat-collector

name

wordstat-collector

description

Сбор семантического ядра (списка поисковых запросов) с реальной частотностью Яндекс Wordstat через Pixel Tools API. По одной фразе-маркеру и региону разворачивает ядро: парсит связанные запросы Wordstat, проверяет частотность каждого (overall / exact / quoted) по нужному региону, отсекает «фантомы» (запросы без реального спроса), классифицирует ключи по 6 категориям (коммерческие, информационные, long-tail, SEO-основные, LSI, верхнего уровня), опционально кластеризует по подобию топа Яндекса и выгружает результат в keys.xlsx. Стек: Pixel Tools API (wordstatapikeywords, wordstatapi, gruppirovka) + Python (httpx, openpyxl). Нужен один ключ PIXELTOOLS_API_KEY. Без внешних LLM-сервисов. Use when «собери семантику», «собрать ядро запросов», «частотность Wordstat», «расширь ядро по маркеру», «собери ключевые слова через Pixel Tools», «выгрузи запросы в Excel», «кластеризация запросов по топу», «wordstat-collector», либо пользователь даёт фразу-маркер и регион и просит собрать список поисковых запросов с частотностью. Do NOT use for написания текстов и статей, SEO-аудита готового сайта, анализа конкурентов, генерации технических заданий — этот скилл только собирает и выгружает семантику.

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

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

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

Что на выходе

Файл	Что внутри
keys.xlsx	Семантическое ядро по 6 категориям (🛒 коммерческие, 📖 информационные, 🎯 long-tail, 🔍 SEO-основные, 🧠 LSI, 🔬 верхнего уровня), у каждого ключа — частотность и оценка релевантности 0-1
clusters.json (опционально)	Кластеры запросов по подобию топа Яндекса — какие запросы поисковик считает одной темой

Промежуточные 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 запросов с интентом "своими руками" — это инфо-спрос, коммерческой страницей сюда не зайти».

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

Путь	Что внутри
references/01-discovery.md	Что спросить у пользователя: маркер + регион. Справочник lr-кодов
references/02-keyword-research.md	Полная логика сбора: seed → enrichment → expansion → 6 категорий → кластеризация
references/03-api-setup.md	Pixel Tools setup, .env, проверка ключа, лимиты

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

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