# Yandex Search API

> Получите результаты веб поиска Яндекса через API v2. Выгрузите выдачу в XML для обработки или запросите HTML.

- HTML: https://poapi.ru/yandex/yandex-search-api
- Компания: Яндекс
- Страница компании: https://poapi.ru/company/yandex
- Категории: ML
- Сайт API: https://aistudio.yandex.ru/ru/docs/search-api/quickstart/
- Адрес API: https://searchapi.api.cloud.yandex.net
- Документация: https://aistudio.yandex.ru/ru/docs/search-api/api-ref/WebSearch/search

## Подключение и ограничения
- Авторизация: Нужен активный платёжный аккаунт, каталог и сервисный аккаунт с ролью search-api.webSearch.user. Передавайте ключ с областью yc.search-api.execute как Authorization: Api-Key <ключ>. Для примера нужны Python 3 и переменные YANDEX_SEARCH_API_KEY и YANDEX_SEARCH_FOLDER_ID.
- Ограничения: POST https://searchapi.api.cloud.yandex.net/v2/web/search. Для текстового поиска доступны FORMAT_XML и FORMAT_HTML. В отложенном режиме сначала приходит операция; её результат проверяется отдельным запросом.

```python
import base64
import binascii
import json
import os
from pathlib import Path
from urllib.request import Request, urlopen
import xml.etree.ElementTree as ET

body = {
    "query": {"searchType": "SEARCH_TYPE_RU", "queryText": "документация Python"},
    "folderId": os.environ["YANDEX_SEARCH_FOLDER_ID"],
    "responseFormat": "FORMAT_XML",
}
request = Request(
    "https://searchapi.api.cloud.yandex.net/v2/web/search",
    data=json.dumps(body).encode(),
    headers={
        "Authorization": f"Api-Key {os.environ['YANDEX_SEARCH_API_KEY']}",
        "Content-Type": "application/json",
    },
    method="POST",
)
with urlopen(request, timeout=30) as response:
    result = json.load(response)

try:
    xml = base64.b64decode(result["rawData"], validate=True)
    root = ET.fromstring(xml)
except (KeyError, TypeError, binascii.Error, ET.ParseError):
    raise SystemExit("API не вернул XML-выдачу в rawData")

error = root if root.tag == "error" else root.find(".//error")
if error is not None:
    raise SystemExit(f"Поиск вернул код {error.get('code')}")

Path("search-result.xml").write_bytes(xml)
print("Выдача сохранена в search-result.xml")
```
- Результат: Синхронный запрос текстового поиска возвращает выдачу в rawData в кодировке Base64. Скрипт сохраняет разбираемый XML без элемента error; разбор документов и ссылок можно выполнять далее по XML.
- Проверено по документации: 2026-11-22
- [Веб-поиск в синхронном режиме](https://aistudio.yandex.ru/ru/docs/search-api/operations/web-search-sync)
- [Запрос WebSearch.Search](https://aistudio.yandex.ru/ru/docs/search-api/api-ref/WebSearch/search)
- [Тарификация Search API](https://aistudio.yandex.ru/ru/docs/search-api/pricing)

## Описание
Yandex Search API обращается к поисковой базе Яндекса. Текстовый поиск поддерживает синхронный запрос с выдачей в ответе и отложенный запрос с идентификатором операции. Отдельные методы ищут изображения и формируют генеративный ответ. Выберите текстовый XML, если нужно передать поисковую выдачу в обработчик документов: он содержит результаты без дополнительных элементов выдачи.

## Когда использовать
- Получить XML по поисковой фразе и передать его обработчику ссылок для подбора материалов.
- Сохранить HTML для изучения того, какие дополнительные элементы появились в выдаче.
- Ночью отправить пакет отложенных запросов и собрать результаты по идентификаторам операций.

## Порядок интеграции
1. Настройте облако, каталог и активный платёжный аккаунт. Создайте ключ с доступом к веб-поиску.
2. Подставьте свою фразу в queryText. Для поиска по русскоязычному сегменту оставьте SEARCH_TYPE_RU.
3. Запросите FORMAT_XML, декодируйте rawData из Base64 и проверьте, что XML разбирается и не содержит элемента error.
4. Передайте сформированный search-result.xml обработчику документов. При коде 15 покажите пустую выдачу.

## Что проверить перед запуском
- Код HTTP 200 подтверждает получение ответа. Проверьте также rawData и ошибку внутри XML прежде, чем использовать выдачу.
- Задайте нужный тип поиска, если важен конкретный сегмент выдачи. Регион можно указать отдельным параметром region.
- Отложенные запросы доступны с 00:00 до 06:00 по Москве. Запланируйте пакетную отправку на это окно. Ставки синхронного и отложенного режимов различаются.

## Похожие API
- [Nexara API](https://poapi.ru/nexara/nexara-api): API для искусственного интеллекта, генеративных моделей и ML интеграций.
- [Translate](https://poapi.ru/yandex/translate): Перевод текста и HTML, определение исходного языка и использование глоссариев для согласованного перевода терминов.
- [Vision OCR](https://poapi.ru/yandex/vision-ocr): Распознавание текста на изображениях и в PDF с координатами блоков, строк и слов, а также структурой таблиц.
- [Yandex DataSphere API v2](https://poapi.ru/yandex/datasphere): Разрабатывайте и запускайте ML вычисления в проектах DataSphere: работайте в ноутбуках, готовьте задания Jobs, настраивайте окружение, данные и доступ к облачным ресурсам.
- [Yandex Foundation Models в AI Studio](https://poapi.ru/yandex/foundation-models): Подключайте модели Yandex Foundation Models в приложениях: генерируйте текст, получайте эмбеддинги и используйте отдельные API для токенизации и классификации.
- [Yandex SpeechKit API](https://poapi.ru/yandex/speechkit): Преобразуйте речь в текст и текст в речь для голосовых интерфейсов, расшифровки звонков и озвучивания. Выберите синхронное, асинхронное или потоковое распознавание по длительности и задержке.
