Связаться с намиПодключиться

Как начать работать с Yandex Search API через интерфейс API v2

Статья создана
Обновлена 29 мая 2025 г.

API v2 – рекомендованный интерфейс для работы с Yandex Search API. API v2 полностью интегрирован в экосистему Yandex Cloud и одновременно с аутентификацией по API-ключу поддерживает более безопасную аутентификацию с помощью короткоживущих IAM-токенов.

Стоимость использования Yandex Search API см. в разделе Правила тарификации для Yandex Search API

Перед началом работы

Зарегистрируйтесь в Yandex Cloud и создайте платежный аккаунт:

  1. Перейдите в консоль управления, затем войдите в Yandex Cloud или зарегистрируйтесь.
  2. На странице Yandex Cloud Billing убедитесь, что у вас подключен платежный аккаунт, и он находится в статусе ACTIVE или TRIAL_ACTIVE. Если платежного аккаунта нет, создайте его и привяжите к нему облако.

Если у вас есть активный платежный аккаунт, вы можете создать или выбрать каталог, в котором будет работать ваша инфраструктура, на странице облака.

Подробнее об облаках и каталогах.

Подготовьте облако к работе

  1. Создайте сервисный аккаунт, от имени которого будут выполняться запросы к Yandex Search API.
  2. Назначьте созданному сервисному аккаунту роль search-api.webSearch.user.
  3. Создайте API-ключ сервисного аккаунта, указав для него область действия yc.search-api.execute.
  4. Чтобы воспользоваться примерами, установите утилиты cURL и jq.

В приведенных примерах используется аутентификация с помощью API-ключа. Чтобы использовать для аутентификации IAM-токен, измените в примерах запросов заголовок Authorization. Подробнее см. в разделе Аутентификация в API v2.

В приведенных примерах запросы к Yandex Search API выполняются с помощью REST API. Примеры выполнения запросов с помощью gPRC API см. в разделе Выполнение поисковых запросов с помощью API v2 в отложенном режиме.

Сформируйте поисковый запрос

Приведенный в примере запрос возвращает страницу с результатами поиска по запросу кофемашина в форматах HTML и XML.

  1. Создайте файл с телом запроса (например, body.json), указав в поле folderId идентификатор каталога, в котором вы будете работать с Yandex Search API:

    body.json

    {
    "query": {
      "searchType": "SEARCH_TYPE_RU",
      "queryText": "кофемашина"
    },
    "folderId": "<идентификатор_каталога>",
    "responseFormat": "FORMAT_HTML",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/132.0.0.0 YaBrowser/25.2.0.0 Safari/537.36"
}

    body.json

    {
    "query": {
      "searchType": "SEARCH_TYPE_RU",
      "queryText": "кофемашина"
    },
    "folderId": "<идентификатор_каталога>",
    "responseFormat": "FORMAT_XML",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/132.0.0.0 YaBrowser/25.2.0.0 Safari/537.36"
}

    Подробнее о параметрах тела запроса см. в разделе Формат тела запроса.

  2. Выполните HTTP-запрос к сервису, указав созданный ранее API-ключ и путь к файлу с телом запроса:

    curl \
  --request POST \
  --header "Authorization: Api-Key <API-ключ>" \
  --data "@body.json" \
  "https://searchapi.api.cloud.yandex.net/v2/web/searchAsync"

    Результат:

    {
"done": false,
"id": "sprqjo0kf40j********",
"description": "WEB search async",
"createdAt": "2025-05-05T18:10:44Z",
"createdBy": "ajegtlf2q28a********",
"modifiedAt": "2025-05-05T18:10:44Z"
}

    В результате сервис вернет идентификатор объекта Operation (значение id), по которому можно будет получить результат операции. Сохраните полученный идентификатор – он понадобится позднее.

Убедитесь в успешном выполнении запроса и получите результат

Дождитесь, пока Yandex Search API выполнит запрос и сформирует ответ. На это может потребоваться от нескольких минут до нескольких часов.

Чтобы убедиться в успешном выполнении поискового запроса, выполните HTTP-запрос:

curl \
  --request GET \
  --header "Authorization: Api-Key <API-ключ>" \
  https://operation.api.cloud.yandex.net/operations/<идентификатор_запроса> \
  > result.json

Где:

  • <API-ключ> — созданный ранее API-ключ.
  • <идентификатор_запроса> — сохраненный на предыдущем шаге идентификатор объекта Operation.

В файл result.json будет сохранен ответ сервиса. Откройте полученный файл, чтобы убедиться, что он содержит поле done в значении true и поле response с результатом выполнения поискового запроса.

Декодируйте полученный результат

Результат выполнения поискового запроса сохранен в поле response файла result.json в кодировке Base64. Чтобы декодировать полученный результат, выполните команду:

echo "$(< result.json)" | \
  jq -r .response.rawData | \
  base64 --decode > result.html

В результате в файл result.html будет сохранен HTML-ответ по запросу.

echo "$(< result.json)" | \
  jq -r .response.rawData | \
  base64 --decode > result.xml

В результате в файл result.xml будет сохранен XML-ответ по запросу.

См. также

Следующая
Все инструкции