---
name: seo-demand-analytics
description: >
  SEO-аналитика спроса и видимости для регионального интернет-магазина или сайта в Яндексе.
  Запускай этот скилл когда нужно:
  - собрать топ-100 запросов по нише в регионе через Яндекс.Wordstat
  - сопоставить запросы с позициями и кликами из Яндекс.Вебмастера
  - получить страницы с органическим трафиком из Яндекс.Метрики
  - найти точки роста (высокий спрос, нет видимости) и быстрые победы
  - сформировать HTML-дашборд, Markdown-отчёт и AI-инсайты
  Триггеры: аналитика спроса, SEO по региону, корреляция Wordstat, видимость в поиске,
  органический трафик по нише, топ запросов региона, SEO-отчёт Яндекс, анализ видимости сайта,
  где теряем трафик, какие запросы не в топе.
---

# seo-demand-analytics

Пайплайн из 7 этапов: сбор данных → корреляция → отчёт → AI-анализ.

---

## Параметры запуска

Запросить у пользователя перед стартом:

| Параметр | Описание | Пример |
|----------|----------|--------|
| `niche` | Ниша / категория | смартфоны |
| `region` | Название региона | Кемеровская область |
| `geo_id` | GeoID Яндекса | 11316 |
| `domain` | Домен/поддомен | kemerovo.2droida.ru |
| `metrika_id` | ID счётчика Метрики | 45533538 |
| `period_days` | Период анализа (дней) | 30 |

GeoID → см. `references/geo_ids.md`. Для неизвестных регионов — через Wordstat UI (URL: `?geo=XXXXX`).

**OAuth-токен Яндекса** нужен для Wordstat и Метрики. Получить: https://oauth.yandex.ru → приложение с правами `wordstat:read` и `metrika:read`. Хранить в переменной окружения `YANDEX_TOKEN` или в `config.json`.

---

## Пайплайн

### Этап 1 — Инициализация
```bash
python3 scripts/init_config.py
```
Сохраняет `config.json`. При повторном запуске предлагает использовать существующий.

### Этап 2 — Сбор спроса (Wordstat)
```bash
python3 scripts/collect_wordstat.py
```
Топ-100 коммерческих запросов по нише + региону. Сохраняет `wordstat_data.json`.
> API Wordstat возвращает данные за предыдущий полный календарный месяц — это норма.

### Этап 3 — Выгрузка Вебмастера (вручную)
API Яндекс.Вебмастера v4 не отдаёт числовые показатели — выгружаем CSV вручную:
1. Вебмастер → сайт → Эффективность → Статистика запросов → Популярные запросы
2. Шестерёнка колонок → добавить «Ср. позиция показа»
3. Кнопка «CSV» → сохранить как `webmaster_data.csv` в рабочую папку

```bash
python3 scripts/collect_webmaster.py   # парсит CSV, нормализует структуру
```

### Этап 4 — Сбор трафика (Метрика)
```bash
python3 scripts/collect_metrika.py
```
Все страницы с органическим трафиком за период. Сохраняет `metrika_data.json`.

### Этап 5 — Корреляция
```bash
python3 scripts/analyze_correlation.py
```
Сопоставляет Wordstat ↔ Вебмастер. Присваивает статус:
- **ТОП-3** — позиция 1–3
- **ТОП-10** — позиция 4–10
- **ТОП-50** — позиция 11–50
- **Слабая видимость** — позиция 51+
- **Не видим** — нет в Вебмастере

Сохраняет `final_correlation.json`.

### Этап 6 — Генерация отчётов
```bash
python3 scripts/generate_reports.py
```
Создаёт:
- `dashboard.html` — интерактивный дашборд с карточками, сортировкой и фильтром
- `report.md` — текстовый отчёт со статистикой и точками роста
- Копирует файлы в `OUTPUTS/` рабочей папки

### Этап 7 — AI-интерпретация (Claude)
После Этапа 6 выполнить анализ данных:

1. Загрузить `final_correlation.json`
2. Сгенерировать **5–7 инсайтов**:
   - Какой % спроса покрывается хотя бы ТОП-50
   - Топ-3 самых дорогих "дыры" (высокочастотные запросы без видимости)
   - Запросы с лучшим потенциалом быстрого роста (ТОП-10→ТОП-3)
   - Темы, где сайт сильнее конкурентов по кликам vs позиции
   - Аномалии: высокая позиция + мало кликов (CTR-проблема)
3. Сформулировать **3–5 гипотез роста** с приоритетом (Высокий/Средний/Низкий) и ожидаемым эффектом
4. Добавить инсайты в раздел `## Инсайты и гипотезы роста` файла `report.md`
5. Сохранить обновлённый `report.md` в `OUTPUTS/`

---

## Файлы и результаты

| Файл | Откуда |
|------|--------|
| `config.json` | Этап 1 |
| `wordstat_data.json` | Этап 2 |
| `webmaster_data.csv` | Этап 3 (вручную) |
| `metrika_data.json` | Этап 4 |
| `final_correlation.json` | Этап 5 |
| `dashboard.html` | Этап 6 |
| `report.md` | Этапы 6–7 |

---

## Ограничения API

| API | Ограничение | Обходное решение |
|-----|-------------|------------------|
| Wordstat | Данные за прошлый месяц | Учитывается в отчёте |
| Вебмастер v4 | Позиции/клики недоступны через API | Ручная выгрузка CSV |
| Метрика | Фразы + URL-фильтр = `sensitive_data` | Страницы и фразы — раздельно |

Подробности → `references/api_notes.md`

---

## Установка зависимостей

```bash
pip install requests python-docx google-api-python-client google-auth-httplib2 google-auth-oauthlib --break-system-packages
```