Analyze Search Demand with Yandex Wordstat

This skill analyzes search demand and keyword statistics through the Yandex Wordstat API, covering top search phrases (up to 2000 results with CSV export), semantic associations, search volume trends over time, and regional demand distribution. It also supports a "missed demand" analysis mode that processes an XLSX export from Yandex Direct advertising campaigns to find search phrases not yet covered by existing campaign semantics.

Its defining discipline is mandatory intent verification: rather than trusting raw query volume, every promising query must be checked with a live WebSearch to determine what the searcher actually wants to buy, since a query can look relevant to a product while actually representing demand for an adjacent accessory, a DIY material, or purely informational research. Its own worked example: "kaolin wool for chimney" looks like chimney-buyer demand but is actually people searching to buy insulation material for a chimney they already own - not a target query for a chimney seller. Red flags for likely non-target queries include phrasing like "for [your product]" (they need an accessory, not the product itself), material/component-focused queries (DIY intent, not buying finished goods), "how to make it yourself" phrasing, and repair/maintenance queries (they already own the item). The skill enforces asking the user for both the target region and the specific business/product being sold before running any analysis, and refuses to proceed until both are answered.

Five CLI scripts drive the analysis: quota.sh checks API connection and remaining quota; top_requests.sh returns top search phrases plus semantically related associations, with CSV export and chunked-reading guidance for handling large exports (500-2000 rows) without flooding output; dynamics.sh tracks search volume trends over daily/weekly/monthly periods; regions_stats.sh and regions_tree.sh/search_region.sh handle regional distribution and region ID lookup. It documents Wordstat's query operators in depth: quotes for exact-phrase-only matching, !word to fix an exact word form (critical for prepositions, which get silently ignored otherwise), minus to exclude unwanted terms, and parentheses for grouping multiple query variants into one combined-demand search - recommending a five-step analysis strategy moving from a broad query to a narrowed exact-phrase match to a cleaned and expanded final query set.

Use this skill when researching search demand, building a semantic core (keyword set) for advertising or SEO, checking query frequency/seasonality/regional demand, or specifically hunting for "missed demand" - phrases a live Yandex Direct campaign isn't yet targeting - by analyzing its XLSX export.

It requires a YANDEX_WORDSTAT_TOKEN configured in config/.env, and operates under hard API limits (10 requests/second, 1000 requests/day) that should be budgeted for when planning large analyses. It should never be used to report raw query volume as "target demand" without the mandatory WebSearch intent-verification step - skipping that step is explicitly treated as a methodology failure, not a shortcut.

Input is a search phrase (with optional Wordstat operators), a target region, and the specific product/service being sold, or an XLSX export from Yandex Direct for missed-demand analysis. Output is a target/non-target-separated report of search queries with impression counts, each non-target exclusion explained (e.g. "searches for insulation material, not the chimney itself"), plus trend and regional-distribution data as needed.

bash scripts/top_requests.sh --phrase "юрист дтп" --limit 500 --csv report.csv

Built on the Yandex Wordstat API, cross-referencing WebSearch for intent verification on every promising query, and supporting Yandex Direct XLSX campaign exports for missed-demand analysis.

SEO specialists, PPC managers, and marketers building keyword sets for Russian-market search advertising who need genuine buyer-intent filtering rather than raw search-volume numbers that include adjacent, DIY, or informational searches.