artwist-polyakov/polyakov-claude-skills/yandex-search-api

yandex-search-api

Parse Yandex SERP via Yandex Cloud Search API v2 (sync + async).

Инфоконтексты (Smart Snippets)

Search API отдаёт не только ссылку и сниппет в пару предложений, а фрагмент найденной страницы примерно на 500 токенов — релевантный запросу и с цитатами из документа. Информации уже достаточно, чтобы ответить, а обрабатывать страницу самому не нужно.

Это то, ради чего скилл ставят в агента: одного запроса хватает на ответ, а не только на список ссылок.

Включено по умолчанию, отдельного скрипта не нужно:

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

Тексты в ответ не печатаются — они уходят в cache/results/<hash>.md, а в stdout приходит индекс по строке на документ. Дальше читай пак файлом: целиком, если нужен весь материал, или грепом, если нужен один источник. Повторный поиск той же фразы ради текста, который уже лежит в паке, — потраченные деньги.

Три ограничения, которые меняют выбор команды:

• Только синхронный режим. web_search_async.sh инфоконтекстов не вернёт.
• Только `SEARCH_TYPE_RU`. С другим типом поиска скилл выполнит запрос, но

без инфоконтекстов, и скажет об этом.

• Не больше 20 документов. Попросить больше нельзя: при --results выше 20

API отдаёт не 20, а вдвое меньше — по той же цене. Скилл клампит сам.

• Дороже. 1 500 ₽ за 1000 запросов против 488 ₽ у обычного синхронного.

Когда нужны только позиции и домены — --no-snippets (или search.smart_snippets.enabled: false в конфиге).

Подробности, формат ответа, отладка и разбор ошибок: references/SMART_SNIPPETS.md.

Config

Для работы нужен сервисный аккаунт Яндекс.Облака с ролью search-api.webSearch.user. Поддерживаются IAM через авторизованный JSON-ключ и API-ключ сервисного аккаунта. Пошаговая настройка обоих вариантов: config/README.md.

Существующие IAM-конфигурации работают без изменений. Для API-ключа задайте auth.mode: "api_key" в config.json и YANDEX_AI_API_KEY в config/.env.

Workflow

STOP! Before any search:

1. Определи регион:

• Если пользователь указал город/регион — найди ID автоматически:

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

• Если регион не понятен из контекста — СПРОСИ и ЖДИ ответа:

``` "Для какого региона искать?

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

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

• Полученное название → search_region.sh --name "..." → получаешь ID
• Для неоднозначных случаев (Москва город vs область) — уточни у пользователя

1. Режим поиска берётся из config.json → search.mode (по умолчанию sync).

Не спрашивай — используй то, что в конфиге. Исключение: если нужны инфоконтексты, режим всегда sync, а тип поиска — SEARCH_TYPE_RU; в асинхронном API и в других поисковых базах их нет.

1. Verify config: убедись, что заданы yandex_cloud_folder_id,

соответствующий credential (поле auth.mode необязательно). Не печатай ключ или токен.

1. Run search с полученным region ID
2. Present results: со snippets — прочитай пак cache/results/<hash>.md

и отвечай по нему, ссылаясь на источники; без snippets — позиция, заголовок, URL, сниппет

Scripts

iam_token_get.sh

Generate or validate IAM token from Service Account key. Needed only when auth.mode is iam.

bash scripts/iam_token_get.sh

Token is cached in cache/iam_token.json and auto-refreshed when expired.

web_search_sync.sh

Synchronous search — one query at a time, immediate results. Единственный режим, который умеет smart snippets.

# 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

\* Either --query or --file is required.

Results saved to cache/results/<hash>.md (пак с выдержками), cache/results/<hash>.json (parsed) и cache/results/<hash>.raw — исходное тело ответа: JSON с инфоконтекстами, XML без них.

web_search_async.sh

Asynchronous batch search — submit many queries, poll for results.

# 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

Async workflow:

1. Script submits all queries as async operations
2. Polls every poll_interval minutes for completion
3. Downloads and parses results as they complete
4. If max_wait exceeded: prints summary + resume command
5. On restart with --resume: continues from cache/ops/, no duplicates

NOTE for agent: Async execution can take minutes to hours. The script handles polling automatically. If it times out, re-run with --resume to continue.

Инфоконтексты в асинхронном режиме недоступны — вернутся только ссылки и короткие сниппеты. Нужны фрагменты страниц — web_search_sync.sh --file. Зато async в ~16 раз дешевле синхронного и в ~50 раз дешевле инфоконтекстов.

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 "Казань"

Output Format

Each search result contains:

• position — rank in SERP
• title — page title
• url — page URL
• snippet — text snippet (up to 300 chars)
• domain — site domain
• extract — инфоконтекст: фрагмент страницы; пустая строка, если его нет

Results cached in cache/results/:

• <hash>.md — пак: заголовок, URL и инфоконтекст по каждому документу
• <hash>.raw — исходное тело ответа: XML для обычной выдачи, JSON для

инфоконтекстов (формат выбирает сервер)

• <hash>.json — parsed JSON array, единый формат для обоих случаев

<hash> — первые 12 символов md5 от текста запроса.

Не печатай инфоконтексты в stdout. 20 документов по ~500 токенов не помещаются в буфер вывода песочницы, и скрипт упадёт молча. Скрипты печатают индекс, тексты читаются из пака через Read/grep.

Tests

Офлайн-тесты: ни сети, ни сервисного аккаунта.

sh scripts/tests/run.sh

Проверяют сборку тела запроса, разбор обоих форматов ответа (XML и JSON), отрисовку пака и разбор флагов CLI. Тело запроса можно посмотреть и вручную, ничего не оплачивая:

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

Popular Region IDs

Run bash scripts/regions_tree.sh for full list.

Pricing

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

Инфоконтексты дороже обычного синхронного запроса примерно втрое. Если нужны только позиции по большому списку запросов — 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 ===