Yandex Search API — облачный сервис для программного получения результатов поиска Яндекса. Он поддерживает веб-поиск и отдельные сценарии поиска по изображениям, возвращает структурированный или готовый к показу ответ и оплачивается через Yandex Cloud. Это не API Яндекс Вебмастера и не способ добавить страницу в индекс.
Что можно получить через Search API
Сервис выполняет поиск по коллекциям, описанным в документации: русской, турецкой или мировой, а также поддерживает разные типы результатов и форматы ответа. Для веб-поиска можно получить XML, JSON или HTML в зависимости от выбранного интерфейса. HTML удобен для быстрого встраивания, JSON — для собственной обработки и хранения отдельных полей.
Поиск отражает правила и возможности API, а не полностью воспроизводит страницу yandex.ru в браузере. Персонализация, эксперименты интерфейса и некоторые блоки могут отличаться. Если задача — мониторинг позиций, заранее определите регион, язык, устройство и способ сравнения результатов.
| Режим | Подходит для | Особенность |
|---|---|---|
| Синхронный | Ответ нужен сразу | Клиент ждёт выполнение запроса |
| Отложенный | Пакетная обработка | Результат забирают отдельным запросом |
| HTML | Готовое отображение | Меньше контроля над полями |
| JSON/XML | Аналитика и интеграция | Нужно разобрать структуру ответа |
| Поиск по изображению | Визуально похожие результаты | Отдельная операция и требования к входу |
Что подготовить в Yandex Cloud
Нужны аккаунт Yandex Cloud, облако, каталог и активный платёжный аккаунт. Для серверной интеграции создайте сервисный аккаунт в нужном каталоге и назначьте только роль, указанную в актуальной документации Search API. Не используйте персональный ключ разработчика в клиентском JavaScript: посетитель увидит его и сможет расходовать квоту.
Выберите способ авторизации, который поддерживает ваш сценарий: IAM-токен ограниченного срока или API-ключ там, где он разрешён документацией. Секрет храните в менеджере секретов или переменной окружения на сервере. Записывайте идентификатор каталога и endpoint отдельно от ключа, чтобы менять доступ без правки кода.
- Создать или выбрать облако и каталог.
- Подключить платёжный аккаунт.
- Активировать Search API.
- Создать сервисный аккаунт и минимальную роль.
- Получить поддерживаемый тип учётных данных.
- Сделать тестовый запрос с сервера.
Как выглядит запрос
Клиент передаёт поисковую фразу и параметры выбранного интерфейса: коллекцию, регион, язык, фильтрацию и пагинацию. Точные названия полей отличаются между синхронным, отложенным и специализированным методами, поэтому код следует строить по текущей OpenAPI-документации, а не по случайному примеру из старой статьи.
Сохраняйте нормализованные параметры вместе с результатом. Иначе через месяц нельзя будет объяснить, почему две выдачи различаются: поменялся поиск или запрос ушёл с другим регионом. Не логируйте IAM-токен и заголовок авторизации.
POST https://searchapi.api.cloud.yandex.net/v2/web/search
Authorization: Bearer <IAM_TOKEN>
Content-Type: application/json
{
"query": { "searchType": "SEARCH_TYPE_RU", "queryText": "indexnow" },
"folderId": "<FOLDER_ID>",
"responseFormat": "FORMAT_JSON"
}Синхронный и отложенный поиск
Синхронный вызов проще для единичной проверки, но держит соединение до ответа и ограничен своей квотой. Отложенный поиск лучше подходит для очередей и больших наборов: приложение отправляет задачу, получает идентификатор операции, затем проверяет статус и забирает результат. Повторные проверки статуса должны иметь паузу и общий таймаут.
На стороне приложения добавьте очередь, повтор только для временных ошибок и идемпотентный ключ задания. Ошибка авторизации или неверный параметр не исправятся десятью повторами. При ответах 429 и 5xx применяйте экспоненциальную задержку и учитывайте серверные рекомендации.
Квоты, стоимость и хранение
Квоты зависят от метода и могут меняться. В июле 2026 года Yandex Cloud публикует отдельные почасовые и посекундные значения для синхронного, отложенного и генеративного поиска, но в интеграции нельзя зашивать их как вечную константу. Читайте текущие значения в документации и консоли своего облака.
Стоимость оценивайте по числу запросов, повторов и глубине выдачи. Кешируйте результат только там, где это разрешают условия сервиса и бизнес-задача терпит устаревание. Для аудита храните время, параметры, код ответа и идентификатор операции; полный ответ может содержать данные, для которых нужны собственные правила срока хранения.
Альтернативы и выбор инструмента
Yandex XML — более старый интерфейс с иной моделью подключения и ограничениями. Сервисы DataForSEO, SerpAPI, Serpstat и похожие агрегаторы удобны единой схемой для нескольких поисковиков, но являются отдельными поставщиками: сравните источник данных, региональность, задержку, условия хранения и поддержку блоков выдачи.
Для проверки собственных показов и кликов надёжнее данные Яндекс Вебмастера, а для мониторинга позиций — специализированные трекеры. Search API выбирают, когда приложению нужен управляемый официальный запрос к поиску. Он не связан с API отправки URL на индексацию.
Частые вопросы
Yandex Search API добавляет страницы в поиск?
Нет. Он получает результаты поиска. Для управления сайтом используются Яндекс Вебмастер, sitemap, переобход и другие инструменты индексации.
Можно ли вызывать API из браузера?
Секреты нельзя отдавать клиенту. Создайте серверный endpoint, который проверяет входные данные, применяет лимиты и обращается к Yandex Cloud.
Какой формат ответа выбрать?
JSON удобен для новых интеграций, XML — для существующих обработчиков, HTML — для готового отображения. Сверьте поддержку формата конкретным методом.
Что читать дальше
Источники
Факты, названия разделов и ограничения сверены с документацией. Интерфейсы, тарифы и лимиты сервисов могут меняться.