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

Статья создана

Улучшена

Обновлена 31 июля 2025 г.

Перед началом работы
Подготовьте облако к работе
Выполните поисковый запрос

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

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

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

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

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

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

Чтобы воспользоваться примерами, установите утилиты cURL и jq, а также gRPCurl (если будете использовать gRPC API).

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

Создайте сервисный аккаунт, от имени которого будут выполняться запросы. Вы также можете использовать аккаунт на Яндексе или федеративный аккаунт, но для автоматизации предпочтительнее использовать сервисный аккаунт.
Назначьте аккаунту, от имени которого будут выполняться запросы, роль search-api.webSearch.user.
Получите IAM-токен, необходимый для аутентификации.

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

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

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

REST API

gRPC API

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

body.json

{
    "query": {
      "searchType": "<тип_поиска>",
      "queryText": "<текст_поискового_запроса>",
      "familyMode": "<значение_настройки_фильтрации_результатов>",
      "page": "<номер_страницы>",
      "fixTypoMode": "<значение_настройки_режима_исправления_опечаток>"
    },
    "sortSpec": {
      "sortMode": "<правило_сортировки_результатов>",
      "sortOrder": "<порядок_сортировки_результатов>"
    },
    "groupSpec": {
      "groupMode": "<метод_группировки_результатов>",
      "groupsOnPage": "<количество_групп_на_странице>",
      "docsInGroup": "<количество_документов_в_группе>"
    },
    "maxPassages": "<максимальное_количество_пассажей>",
    "region": "<идентификатор_региона>",
    "l10N": "<язык_уведомлений>",
    "folderId": "<идентификатор_каталога>",
    "responseFormat": "<формат_результата>",
    "userAgent": "<заголовок_User-Agent>"
}

Описание полей

searchType — тип поиска. Возможные значения:
- SEARCH_TYPE_RU — для типа поиска Русский.
- SEARCH_TYPE_TR — для типа поиска Турецкий.
- SEARCH_TYPE_COM — для типа поиска Международный.
- SEARCH_TYPE_KK — для типа поиска Казахский.
- SEARCH_TYPE_BE – для типа поиска Белорусский.
- SEARCH_TYPE_UZ — для типа поиска Узбекский.
queryText — текст поискового запроса. Максимальная длина запроса — 400 символов.
familyMode — фильтрация результатов. Необязательный параметр. Возможные значения:
- FAMILY_MODE_MODERATE — умеренный фильтр (значение по умолчанию). Из выдачи исключаются документы, относящиеся к категории «для взрослых», если запрос явно не направлен на поиск подобных ресурсов.
- FAMILY_MODE_NONE — фильтрация отключена. В выдачу включаются любые документы вне зависимости от содержимого.
- FAMILY_MODE_STRICT — семейный фильтр. Вне зависимости от поискового запроса из выдачи исключаются документы, относящиеся к категории «для взрослых», а также содержащие ненормативную лексику.
page — номер запрашиваемой страницы. Необязательный параметр. По умолчанию возвращается первая страница поисковой выдачи. Нумерация страниц начинается с нуля (первой странице соответствует значение 0).
fixTypoMode — значение настройки режима исправления опечаток в поисковом запросе. Необязательный параметр. Возможные значения:
- FIX_TYPO_MODE_ON — исправление опечаток включено (значение по умолчанию). Опечатки в тексте поискового запроса автоматически исправляются.
- FIX_TYPO_MODE_OFF — исправление опечаток отключено. Опечатки в тексте поискового запроса не исправляются, поиск выполняется в полном соответствии с переданным запросом.

sortMode — правило сортировки результатов поиска, которое определяет порядок выдачи результатов поиска. Необязательный параметр. Возможные значения:
- SORT_MODE_BY_RELEVANCE — сортировка по релевантности (значение по умолчанию).
- SORT_MODE_BY_TIME — сортировка по времени изменения документа.
sortOrder — порядок сортировки результатов поиска. Необязательный параметр. Возможные значения:
- SORT_ORDER_DESC — прямой порядок сортировки — от наиболее свежего к наиболее старому (значение по умолчанию).
- SORT_ORDER_ASC — обратный порядок сортировки — от наиболее старого к наиболее свежему.
groupMode — метод группировки результатов. Необязательный параметр. Возможные значения:
- GROUP_MODE_DEEP — группировка по доменам. Каждая группа содержит документы одного домена (значение по умолчанию).
- GROUP_MODE_FLAT — плоская группировка. Каждая группа содержит один документ.
groupsOnPage — максимальное количество групп, которые могут быть возвращены на одной странице результатов поиска. Необязательный параметр. Значение по умолчанию — 20.

При получении результата в формате XML допустимые значения — от 1 до 100, при получении результата в формате HTML — от 5 до 50.
docsInGroup — максимальное количество документов, которые могут быть возвращены в одной группе. Необязательный параметр. Допустимые значения — от 1 до 3. Значение по умолчанию — 1.
maxPassages — максимальное количество пассажей, которое может быть использовано при формировании сниппета к документу. Необязательный параметр. Допустимые значения — от 1 до 5. По умолчанию для каждого документа возвращается не более четырех пассажей с текстом запроса.
region — идентификатор страны или региона поиска, который влияет на правила ранжирования документов. Поддерживается только для типов поиска Русский и Турецкий.

Список идентификаторов часто используемых стран и регионов см. в разделе Регионы поиска.
l10N — язык уведомлений поискового ответа. Влияет на текст, передаваемый в теге found-docs-human и в сообщениях об ошибках. Необязательный параметр. Возможные значения зависят от выбранного типа поиска:
- Тип поиска Русский:
  - LOCALIZATION_RU — русский язык (значение по умолчанию).
  - LOCALIZATION_BE — белорусский язык.
  - LOCALIZATION_KK — казахский язык.
  - LOCALIZATION_UK — украинский язык.
- Тип поиска Турецкий:
  - LOCALIZATION_TR — турецкий язык.
- Тип поиска Международный:
  - LOCALIZATION_EN — английский язык.
folderId — идентификатор каталога пользователя или сервисного аккаунта, от имени которого вы будете выполнять запросы.
responseFormat — формат получения поисковой выдачи. Необязательный параметр. Возможные значения:
- FORMAT_XML — результат запроса будет передан в формате XML (значение по умолчанию).
- FORMAT_HTML — результат запроса будет передан в формате HTML.
userAgent — строка, содержащая заголовок User-Agent. Параметр позволяет получить поисковую выдачу, ориентированную на конкретные устройство и браузер, в том числе мобильную выдачу. Необязательный параметр. Если параметр не задан, сервис возвращает стандартную выдачу по умолчанию.

Список поддерживаемых параметров:

Примечание

Список поддерживаемых в запросе параметров зависит от того, в каком формате требуется получить результат: XML или HTML.

Параметр	Поддерживается при XML-ответе	Поддерживается при HTML-ответе
`searchType`
`queryText`
`familyMode`
`page`
`fixTypoMode`
`sortMode`
`sortOrder`
`groupMode`
`groupsOnPage`
`docsInGroup`
`maxPassages`
`region`
`l10N`
`folderId`
`responseFormat`
`userAgent`

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

curl \
  --request POST \
  --header "Authorization: Bearer <IAM-токен>" \
  --data "@body.json" \
  "https://searchapi.api.cloud.yandex.net/v2/web/search" \
  > result.json

Создайте файл с телом запроса (например, 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 — для типа поиска Международный.
- SEARCH_TYPE_KK — для типа поиска Казахский.
- SEARCH_TYPE_BE – для типа поиска Белорусский.
- SEARCH_TYPE_UZ — для типа поиска Узбекский.
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 — максимальное количество групп, которые могут быть возвращены на одной странице результатов поиска. Необязательный параметр. Значение по умолчанию — 20.

При получении результата в формате XML допустимые значения — от 1 до 100, при получении результата в формате HTML — от 5 до 50.
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. Параметр позволяет получить поисковую выдачу, ориентированную на конкретные устройство и браузер, в том числе мобильную выдачу. Необязательный параметр. Если параметр не задан, сервис возвращает стандартную выдачу по умолчанию.

Список поддерживаемых параметров:

Примечание

Параметр	Поддерживается при XML-ответе	Поддерживается при HTML-ответе
`search_type`
`query_text`
`family_mode`
`page`
`fix_typo_mode`
`sort_mode`
`sort_order`
`group_mode`
`groups_on_page`
`docs_in_group`
`max_passages`
`region`
`l10n`
`folder_id`
`response_format`
`user_agent`

Выполните 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.

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

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

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

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

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

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

См. также

Была ли статья полезна?

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

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

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

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

См. такжеСм. также

Была ли статья полезна?

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

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

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

См. также