Analyze search demand and keyword statistics using Yandex Wordstat API.
Setup
The skill works via the Wordstat API in Yandex Cloud Search API v2. For authorization, choose IAM via an authorized JSON key of a service account or an API key of a service account. The scripts obtain and refresh the IAM token automatically; the API key is not refreshed automatically.
A single guide for setup, migrating from the old API, and troubleshooting: config/README.md.
⚠️ Operators in dynamics: with --period weekly|monthly only the operator +is supported. Minus words, quotes, groupings, and exact forms work only with --period daily. The skill validates the phrase and reports an error before sending the request. More details — in the README.
Philosophy
- Skepticism to non-target demand — high numbers don't mean quality traffic
- Creative semantic expansion — think like a customer
- Always clarify region — ask user for target region before analysis
- Show operators in reports — include Wordstat operators for verification
- 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 "kaolin wool for chimney" 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:
- What does the person want to BUY? (not just "what are they interested in")
- Will they buy OUR product from this search?
- 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 "for [your product]" — they need ACCESSORY, not your product
- Query about materials/components — they DIY, not buy finished product
- Query has "with your own hands", "how to make" — informational, not buying
- Query about repair/maintenance — they already own it
Examples
| Query | Looks like | Actually | Target? |
|---|---|---|---|
| kaolin wool for chimney | chimney buyer | cotton wool buyer | ❌ NO |
| buy chimney | chimney buyer | chimney buyer | ✅ YES |
| chimney insulation | chimney buyer | insulation DIYer | ❌ NO |
| sandwich chimney price | chimney buyer | chimney buyer | ✅ YES |
| road accident victim | lawyer client | news reader | ❌ NO |
| lawyer after road accident | lawyer client | lawyer client | ✅ YES |
Workflow Update
- Find queries in Wordstat
- WebSearch each promising query to verify intent
- Mark as target ONLY if intent matches the sale
- Report both target AND rejected queries with reasoning
Workflow
STOP! Before any analysis:
-
ASK user about region and WAIT for answer:
"Для какого региона анализировать спрос? - Вся Россия (по умолчанию) - Москва и область - Конкретный город (какой?)"DO NOT CONTINUE until the user responds!
-
ASK about business goal:
"Что именно вы продаёте/рекламируете? Это важно для фильтрации нецелевых запросов."
After getting answers:
- Check connection:
bash scripts/quota.sh - Run analysis using appropriate script
- Verify intent via WebSearch for each promising query
- 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 "lawyer road accident" → "lawyer for road accident", "consultation with a lawyer for road accident". - assoc (
associations) — queries similar by meaning but not necessarily containing the same words, sorted by similarity. These are semantically related searches. Example: phrase "lawyer road accident" → "legal liability", "accident attorney".
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;type.
When --csv is set, stdout shows first 20 rows per section; full data goes to file.
Working with large CSV exports
When --limit is set to a high value (e.g. 500-2000), use CSV export and read the file in chunks:
# Export 2000 results
bash scripts/top_requests.sh --phrase "query" --limit 2000 --csv data.csv
# Read first 50 rows (header + data)
head -n 51 data.csv
# Read rows 51-100
tail -n +52 data.csv | head -50
# Count total rows
wc -l < data.csv
# Filter only associations
grep ";assoc$" data.csv
This approach lets the agent process large datasets without flooding stdout.
dynamics.sh
Get search volume trends over time.
bash scripts/dynamics.sh \
--phrase "юрист дтп" \
--period "monthly" \
--from-date "2025-01-01"
| Param | Required | Default | Values |
|---|---|---|---|
--phrase |
yes | - | text |
--period |
no | monthly | daily, weekly, monthly |
--from-date |
yes | - | YYYY-MM-DD |
--to-date |
no | today | YYYY-MM-DD |
--regions |
no | all | region IDs |
--devices |
no | all | all, desktop, phone, tablet |
regions_stats.sh
Get regional distribution.
bash scripts/regions_stats.sh \
--phrase "юрист дтп" \
--region-type "cities"
| Param | Required | Default | Values |
|---|---|---|---|
--phrase |
yes | - | text |
--region-type |
no | all | cities, regions, all |
--devices |
no | all | all, desktop, phone, tablet |
regions_tree.sh
Show common region IDs.
bash scripts/regions_tree.sh
search_region.sh
Find region ID by name.
bash scripts/search_region.sh --name "Москва"
Wordstat Operators
Quotes "query"
Shows demand ONLY for this exact phrase (no additional words).
"юрист дтп" → "юрист дтп", "юристы дтп"
but NOT "юрист по дтп"
Exclamation !word
Fixes exact word form.
!юрист → "юрист по дтп", "юрист москва"
but NOT "юристы", "юриста"
Combination "!word !word"
Exact phrase + exact forms.
"!юрист !по !дтп" → only "юрист по дтп"
Minus -word
Exclude queries with this word.
юрист дтп -бесплатно -консультация
Grouping (a|b|c)
Multiple variants in one query.
(юрист|адвокат) дтп → combined demand
Stop words
Always fix prepositions with !:
юрист !по дтп ← correct
юрист по дтп ← "по" ignored!
Analysis Strategy
- Broad query:
юрист дтп— see total volume - Narrow with quotes:
"юрист дтп"— exact phrase only - Fix forms:
"!юрист !по !дтп"— exact match - Clean with minus:
юрист дтп -бесплатно -онлайн - Expand: synonyms, related terms, client problems
Popular Region IDs
| Region | ID |
|---|---|
| Russia | 225 |
| Moscow | 213 |
| Moscow and region | 1 |
| Saint Petersburg | 2 |
| Yekaterinburg | 54 |
| Novosibirsk | 65 |
| Kazan | 43 |
Run bash scripts/regions_tree.sh for full list.
Quotas and limits
The current restrictions for Wordstat are given in Yandex Search API documentation.
Example Session
User: Найди запросы для рекламы дымоходов
Claude: Для какого региона анализировать спрос?
И уточните — вы продаёте готовые дымоходы или
материалы для их изготовления/утепления?
User: Москва, продаём готовые сэндвич-дымоходы
Claude: [Запускает анализ для региона 213]
Нашёл запросы. Проверяю интент через веб-поиск...
✅ ЦЕЛЕВЫЕ (покупают дымоходы):
- "дымоход сэндвич купить" — 450 показов
- "дымоход для бани цена" — 380 показов
❌ НЕ ЦЕЛЕВЫЕ (покупают другое):
- "каолиновая вата для дымохода" — ищут утеплитель, не дымоход
- "монтаж дымохода своими руками" — DIY, не покупатели
- "чистка дымохода" — уже владеют, сервисный запрос
Key Points
- ALWAYS ask for the region and wait for an answer
- ALWAYS clarify what exactly the client is selling
- ALWAYS check the intent via WebSearch
- Split the report into target/non-target with explanation
Advanced scenarios
Search for missed demand
Analysis of a Yandex Direct advertising campaign to find phrases not covered by the current semantics. Requirements: XLSX export from Yandex Direct (sheet "Тексты"). Details: MISSED_DEMAND.md