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

Yandex Search API позволяет отправлять запросы к поисковой базе Яндекса через REST API, gRPC API или Yandex AI Studio SDK. В этом руководстве вы настроите доступ к Yandex Search API и выполните первый поисковый запрос в синхронном режиме — результат вернется сразу после обработки запроса.

Обо всех возможностях сервиса читайте в разделе О сервисе Yandex Search API. Стоимость использования указана в разделе Правила тарификации для Yandex Search API.

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

AI Studio использует ресурсную модель Yandex Cloud: большинство сервисов хранит ресурсы в каталогах. Каталоги принадлежат облакам, а облака — организациям. Каталог потребуется и для работы с AI Studio.

Войдите в AI Studio, используя личный аккаунт на Яндексе (Яндекс ID). Подробную инструкцию, как создать такой аккаунт, смотрите в Справке Яндекс ID.
Создайте организацию:
- Введите название организации.
- Укажите название облака — оно будет использоваться для всех ресурсов Yandex Cloud.
- Нажмите Открыть AI Studio.
В организации будет автоматически создан новый каталог с именем default.

Привяжите платежный аккаунт

Для работы с AI Studio необходим активный платежный аккаунт, привязанный к вашему облаку. При создании первого платежного аккаунта с привязанной к нему банковской картой вам будет начислен стартовый грант.

После авторизации в AI Studio нажмите кнопку Привязать платежный аккаунт в правом верхнем углу интерфейса.
Создайте платежный аккаунт или выберите существующий.
- Нажмите кнопку Добавить карту.
- Укажите данные карты: 16-значный номер, срок действия, код CVV (с обратной стороны карты).
- Нажмите кнопку Привязать.
Убедитесь, что платежный аккаунт имеет статус ACTIVE или TRIAL_ACTIVE.

Создайте API-ключ

Чтобы создать API-ключ:

Интерфейс AI Studio

В интерфейсе AI Studio нажмите Создать API-ключ в правом верхнем углу.
(Опционально) Измените описание API-ключа, чтобы вы легко могли найти его после.
Выберите срок действия API-ключа.
Нажмите кнопку Создать.
Сохраните идентификатор и секретный ключ.

Внимание

Не передавайте никому свой API-ключ. После закрытия диалога значение ключа будет недоступно.

Вместе с API‑ключем будет создан и сервисный аккаунт с ролью для работы с Yandex Search API.

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

После создания API-ключа вы можете сразу выполнить поисковый запрос. Выберите удобный способ: с помощью cURL через REST API или с помощью Yandex AI Studio SDK.

cURL

AI SDK

Для работы с REST API установите утилиты cURL и jq:

# Для Ubuntu/Debian
        sudo apt-get install curl jq
        
        # Для macOS
        brew install curl jq

Создайте файл с телом запроса body.json:
```
{
          "query": {
            "searchType": "SEARCH_TYPE_RU",
            "queryText": "кофемашина"
          },
          "folderId": "<идентификатор_каталога>",
          "responseFormat": "FORMAT_HTML"
        }
        
```
Где:
- searchType — тип поиска. SEARCH_TYPE_RU — поиск в русскоязычном сегменте интернета.
- queryText — текст поискового запроса.
- folderId — идентификатор каталога, в котором создан API-ключ.
- responseFormat — формат ответа. FORMAT_HTML — результаты в формате HTML.

Выполните запрос:

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

Где <API-ключ> — созданный ранее API-ключ.

Результат:

{
          "rawData": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4KPHlhbmRleHNlYXJjaCB2ZXJzaW9uPSIxLjAiPgo8cmVxdWVzdD4..."
        }

Поле rawData содержит результаты поиска в кодировке Base64.

Декодируйте результат:

curl \
          --request POST \
          --header "Authorization: Api-Key <API-ключ>" \
          --data "@body.json" \
          "https://searchapi.api.cloud.yandex.net/v2/web/search" | \
          jq -r .rawData | \
          base64 --decode > result.html

Результаты поиска будут сохранены в файл result.html.

Совет

Чтобы получить результаты в формате XML, измените "responseFormat": "FORMAT_HTML" на "responseFormat": "FORMAT_XML". Подробнее о форматах см. XML-формат ответа при текстовом поиске и HTML-формат ответа при текстовом поиске.

Для работы с AI SDK установите Python версии 3.10 или выше и библиотеку Yandex AI Studio SDK:

# Проверьте версию Python
        python3 --version
        
        # Установите библиотеку
        pip install yandex-ai-studio-sdk

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

#!/usr/bin/env python3
        
        from yandex_ai_studio_sdk import AIStudio
        
        # Инициализация SDK
        sdk = AIStudio(
            folder_id="<идентификатор_каталога>",
            auth="<API-ключ>",
        )
        
        # Выполнение поиска
        search = sdk.search_api.web(search_type="ru")
        result = search.run_sync("кофемашина", format="html")
        
        # Сохранение результата в файл
        with open("result.html", "w", encoding="utf-8") as f:
            f.write(result.decode("utf-8"))
        
        print("Результаты сохранены в файл result.html")

Где:

<идентификатор_каталога> — идентификатор каталога, в котором создан API-ключ.
<API-ключ> — созданный ранее API-ключ.
search_type="ru" — тип поиска (русскоязычный сегмент).
format="html" — формат результатов.

Выполните скрипт:
```
python3 search.py
        
```
Результат будет сохранен в файл result.html.

Совет

Чтобы получить результаты в формате XML, измените format="html" на format="xml". Подробнее о параметрах SDK см. в документации Yandex AI Studio SDK.