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

Как начать работать с Yandex Search API

Статья создана
Улучшена
Обновлена 12 ноября 2025 г.

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

Выполнять запросы к Yandex Search API вы можете с помощью Yandex Cloud ML SDK, REST API и gRPC API. Поисковая выдача зависит от заданных в запросе параметров.

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

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

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

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

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

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

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

Чтобы воспользоваться примерами:

  1. Создайте сервисный аккаунт и назначьте ему роль search-api.webSearch.user.

  2. Получите и сохраните API-ключ сервисного аккаунта, указав для него область действия yc.search-api.execute.

    В примерах используется аутентификация с помощью API-ключа. Yandex Cloud ML SDK также поддерживает аутентификацию с помощью IAM-токена и OAuth-токена. Подробнее см. в разделе Аутентификация в Yandex Cloud ML SDK.

    Примечание

    Если вы используете ОС Windows, рекомендуем предварительно установить оболочку WSL и выполнять дальнейшие действия в этой оболочке.

  3. Установите Python версии 3.10 или выше.

  4. Установите библиотеку Python venv для создания изолированных виртуальных окружений в Python.

  5. Создайте и войдите в новое виртуальное окружение Python:

    python3 -m venv new-env
source new-env/bin/activate

  6. С помощью менеджера пакетов pip установите библиотеку ML SDK:

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

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

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

Выполните поисковый запрос

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

Чтобы выполнить поисковый запрос с помощью Yandex Search API:

  1. Создайте файл web-search.py и добавьте в него следующий код:

    #!/usr/bin/env python3

from __future__ import annotations

from yandex_cloud_ml_sdk import YCloudML

from yandex_cloud_ml_sdk.search_api import (
    FamilyMode,
    FixTypoMode,
    GroupMode,
    Localization,
    SearchType,
    SortMode,
    SortOrder,
)

import pathlib

USER_AGENT = "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"

search_query = "кофемашина"

formats = ["xml", "html"]


def main() -> None:

    sdk = YCloudML(
        folder_id="<идентификатор_каталога>",
        auth="<API-ключ>",
    )
    sdk.setup_default_logging("error")

    search = sdk.search_api.web(
        search_type="ru",
        user_agent=USER_AGENT,
    )

    for format in formats:

        print(f"Saving results in the {format.upper()} format:")
        for page in range(0, 3):
            operation = search.run_deferred(search_query, format=format, page=page)
            search_result = operation.wait(poll_interval=1)
            output_filename = (
                str(pathlib.Path(__file__).parent)
                + "/"
                + "page_"
                + str(page + 1)
                + "."
                + format
            )
            file = open(output_filename, "a")
            file.write(search_result.decode("utf-8"))
            print(f"Page {page} saved to file {output_filename}")
            file.close()
        print()


if __name__ == "__main__":
    main()

    Где:

    Подробнее о параметрах запроса см. в разделе Выполнение текстовых поисковых запросов в отложенном режиме.

  2. Выполните созданный файл:

    python3 web-search.py

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

    Saving results in the XML format:
Page 0 saved to file /Users/MyUser/Desktop/page_1.xml
Page 1 saved to file /Users/MyUser/Desktop/page_2.xml
Page 2 saved to file /Users/MyUser/Desktop/page_3.xml

Saving results in the HTML format:
Page 0 saved to file /Users/MyUser/Desktop/page_1.html
Page 1 saved to file /Users/MyUser/Desktop/page_2.html
Page 2 saved to file /Users/MyUser/Desktop/page_3.html

  1. Отправьте поисковый запрос:

    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"
}

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

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

      curl \
  --request POST \
  --header "Authorization: Api-Key <API-ключ>" \
  --data "@body.json" \
  "https://searchapi.api.yandexcloud.kz/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), по которому можно будет получить результат операции. Сохраните полученный идентификатор – он понадобится позднее.

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

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

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

    Где:

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

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

  3. Декодируйте полученный результат. Для этого выполните команду:

    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-ответ по запросу.

См. также

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