yandex-search-api

yandex-search-api

Yandex Cloud Search API v2 を使って Yandex の SERP を解析します（同期・非同期）。

インフォコンテキスト（Smart Snippets）

Search API はリンクと数文のスニペットだけでなく、見つかったページから約 500 トークン分の抜粋も返します。抜粋は検索クエリに関連しており、ドキュメントからの引用も含まれます。回答に必要な情報がそろうため、ページを自分で処理する必要はありません。

この機能をエージェントに導入する理由はここにあります。リンクの一覧だけでなく、検索 1 回で回答できます。

デフォルトで有効になっているため、別のスクリプトは不要です。

bash scripts/web_search_sync.sh --query "как считается НДС для УСН в 2026" --region-id 225

テキストは回答に出力されません。cache/results/<hash>.md に保存され、標準出力にはドキュメントごとに 1 行のインデックスが出力されます。続けてパックをファイルとして読み込みます。資料全体が必要なら全体を、1 つの情報源だけでよければ grep で読み込みます。すでにパックにあるテキストを取得するために同じ語句を再検索するのは、費用の無駄です。

コマンドの選択に影響する制限が 3 つあります。

• 同期モードのみです。 web_search_async.sh はインフォコンテキストを返しません。
• SEARCH_TYPE_RU のみです。 ほかの検索タイプでは、検索は実行されますが、インフォコンテキストは返されず、その旨が通知されます。
• ドキュメントは最大 20 件です。 それ以上は指定できません。--results に 20 を超える値を指定すると、API は 20 件ではなく半分の件数を同じ料金で返します。スキル側で自動的に上限を設定します。
• 料金が高くなります。 通常の同期検索は 1,000 クエリあたり 488 ₽ ですが、こちらは 1,000 クエリあたり 1,500 ₽ です。

順位とドメインだけが必要な場合は、--no-snippets を指定するか、設定で search.smart_snippets.enabled: false にします。

詳細、回答形式、デバッグ、エラーの調査については、 references/SMART_SNIPPETS.md を参照してください。

設定

利用するには、search-api.webSearch.user ロールを持つ Yandex Cloud サービスアカウントが必要です。認証済み JSON キーによる IAM と、サービスアカウントの API キーに対応しています。両方の設定手順については、config/README.md を参照してください。

既存の IAM 設定は変更せずに利用できます。API キーを使用する場合は、config.json で auth.mode: "api_key" を、config/.env で YANDEX_AI_API_KEY を設定します。

ワークフロー

停止！検索を始める前に：

1. 地域を特定します。

   • ユーザーが都市や地域を指定した場合は、ID を自動で検索します。

     bash scripts/search_region.sh --name "Казань"
     

   • コンテキストから地域がわからない場合は、ユーザーに確認し、回答を待ちます。

     "どの地域を検索しますか？
     - ロシア全土（デフォルト）
     - モスクワ
     - 特定の都市（どこですか？）"
     

     ユーザーが回答するまで続行しないでください！
   • 取得した地域名を search_region.sh --name "..." に渡して、ID を取得します。
   • モスクワ市とモスクワ州のように曖昧な場合は、ユーザーに確認してください。

2. 検索モードは config.json の search.mode から取得します（デフォルトは sync）。 質問せず、設定されている値を使用してください。 例外：インフォコンテキストが必要な場合、モードは常に sync、検索タイプは SEARCH_TYPE_RU です。非同期 API とほかの検索データベースでは利用できません。

3. 設定を確認します。 yandex_cloud_folder_id と、該当する認証情報が設定されていることを確認します（auth.mode フィールドは任意です）。キーやトークンは出力しないでください。

4. 取得した地域 ID を使って検索を実行します。

5. 結果を提示します。 スニペットがある場合は cache/results/<hash>.md のパックを読み込み、情報源を示して回答します。スニペットがない場合は、順位、タイトル、URL、スニペットを提示します。

スクリプト

iam_token_get.sh

サービスアカウントキーから IAM トークンを生成または検証します。auth.mode が iam の場合にのみ必要です。

bash scripts/iam_token_get.sh

トークンは cache/iam_token.json にキャッシュされ、有効期限が切れると自動的に更新されます。

web_search_sync.sh

同期検索 — 一度に1つのクエリを検索し、すぐに結果を返します。 スマートスニペットに対応している唯一のモードです。

# Single query — с выдержками страниц
bash scripts/web_search_sync.sh \
  --query "купить дымоход" \
  --region-id 213

# Только позиции и ссылки, без выдержек
bash scripts/web_search_sync.sh \
  --query "купить дымоход" \
  --region-id 213 \
  --no-snippets

# Batch from file — по строке на запрос в stdout, пак на каждый запрос
bash scripts/web_search_sync.sh \
  --file queries.txt \
  --region-id 225

パラメーター	必須	デフォルト	値
--query, -q	はい*	-	検索テキスト
--file, -f	はい*	-	クエリを1行ずつ記載したファイル
--region-id, -r	いいえ	設定ファイルの値（225）	地域 ID
--results, -n	いいえ	スニペットありの場合は20、なしの場合は設定ファイルの値（10）	スニペットありの場合は20件までに制限されます。なしの場合は1〜100件です
--page, -p	いいえ	0	ページ番号
--search-type	いいえ	SEARCH_TYPE_RU	SEARCH_TYPE_RU / SEARCH_TYPE_TR / SEARCH_TYPE_COM / SEARCH_TYPE_KK / SEARCH_TYPE_BE / SEARCH_TYPE_UZ
--family-mode	いいえ	FAMILY_MODE_MODERATE	FAMILY_MODE_NONE / FAMILY_MODE_MODERATE / FAMILY_MODE_STRICT
--snippets	いいえ	有効	ページから抜粋を取得します
--no-snippets	いいえ	-	リンクと短いスニペットのみ

* --query または --file のいずれかが必要です。

結果は cache/results/<hash>.md（抜粋を含むパック）、 cache/results/<hash>.json（解析済み）、および cache/results/<hash>.raw（レスポンスの 生データ）に保存されます。生データは、インフォコンテキストがある場合は JSON、ない場合は XML です。

web_search_async.sh

非同期バッチ検索 — 多数のクエリを送信し、結果をポーリングします。

# Submit batch and wait
bash scripts/web_search_async.sh \
  --file queries.txt \
  --region-id 213

# Resume after timeout/interrupt
bash scripts/web_search_async.sh --resume

パラメーター	必須	デフォルト	値
--file, -f	はい	-	クエリを記載したファイル
--region-id, -r	いいえ	設定ファイルの値（225）	地域 ID
--poll-interval	いいえ	10	ポーリング間隔（分）
--max-wait	いいえ	120	タイムアウトまでの最大待機時間（分）
--resume	いいえ	-	保留中の操作のポーリングを再開します

非同期ワークフロー：

1. スクリプトがすべてのクエリを非同期操作として送信します
2. 完了するまで poll_interval 分ごとにポーリングします
3. 完了した結果をダウンロードして解析します
4. max_wait を超えた場合：概要と再開用コマンドを出力します
5. --resume を指定して再起動すると、cache/ops/ から続行し、重複を避けます

エージェント向けの注意： 非同期実行には数分から数時間かかる場合があります。 スクリプトがポーリングを自動的に処理します。タイムアウトした場合は、 --resume を指定して再実行すると続行できます。

非同期モードではインフォコンテキストを利用できません — リンクと 短いスニペットのみが返されます。ページの抜粋が必要な場合は、web_search_sync.sh --file を使用してください。 ただし、非同期検索は同期検索より約16倍、インフォコンテキストより約50倍安価です。

regions_tree.sh

一般的な地域 ID を表示します。

bash scripts/regions_tree.sh

search_region.sh

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

bash scripts/search_region.sh --name "Казань"

出力形式

各検索結果には次の項目が含まれます。

• position — 検索結果ページでの順位
• title — ページのタイトル
• url — ページの URL
• snippet — テキストのスニペット（最大300文字）
• domain — サイトのドメイン
• extract — インフォコンテキスト：ページの抜粋。ない場合は空文字列

結果は cache/results/ にキャッシュされます。

• <hash>.md — パック：各ドキュメントのタイトル、URL、インフォコンテキスト
• <hash>.raw — レスポンスの生データ：通常の検索結果では XML、インフォコンテキストでは JSON（形式はサーバーが選択します）
• <hash>.json — どちらの場合も共通の形式である、解析済みの JSON 配列

<hash> はクエリテキストの md5 の先頭12文字です。

インフォコンテキストを stdout に出力しないでください。 1件あたり約500トークンのドキュメントが20件あると、 サンドボックスの出力バッファーに収まらず、スクリプトが何も出力せずに失敗します。スクリプトは インデックスを出力します。テキストは Read/grep を使ってパックから読み取ります。

テスト

オフラインテストです。ネットワークもサービスアカウントも必要ありません。

sh scripts/tests/run.sh

リクエスト本文の構築、両方のレスポンス形式（XML と JSON）の解析、パックの描画、CLI フラグの解析をテストします。リクエスト本文は、料金をかけずに手動で確認することもできます。

YSA_DRY_RUN=1 bash scripts/web_search_sync.sh --query "тест"

人気の地域 ID

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

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

Pricing

Тарификация — за один запрос. Цены за 1000 запросов, с НДС:

Тип запроса	₽
Дневные синхронные	488
Ночные синхронные (00:00–07:59 UTC+3)	366
Дневные отложенные (async)	30,5
Запросы инфоконтекста поиска в регионе RU	1 500

Инфоконтексты дороже обычного синхронного запроса примерно втрое. Если нужны только позиции по большому списку запросов — async или --no-snippets.

Актуальный прайс: https://aistudio.yandex.ru/docs/ru/search-api/pricing

Example Session

User: Разберись, как в 2026 считается НДС для УСН, и дай ответ со ссылками

Claude: [Регион из контекста не следует, но вопрос общероссийский → 225]

        [Проверяет конфигурацию авторизации без вывода секрета]

        [Ищет с выдержками — они включены по умолчанию]
        bash scripts/web_search_sync.sh --query "НДС для УСН 2026 порядок расчёта" --region-id 225

        === Results for: НДС для УСН 2026 порядок расчёта ===
        Region: 225 | Page: 0 | Snippets: true

            #  символов  домен                     заголовок
            1      1840  nalog.gov.ru              Об изменениях в главе 26.2 НК РФ
            2      1512  consultant.ru             НДС при УСН с 2026 года
            3         0  example-blog.ru           Что изменится для упрощенцев
            ...

          Всего: 20, с выдержками: 17
          Пак:  cache/results/a1b2c3d4e5f6.md (48 KB) — читай его вместо повторного поиска

        [Читает пак и отвечает по нему, а не по заголовкам]
        Read cache/results/a1b2c3d4e5f6.md

        По порогу выручки: ...  (nalog.gov.ru)
        По ставкам: ...          (consultant.ru)

User: Найди топ выдачи яндекса по запросу "купить сэндвич дымоход" в Москве

Claude: Уточню: Москва-город или Москва и область?

User: Москва город

Claude: [Находит ID региона]
        bash scripts/search_region.sh --name "Москва"
        → Москва = 213

        [Проверяет конфигурацию авторизации без вывода секрета]

        [Задача про позиции в выдаче, содержание страниц не нужно —
         отключает инфоконтексты: дешевле втрое]
        bash scripts/web_search_sync.sh --query "купить сэндвич дымоход" \
          --region-id 213 --no-snippets

        === Results for: купить сэндвич дымоход ===
        Region: 213 | Page: 0 | Snippets: false

          1. Сэндвич-дымоходы купить в Москве — Леруа Мерлен
             https://leroymerlin.ru/...
             Широкий ассортимент сэндвич-дымоходов...

          2. Дымоходы сэндвич — купить в интернет-магазине
             https://...
             ...

          Всего: 10, с выдержками: 0
          JSON: cache/results/7f3a91c2e5d8.json
          Raw:  cache/results/7f3a91c2e5d8.raw

User: Проверь выдачу по запросам из файла queries.txt в Казани

Claude: [Находит ID региона]
        bash scripts/search_region.sh --name "Казань"
        → Казань = 43

        [Проверяет конфигурацию авторизации без вывода секрета]

        [Батч по одному запросу; в stdout — строка на запрос,
         тексты и разбор лежат в файлах]
        bash scripts/web_search_sync.sh --file queries.txt --region-id 43

          запрос                                     результаты            пак
          дымоход сэндвич цена                        20 док., выдержек 18  cache/results/a1b2c3d4e5f6.md
          купить дымоход казань                       20 док., выдержек 15  cache/results/b2c3d4e5f6a1.md
          дымоход нержавейка                          20 док., выдержек 19  cache/results/c3d4e5f6a1b2.md

        === Batch complete: 3/3 queries processed ===