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

Выполнение поисковых запросов с помощью API v2 в синхронном режиме

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

API v2 сервиса Yandex Search API позволяет выполнять текстовый поиск в поисковой базе Яндекса и получать результат поиска в формате XML или HTML в синхронном режиме. Выполнять запросы можно с помощью gPRC API. Поисковая выдача зависит от заданных в запросе параметров.

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

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

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

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

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

Чтобы воспользоваться примерами, установите утилиты gRPCurl и jq.

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

  1. Для аутентификации в API v2 от имени сервисного аккаунта создайте сервисный аккаунт.

  2. Назначьте пользователю или сервисному аккаунту, от имени которого будут выполняться запросы, роль search-api.webSearch.user.

  3. Получите IAM-токен, необходимый для аутентификации.

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

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

  1. Отправьте запрос и получите результат в кодировке Base64:

    1. Создайте файл с телом запроса (например, body.json):

      body.json

      {
    "query": {
      "search_type": "<тип_поиска>",
      "query_text": "<текст_поискового_запроса>",
      "family_mode": "<значение_настройки_фильтрации_результатов>",
      "page": "<номер_страницы>",
      "fix_typo_mode": "<значение_настройки_режима_исправления_опечаток>"
    },
    "sort_spec": {
      "sort_mode": "<правило_сортировки_результатов>",
      "sort_order": "<порядок_сортировки_результатов>"
    },
    "group_spec": {
      "group_mode": "<метод_группировки_результатов>",
      "groups_on_page": "<количество_групп_на_странице>",
      "docs_in_group": "<количество_документов_в_группе>"
    },
    "max_passages": "<максимальное_количество_пассажей>",
    "region": "<идентификатор_региона>",
    "l10n": "<язык_уведомлений>",
    "folder_id": "<идентификатор_каталога>",
    "response_format": "<формат_результата>",
    "user_agent": "<заголовок_User-Agent>"
}
      Описание полей

      • search_type — тип поиска. Возможные значения:

        • SEARCH_TYPE_RU — для типа поиска Русский.
        • SEARCH_TYPE_TR — для типа поиска Турецкий.
        • SEARCH_TYPE_COM — для типа поиска Международный.

      • query_text — текст поискового запроса. Максимальная длина запроса — 400 символов.

      • family_mode — фильтрация результатов. Необязательный параметр. Возможные значения:

        • FAMILY_MODE_MODERATE — умеренный фильтр (значение по умолчанию). Из выдачи исключаются документы, относящиеся к категории "для взрослых", если запрос явно не направлен на поиск подобных ресурсов.
        • FAMILY_MODE_NONE — фильтрация отключена. В выдачу включаются любые документы вне зависимости от содержимого.
        • FAMILY_MODE_STRICT — семейный фильтр. Вне зависимости от поискового запроса из выдачи исключаются документы, относящиеся к категории "для взрослых", а также содержащие ненормативную лексику.

      • page — номер запрашиваемой страницы. Необязательный параметр. По умолчанию возвращается первая страница поисковой выдачи. Нумерация страниц начинается с нуля (первой странице соответствует значение 0).

      • fix_typo_mode — значение настройки режима исправления опечаток в поисковом запросе. Необязательный параметр. Возможные значения:

        • FIX_TYPO_MODE_ON — исправление опечаток включено (значение по умолчанию). Опечатки в тексте поискового запроса автоматически исправляются.
        • FIX_TYPO_MODE_OFF — исправление опечаток отключено. Опечатки в тексте поискового запроса не исправляются, поиск выполняется в полном соответствии с переданным запросом.

      • sort_mode — правило сортировки результатов поиска, которое определяет порядок выдачи результатов поиска. Необязательный параметр. Возможные значения:

        • SORT_MODE_BY_RELEVANCE — сортировка по релевантности (значение по умолчанию).
        • SORT_MODE_BY_TIME — сортировка по времени изменения документа.

      • sort_order — порядок сортировки результатов поиска. Необязательный параметр. Возможные значения:

        • SORT_ORDER_DESC — прямой порядок сортировки — от наиболее свежего к наиболее старому (значение по умолчанию).
        • SORT_ORDER_ASC — обратный порядок сортировки — от наиболее старого к наиболее свежему.

      • group_mode — метод группировки результатов. Необязательный параметр. Возможные значения:

        • GROUP_MODE_DEEP — группировка по доменам. Каждая группа содержит документы одного домена (значение по умолчанию).
        • GROUP_MODE_FLAT — плоская группировка. Каждая группа содержит один документ.

      • groups_on_page — максимальное количество групп, которые могут быть возвращены на одной странице результатов поиска. Необязательный параметр. Допустимые значения — от 1 до 100. Значение по умолчанию — 20.

      • docs_in_group — максимальное количество документов, которые могут быть возвращены в одной группе. Необязательный параметр. Допустимые значения — от 1 до 3. Значение по умолчанию — 1.

      • max_passages — максимальное количество пассажей, которое может быть использовано при формировании сниппета к документу. Необязательный параметр. Допустимые значения — от 1 до 5. По умолчанию для каждого документа возвращается не более четырех пассажей с текстом запроса.

      • region — идентификатор страны или региона поиска, который влияет на правила ранжирования документов. Поддерживается только для типов поиска Русский и Турецкий.

        Список идентификаторов часто используемых стран и регионов см. в разделе Регионы поиска.

      • l10n — язык уведомлений поискового ответа. Влияет на текст, передаваемый в теге found-docs-human и в сообщениях об ошибках. Необязательный параметр. Возможные значения зависят от выбранного типа поиска:

        • Тип поиска Русский:

          • LOCALIZATION_RU — русский язык (значение по умолчанию).
          • LOCALIZATION_BE — белорусский язык.
          • LOCALIZATION_KK — казахский язык.
          • LOCALIZATION_UK — украинский язык.

        • Тип поиска Турецкий:

          • LOCALIZATION_TR — турецкий язык.

        • Тип поиска Международный:

          • LOCALIZATION_EN — английский язык.

      • folder_id — идентификатор каталога пользователя или сервисного аккаунта, от имени которого вы будете выполнять запросы.

      • response_format — формат получения поисковой выдачи. Необязательный параметр. Возможные значения:

        • FORMAT_XML — результат запроса будет передан в формате XML (значение по умолчанию).
        • FORMAT_HTML — результат запроса будет передан в формате HTML.

      • user_agent — строка, содержащая заголовок User-Agent. Параметр позволяет получить поисковую выдачу, ориентированную на конкретные устройство и браузер, в том числе мобильную выдачу. Необязательный параметр. Если параметр не задан, сервис возвращает стандартную выдачу по умолчанию.

    2. Выполните gRPC-вызов, указав полученный ранее IAM-токен:

      grpcurl \
  -rpc-header "Authorization: Bearer <IAM-токен>" \
  -d @ < body.json \
  searchapi.api.cloud.yandex.net:443 yandex.cloud.searchapi.v2.WebSearchService/Search \
  > result.json

    В результате в файл result.json будет сохранен результат выполнения поискового запроса, содержащий в поле rawData XML или HTML ответ в кодировке Base64.

  2. В зависимости от запрошенного формата ответа, декодируйте результат из формата Base64:

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

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

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

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

См. также

Предыдущая
Мобильная выдача
Следующая
Выполнение поисковых запросов в отложенном режиме