Текстовый поиск

Текстовый поиск позволяет отправлять запросы к поисковой базе Яндекса и получать результаты в формате XML или HTML. Запросы можно выполнять через REST API, gRPC API или Yandex AI Studio SDK. Текстовый поиск доступен в синхронном и отложенном режиме.

Форматы результата поиска

В поисковом запросе вы можете указать, в каком формате хотите получить результат. По умолчанию результаты возвращаются в виде XML-файл в кодировке UTF-8, содержащий результаты поиска. XML-файл содержит только результаты поиска без дополнительных элементов поисковой выдачи. Если же вы хотите получить полный результат, соответствующий поисковой выдаче на главной странице Яндекс Поиска в режиме инкогнито, в параметрах запроса укажите формат HTML. Кроме документов, формат HTML также включает в себя рекламу, быстрые ответы и другие элементы, которые могут появиться в поисковой выдаче (пример).

Важно

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

По каждому поисковому запросу возвращается не более 250 результатов. Количество результатов поиска на странице задаётся в параметре groupsOnPage. Например, если groupsOnPage равен 10, может быть сформировано не более 25 страниц, а если 50 — не более 5 страниц.

Параметры запроса

Имена полей тела запроса различаются в REST API и gRPC API: в REST API используется CamelCase, в gRPC API — snake_case.

Параметр REST API

Параметр gRPC API

XML

HTML

Описание

searchType

search_type

yes

yes

Тип поиска. Возможные значения:

  • SEARCH_TYPE_RU — тип поиска Русский.
  • SEARCH_TYPE_TR — тип поиска Турецкий.
  • SEARCH_TYPE_COM — тип поиска Международный.
  • SEARCH_TYPE_KK — тип поиска Казахский.
  • SEARCH_TYPE_BE — тип поиска Белорусский.
  • SEARCH_TYPE_UZ — тип поиска Узбекский.

queryText

query_text

yes

yes

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

familyMode

family_mode

yes

yes

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

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

page

page

yes

yes

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

fixTypoMode

fix_typo_mode

yes

yes

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

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

sortMode

sort_mode

yes

yes

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

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

sortOrder

sort_order

yes

no

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

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

groupMode

group_mode

yes

no

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

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

groupsOnPage

groups_on_page

yes

yes

Максимальное количество групп на одной странице результатов. Необязательный параметр. Значение по умолчанию — 20. Допустимые значения: от 1 до 100 для XML, от 5 до 50 для HTML.

docsInGroup

docs_in_group

yes

no

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

maxPassages

max_passages

yes

no

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

region

region

yes

yes

Идентификатор страны или региона поиска, влияющий на правила ранжирования. Поддерживается только для типов поиска Русский и Турецкий. Актуальный список идентификаторов можно получить, выполнив запрос GetRegionsTree. Список наиболее часто используемых идентификаторов доступен в разделе Регионы поиска.

l10n

l10n

yes

no

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

  • Для Русский: LOCALIZATION_RU (по умолчанию), LOCALIZATION_BE, LOCALIZATION_KK, LOCALIZATION_UK.
  • Для Турецкий: LOCALIZATION_TR.
  • Для Международный: LOCALIZATION_EN.

folderId

folder_id

yes

yes

Идентификатор каталога пользователя или сервисного аккаунта, от имени которого выполняются запросы.

responseFormat

response_format

yes

yes

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

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

userAgent

user_agent

yes

yes

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

resultsWithin

results_within

no

yes

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

  • WITHIN_ALL_TIME: документы за все время (по умолчанию).
  • WITHIN_1_DAY: документы за последние 24 часа.
  • WITHIN_2_WEEKS: документы за последние 2 недели.
  • WITHIN_1_MONTH: документы за последний месяц.

Синхронный режим поиска

В синхронном режиме запросы можно выполнять с помощью Yandex AI Studio SDK, REST API и gRPC API.

В ответ на запрос в синхронном режиме сервис Yandex Search API в зависимости от заданных параметров запроса возвращает результат в формате XML или HTML. Результат возвращается в поле rawData ответа в кодировке Base64.

Примечание

Ответ не содержит обязательных полей. Поле может отсутствовать в ответе, если не содержит значащей информации.

Отложенный (асинхронный) режим поиска

В отложенном режиме запросы можно выполнять с помощью Yandex AI Studio SDK, REST API и gRPC API.

В ответ на отложенный запрос Yandex Search API возвращает объект, содержащий информацию об операции: статус, идентификатор, время вызова и т.д. Зная идентификатор объекта Operation, вы можете отследить статус обработки запроса, а также получить результат по завершении обработки.

В зависимости от заданных параметров запроса результат вернется в поле response.rawData ответа в формате XML или HTML.

Формат ответа при асинхронном поиске

В ответ на отложенный запрос API Yandex Search API возвращает объект Operation следующего вида:

Примечание

Ответ не содержит обязательных полей. Поле может отсутствовать в ответе, если не содержит значащей информации.

{
         "done": true,
         "response": {
          "@type": "type.googleapis.com/yandex.cloud.searchapi.v2.WebSearchResponse",
          "rawData": "<тело_XML_ответа_в_кодировке_Base64>"
         },
         "id": "<идентификатор_объекта_operation>",
         "description": "WEB search async",
         "createdAt": "2024-10-03T08:07:07Z",
         "createdBy": "<идентификатор_субъекта>",
         "modifiedAt": "2024-10-03T08:12:09Z"
        }
        
{
          "id": "<идентификатор_объекта_operation>",
          "description": "WEB search async",
          "createdAt": "2024-10-03T08:07:07Z",
          "createdBy": "<идентификатор_субъекта>",
          "modifiedAt": "2024-10-03T08:12:09Z",
          "done": true,
          "response": {
            "@type": "type.googleapis.com/yandex.cloud.searchapi.v2.WebSearchResponse",
            "rawData": "<тело_XML_ответа_в_кодировке_Base64>"
          }
        }

Объект response внутри объекта Operation становится доступен только после того, как запрос был выполнен на стороне Yandex Search API, а значение поля done (статус операции) изменилось на true.

Значение поля rawData объекта response в зависимости от параметров запроса содержит XML или HTML ответ в кодировке Base64.

Примеры использования

Полезные ссылки

Каталог — пространство, в котором содержатся ресурсы Yandex Cloud. Для аутентификации в AI Studio необходим идентификатор каталога. Чтобы его получить, в интерфейсе AI Studio наведите указатель на название каталога, расположенное в верхней части экрана, и нажмите image. Идентификатор будет скопирован в буфер обмена.

image

Предыдущая
Начало работы
Следующая
Генеративный поиск