yandex-wordstat

yandex-wordstat

Yandex Wordstat API を使用して検索需要とキーワード統計を分析します。

設定

このスキルは、Yandex Cloud Search API v2 の Wordstat API を使用します。認証には、認証済みのサービスアカウント JSON キーを使った IAM、またはサービスアカウントの API キーを選択してください。スクリプトは IAM トークンを自動的に取得・更新します。API キーは自動更新されません。

設定、旧 API からの移行、エラーの解決に関する共通の手順については、config/README.md を参照してください。

⚠️ dynamics の演算子：--period weekly|monthly の場合、使用できる演算子は + のみです。除外キーワード、引用符、グループ化、完全一致形式は --period daily の場合にのみ機能します。このスキルはリクエストの送信前にフレーズを検証し、エラーがあれば通知します。詳細は README を参照してください。

基本方針

1. ターゲット外の需要を疑う — 数値が大きくても、質の高いトラフィックとは限りません
2. 柔軟に意味を広げる — 顧客の立場で考えます
3. 必ず地域を確認する — 分析前に、対象地域をユーザーに尋ねます
4. レポートに演算子を表示する — 検証できるよう、Wordstat の演算子を含めます
5. WebSearch で意図を確認する — 人々が実際に何を購入したいのか、必ず確認します

重要：検索意図の確認

クエリを「ターゲット」と判定する前に、必ず WebSearch で意図を確認してください！

問題点

「дымоход用のкаолиновая вата」というクエリは煙突の販売業者に関連があるように見えますが、実際には次のような場合があります。

• 人々が検索しているのは煙突ではなく、断熱材のウールを購入することです
• すでに煙突を所有しており、必要なのは断熱材です
• これは煙突販売のターゲットクエリではありません！

確認手順

有望なクエリごとに、次の点を自問してください。

1. その人は何を購入したいのか？（単に「何に興味があるか」ではありません）
2. この検索から自社の商品を購入する可能性はあるか？
3. それとも、関連商品や補完商品を探しているのか？

必須：WebSearch を使用する

次の点を確認するため、必ず WebSearch を実行してください。

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

検索結果を確認します。

• どのような商品が表示されていますか？
• どのような質問がされていますか？
• 情報収集目的ですか、それとも購入目的ですか？

注意すべき兆候（ターゲットではない可能性が高い）

• クエリに「для [вашего продукта]」が含まれている — 自社の商品ではなく、付属品を必要としています
• 素材や部品についてのクエリ — 完成品を購入するのではなく、自分で作ろうとしています
• クエリに「своими руками」や「как сделать」が含まれている — 購入目的ではなく、情報収集目的です
• 修理やメンテナンスについてのクエリ — すでに商品を所有しています

例

クエリ	見た目の意図	実際の意図	ターゲット？
каолиновая вата для дымохода	煙突の購入者	ウールの購入者	❌ いいえ
дымоход купить	煙突の購入者	煙突の購入者	✅ はい
утепление дымохода	煙突の購入者	断熱を自分で行う人	❌ いいえ
дымоход сэндвич цена	煙突の購入者	煙突の購入者	✅ はい
потерпевший дтп	弁護士の依頼人	ニュースの読者	❌ いいえ
юрист после дтп	弁護士の依頼人	弁護士の依頼人	✅ はい

ワークフローの更新

1. Wordstat でクエリを見つけます
2. 有望なクエリごとに WebSearch を行い、意図を確認します
3. 意図が販売内容と一致する場合のみ、ターゲットと判定します
4. ターゲットのクエリと、除外したクエリの両方を、理由とともに報告します

ワークフロー

停止！分析を始める前に：

1. ユーザーに地域を尋ね、回答を待ちます。

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

   ユーザーが回答するまで続行しないでください！

2. 事業の目標を尋ねます。

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

回答を得た後：

3. 接続を確認します：bash scripts/quota.sh
4. 適切なスクリプトを使って分析を実行します
5. 有望なクエリごとにWebSearch で意図を確認します
6. ターゲットとターゲット外を分けて結果を提示します

スクリプト

quota.sh

API 接続を確認します。

bash scripts/quota.sh

top_requests.sh

人気の検索フレーズを取得します。最大 2000 件の結果と CSV エクスポートに対応しています。

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 ","

パラメーター	必須	デフォルト	値
--phrase	はい	-	演算子を含むテキスト
--regions	いいえ	all	カンマ区切りの ID
--devices	いいえ	all	all、desktop、phone、tablet
--limit	いいえ	50（スキルで設定）	1-2000（API の numPhrases に対応）
--csv	いいえ	-	出力する CSV ファイルのパス
--sep	いいえ	;	CSV の区切り文字（ロシア版 Excel 用は ;）

結果の種類：トップリクエストと関連語

出力には 2 つのセクションが含まれます（標準出力と CSV の両方）。

• top（topRequests）— フレーズに含まれる単語を含む検索語句を頻度順に表示します。検索クエリの直接的なバリエーションです。例：フレーズ「юрист дтп」→「юрист по дтп」、「консультация юриста по дтп」。
• assoc（associations）— 必ずしも同じ単語を含まない、意味が類似した検索語句を類似度順に表示します。意味的に関連する検索語句です。例：フレーズ「юрист дтп」→「юридическая ответственность」、「адвокат аварии」。

分析にあたって： top の結果は、主要なキーワード候補です。assoc の結果は意味的な拡張に役立ちますが、ノイズが含まれることも多いため、含める前に必ず検索意図を確認してください。

CSV エクスポートの詳細

CSV 形式：UTF-8（BOM 付き）、列：n;phrase;impressions;type。 --csv を設定すると、標準出力には各セクションの先頭 20 行が表示され、全データはファイルに出力されます。

大容量の CSV エクスポートを扱う

--limit に大きな値（例：500-2000）を設定した場合は、CSV にエクスポートし、ファイルを分割して読み込んでください。

# 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

この方法なら、標準出力に大量のデータを流すことなく、エージェントが大規模なデータセットを処理できます。

dynamics.sh

検索ボリュームの推移を時系列で取得します。

bash scripts/dynamics.sh \
  --phrase "юрист дтп" \
  --period "monthly" \
  --from-date "2025-01-01"

パラメーター	必須	デフォルト	値
--phrase	はい	-	テキスト
--period	いいえ	monthly	daily、weekly、monthly
--from-date	はい	-	YYYY-MM-DD
--to-date	いいえ	today	YYYY-MM-DD
--regions	いいえ	all	地域 ID
--devices	いいえ	all	all、desktop、phone、tablet

regions_stats.sh

地域ごとの分布を取得します。

bash scripts/regions_stats.sh \
  --phrase "юрист дтп" \
  --region-type "cities"

パラメーター	必須	デフォルト	値
--phrase	はい	-	テキスト
--region-type	いいえ	all	cities、regions、all
--devices	いいえ	all	all、desktop、phone、tablet

regions_tree.sh

よく使われる地域 ID を表示します。

bash scripts/regions_tree.sh

search_region.sh

名前から地域 ID を検索します。

bash scripts/search_region.sh --name "Москва"

Wordstat の演算子

引用符 "query"

この正確なフレーズのみの需要を表示します（追加の単語は含まれません）。

"юрист дтп" → "юрист дтп", "юристы дтп"
             but NOT "юрист по дтп"

感嘆符 !word

単語の形を固定します。

!юрист → "юрист по дтп", "юрист москва"
         but NOT "юристы", "юриста"

組み合わせ "!word !word"

正確なフレーズと単語の正確な形を指定します。

"!юрист !по !дтп" → only "юрист по дтп"

マイナス -word

この単語を含む検索語句を除外します。

юрист дтп -бесплатно -консультация

グループ化 (a|b|c)

1 つのクエリで複数の候補を指定します。

(юрист|адвокат) дтп → combined demand

ストップワード

前置詞には必ず ! を付けて固定してください：

юрист !по дтп    ← correct
юрист по дтп     ← "по" ignored!

分析戦略

1. 幅広いクエリ：юрист дтп — 全体の検索ボリュームを確認
2. 引用符で絞り込む："юрист дтп" — 正確なフレーズのみ
3. 語形を固定する："!юрист !по !дтп" — 完全一致
4. マイナスで除外する：юрист дтп -бесплатно -онлайн
5. 拡張する：同義語、関連語、クライアントの課題

人気の地域 ID

地域	ID
ロシア	225
モスクワ	213
モスクワと州	1
サンクトペテルブルク	2
エカテリンブルク	54
ノヴォシビルスク	65
カザン	43

一覧全体を確認するには、bash scripts/regions_tree.sh を実行してください。

割り当てと制限

Wordstat の最新の制限については、Yandex Search API のドキュメントをご覧ください。

セッション例

User: Найди запросы для рекламы дымоходов

Claude: Для какого региона анализировать спрос?
        И уточните — вы продаёте готовые дымоходы или
        материалы для их изготовления/утепления?

User: Москва, продаём готовые сэндвич-дымоходы

Claude: [Запускает анализ для региона 213]

        Нашёл запросы. Проверяю интент через веб-поиск...

        ✅ ЦЕЛЕВЫЕ (покупают дымоходы):
        - "дымоход сэндвич купить" — 450 показов
        - "дымоход для бани цена" — 380 показов

        ❌ НЕ ЦЕЛЕВЫЕ (покупают другое):
        - "каолиновая вата для дымохода" — ищут утеплитель, не дымоход
        - "монтаж дымохода своими руками" — DIY, не покупатели
        - "чистка дымохода" — уже владеют, сервисный запрос

重要なポイント

1. 必ず地域を尋ね、回答を待ってください
2. クライアントが何を販売しているのか、必ず確認してください
3. WebSearch で必ず検索意図を確認してください
4. レポートを対象／対象外に分け、説明を添えてください

応用シナリオ

Поиск упущенного спроса

Анализ рекламной кампании Яндекс Директ для нахождения фраз, не покрытых текущей семантикой. Требования: XLSX-выгрузка из Яндекс Директ (лист «Тексты»). Подробнее: MISSED_DEMAND.md