# Wordstat Collector

> Сбор семантического ядра (списка поисковых запросов) с реальной частотностью Яндекс 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», либо пользователь даёт фразу-маркер и регион и просит собрать список поисковых запросов с частотность

- Skill: `timurugulava/wordstat-collector` (Agent Skill, multi-file: 12 files)
- Install (CLI): `npx skillmds@latest add timurugulava/wordstat-collector`
- Raw SKILL.md: https://api.skillmd.com/api/skills/timurugulava/wordstat-collector/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Marketing & Growth
- Author: TimurUgulava (https://skillmd.com/u/timurugulava)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/timurugulava/wordstat-collector

---


# 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`.

```bash
pip install httpx python-dotenv rapidfuzz openpyxl
```

## Старт

1. Прочитай `references/03-api-setup.md` и проверь наличие ключа — **только на наличие переменной**, никогда не выводи значение ключа в чат:
   ```bash
   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.
- ❌ Не выдаёт ядро без проверки частотности — иначе оно состоит из фантомов.