/yandex-wordstat

name: yandex-wordstat
description: |
  Анализ поискового спроса через Yandex Wordstat API.
  Используй когда нужно: исследовать спрос, семантическое ядро,
  частотность запросов, сезонность или региональный спрос.
  Топ до 2000 запросов, ассоциации, динамика, экспорт CSV.
  Поиск упущенного спроса: анализ XLSX-выгрузки из Яндекс Директ,
  сегментация фраз, расширение семантики, сравнение OR-запросов.
  Triggers: упущенный спрос.

yandex-wordstat

Analyze search demand and keyword statistics using Yandex Wordstat API.

Настройка

Скилл работает через Wordstat API в Yandex Cloud Search API v2. Для авторизации выберите IAM через авторизованный JSON-ключ сервисного аккаунта или API-ключ сервисного аккаунта. IAM-токен скрипты получают и обновляют автоматически; API-ключ автоматически не обновляется.

Единая инструкция по настройке, переходу со старого API и устранению ошибок: [config/README.md](config/README.md).

⚠️ **Операторы в `dynamics`**: при `--period weekly|monthly` поддерживается только оператор `+`. Минус-слова, кавычки, группировки и точные формы работают только при `--period daily`. Скилл проверяет фразу и сообщает об ошибке до отправки запроса. Подробнее — в README.

Philosophy

1. **Skepticism to non-target demand** — high numbers don't mean quality traffic 2. **Creative semantic expansion** — think like a customer 3. **Always clarify region** — ask user for target region before analysis 4. **Show operators in reports** — include Wordstat operators for verification 5. **VERIFY INTENT via web search** — always check what people actually want to buy

CRITICAL: Intent Verification

**Before marking ANY query as "target", verify intent via WebSearch!**

The Problem

Query "каолиновая вата для дымохода" looks relevant for chimney seller, but:

• People search this to BUY COTTON WOOL, not chimneys
• They already HAVE a chimney and need insulation material
• This is NOT a target query for chimney sales!

Verification Process

For every promising query, ASK YOURSELF: 1. **What does the person want to BUY?** (not just "what are they interested in") 2. **Will they buy OUR product from this search?** 3. **Or are they looking for something adjacent/complementary?**

MANDATORY: Use WebSearch

**Always run WebSearch** to check:

WebSearch: "каолиновая вата для дымохода" что ищут покупатели

Look at search results:

• What products are shown?
• What questions do people ask?
• Is this informational or transactional intent?

Red Flags (likely NOT target)

• Query contains "для [вашего продукта]" — they need ACCESSORY, not your product
• Query about materials/components — they DIY, not buy finished product
• Query has "своими руками", "как сделать" — informational, not buying
• Query about repair/maintenance — they already own it

Examples

| Query | Looks like | Actually | Target? | |-------|------------|----------|---------| | каолиновая вата для дымохода | chimney buyer | cotton wool buyer | ❌ NO | | дымоход купить | chimney buyer | chimney buyer | ✅ YES | | утепление дымохода | chimney buyer | insulation DIYer | ❌ NO | | дымоход сэндвич цена | chimney buyer | chimney buyer | ✅ YES | | потерпевший дтп | lawyer client | news reader | ❌ NO | | юрист после дтп | lawyer client | lawyer client | ✅ YES |

Workflow Update

1. Find queries in Wordstat 2. **WebSearch each promising query to verify intent** 3. Mark as target ONLY if intent matches the sale 4. Report both target AND rejected queries with reasoning

Workflow

STOP! Before any analysis:

1. **ASK user about region and WAIT for answer:**

   "Для какого региона анализировать спрос?
   - Вся Россия (по умолчанию)
   - Москва и область
   - Конкретный город (какой?)"

**НЕ ПРОДОЛЖАЙ пока пользователь не ответит!**

2. **ASK about business goal:**

   "Что именно вы продаёте/рекламируете?
   Это важно для фильтрации нецелевых запросов."

After getting answers:

3. **Check connection**: `bash scripts/quota.sh` 4. **Run analysis** using appropriate script 5. **Verify intent via WebSearch** for each promising query 6. **Present results** with target/non-target separation

Scripts

quota.sh

Check API connection.

bash scripts/quota.sh

top_requests.sh

Get top search phrases. Supports up to 2000 results and CSV export.

bash scripts/top_requests.sh \
  --phrase "юрист дтп" \
  --regions "213" \
  --devices "all"

# Extended: 500 results exported to CSV
bash scripts/top_requests.sh \
  --phrase "юрист дтп" \
  --limit 500 \
  --csv report.csv

# Max results with comma separator
bash scripts/top_requests.sh \
  --phrase "юрист дтп" \
  --limit 2000 \
  --csv full_report.csv \
  --sep ","

| Param | Required | Default | Values | |-------|----------|---------|--------| | `--phrase` | yes | - | text with operators | | `--regions` | no | all | comma-separated IDs | | `--devices` | no | all | all, desktop, phone, tablet | | `--limit` | no | 50 (set by the skill) | 1-2000 (maps to API numPhrases) | | `--csv` | no | - | path to output CSV file | | `--sep` | no | ; | CSV separator (; for RU Excel) |

Result types: Top Requests vs Associations

The output contains two sections (both in stdout and CSV):

• **top** (`topRequests`) — queries that **contain the words** from your phrase, sorted by frequency. These are direct variations of the search query. Example: phrase "юрист дтп" → "юрист по дтп", "консультация юриста по дтп".
• **assoc** (`associations`) — queries **similar by meaning** but not necessarily containing the same words, sorted by similarity. These are semantically related searches. Example: phrase "юрист дтп" → "юридическая ответственность", "адвокат аварии".

**For analysis:** `top` results are your primary keyword pool. `assoc` results are useful for semantic expansion but often contain noise — always verify intent before including them.

CSV export details

CSV format: UTF-8 with BOM, columns: `n;phrase;impressions;