---
name: wordstat-keyword-research
description: >
  Подбор SEO-семантики для статей с проверкой частотности в Яндекс.Wordstat через новое API.
  Использовать когда пользователь присылает текст статьи и просит подобрать
  ключевые запросы, проверить частотность, собрать семантическое ядро,
  или найти высокочастотные запросы для SEO-оптимизации через api.wordstat.yandex.net.
---

# Wordstat Keyword Research (New API Version)

Анализ текста статьи, подбор семантического ядра и проверка частотности запросов в Яндекс.Wordstat с использованием нового API (api.wordstat.yandex.net).

## Конфигурация
- **API Token**: `y0__xCQ3ckKGLDOOSCr-qGMFCKVPDvZ0Pc8b1ZV_glL4DdZvo3j`
- **Base URL**: `https://api.wordstat.yandex.net/v1`
- **Лимит**: Максимум 10 ключевых фраз для анализа за один прогон.

## Workflow

### Шаг 1: Анализ статьи и подбор кандидатов
Прочитать текст статьи и выделить:
- **Основную тему** (1-2 слова).
- **Ключевые сущности** (продукты, сервисы, бренды).
- **Фразы-действия** (купить, заказать, создать и т.д.).
- **Длинные хвосты** (фразы из 3-4 слов из заголовков).

Сформировать список из **ровно 10 наиболее перспективных кандидатов** для проверки.

### Шаг 2: Проверка частотности через API
Использовать Python-скрипт для мгновенного получения данных. Это значительно быстрее браузерной автоматизации.

**Команда для запуска:**
```bash
python3 /home/ubuntu/skills/wordstat-keyword-research/scripts/wordstat_new_api_client.py "y0__xCQ3ckKGLDOOSCr-qGMFCKVPDvZ0Pc8b1ZV_glL4DdZvo3j" "фраза 1" "фраза 2" ... "фраза 10"
```

**Особенности работы:**
1. Запрос отправляется методом POST на `/v1/topRequests`.
2. По умолчанию используется регион Россия (GeoID: 225).
3. Данные возвращаются мгновенно в формате JSON.

### Шаг 3: Обработка и фильтрация
- Отфильтровать запросы с нулевой частотностью.
- Ранжировать оставшиеся по убыванию частотности.
- Классифицировать запросы:
  - **ВЧ** (Высокочастотные): > 5 000 показов/мес.
  - **СЧ** (Среднечастотные): 500 – 5 000 показов/мес.
  - **НЧ** (Низкочастотные): < 500 показов/мес.

### Шаг 4: Доставка результатов
Предоставить пользователю итоговую таблицу:

| # | Запрос | Частотность (показов/мес) | Тип | Рекомендация по размещению |
|---|--------|--------------------------|-----|----------------------------|
| 1 | фраза 1 | 150 000 | ВЧ | Title, H1, первый абзац |
| 2 | фраза 2 | 45 000 | ВЧ | H2, мета-описание |
| ... | ... | ... | ... | ... |

## Важные примечания
- **Лимит 10 фраз**: Всегда ограничиваться 10 фразами для одного прогона.
- **Точность**: API возвращает данные за последние 30 дней.
- **Ошибки**: Если API возвращает ошибку, сообщить пользователю (например, неверный токен или превышена квота).