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

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

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

API v1 сервиса Yandex Search API позволяет выполнять текстовый поиск и поиск по картинкам в поисковой базе Яндекса и получать результат поиска в формате XML или HTML (для текстового поиска) в синхронном режиме. Поисковая выдача зависит от заданных в запросе параметров.

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

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

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

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

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

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

  1. Создайте сервисный аккаунт.
  2. Назначьте созданному сервисному аккаунту роль search-api.executor.
  3. Создайте API-ключ для созданного сервисного аккаунта.
  4. Зарегистрируйтесь в сервисе Yandex Search API.

Сформируйте поисковый запрос

В зависимости от типа поиска, выбранного при регистрации в сервисе, указывайте в запросе подходящее имя домена:

  • yandex.ru — для типа поиска Русский;
  • yandex.com.tr — для типа поиска Турецкий;
  • yandex.com — для типа поиска Международный.

Для текстового поиска вы можете использовать GET-запросы.

Важно

Специальные символы, передаваемые в качестве значений параметров, необходимо заменять на соответствующие экранированные последовательности в соответствии с percent-encoding. Например, вместо знака равно = используйте последовательность %3D.

  1. Чтобы получить ответ в XML-формате, сформируйте GET-запрос в следующем виде:

    https://yandex.<домен>/search/xml
  ? [folderid=<идентификатор_каталога>]
  & [apikey=<API-ключ>]
  & [query=<текст_поискового_запроса>]
  & [lr=<идентификатор_региона_поиска>]
  & [l10n=<язык_уведомлений>]
  & [sortby=<тип_сортировки>]
  & [filter=<тип_фильтрации>]
  & [maxpassages=<количество_пассажей>]
  & [groupby=<параметры_группировки_результатов>]
  & [page=<номер_страницы>]

    Подробную информацию о параметрах запроса см. в разделе Параметры запроса.

    Пример запроса:

    https://yandex.ru/search/xml?folderid=b1gt6g8ht345********&apikey=your_service_account_API_key********&query=%3Ctable%3E&lr=11316&l10n=ru&sortby=rlv&filter=strict&groupby=attr%3Dd.mode%3Ddeep.groups-on-page%3D5.docs-in-group%3D3&maxpassages=3&page=4

    Этот запрос возвращает пятую страницу результатов поиска по запросу <table>. Тип поиска — Русский (yandex.ru). Регион поиска — Новосибирская область. Язык уведомлений — русский. К результатам поиска будет применен семейный фильтр. Количество пассажей — три. Результаты группируются по домену и сортируются по релевантности. Каждая группа содержит три документа, а количество групп, возвращаемых на одной странице, равно пяти.

  2. Отправьте запрос к поисковой базе Яндекса. Для этого воспользуйтесь утилитой cURL:

    curl \
  --request GET \
  --output result.xml \
  'https://yandex.ru/search/xml?folderid=b1gt6g8ht345********&apikey=your_service_account_API_key********&query=%3Ctable%3E&lr=11316&l10n=ru&sortby=rlv&filter=strict&groupby=attr%3Dd.mode%3Ddeep.groups-on-page%3D5.docs-in-group%3D3&maxpassages=3&page=4'

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

    Для того чтобы получить ответ в формате HTML, добавьте /html в путь URL запроса. Например: https://yandex.ru/search/xml/html?folderid=b1.... Подробнее см. в разделе Формат запроса.

Для текстового поиска вы можете использовать POST-запросы.

Важно

Специальные символы, передаваемые в качестве значений параметров в теле запроса, необходимо заменять на соответствующие экранированные последовательности в соответствии с XML-encoding. Например, вместо символа амперсанд & используйте последовательность &amp;.

  1. Чтобы получить ответ в XML-формате, сформируйте URL POST-запроса в следующем виде:

    https://yandex.<домен>/search/xml
  ? [folderid=<идентификатор_каталога>]
  & [filter=<тип_фильтрации>]
  & [lr=<идентификатор_региона_поиска>]
  & [l10n=<язык_уведомлений>]

    Подробную информацию о параметрах URL запроса см. в разделе Параметры запроса.

    Пример запроса:

    https://yandex.ru/search/xml?folderid=b1gt6g8ht345********&filter=strict&lr=11316&l10n=ru

  2. Подготовьте файл с телом запроса, например body.xml.

    Пример файла с телом запроса:

    <?xml version="1.0" encoding="UTF-8"?>
<request>
  <query>&lt;table&gt;</query>
  <sortby order="descending">tm</sortby>
  <maxpassages>2</maxpassages>
  <page>4</page>
  <groupings>
    <groupby attr="d" mode="deep" groups-on-page="10" docs-in-group="3" />
  </groupings>
</request>

    Подробную информацию о параметрах, задаваемых в теле запроса, см. в разделе Параметры тела запроса.

    Приведенный пример запроса возвращает пятую страницу результатов поиска по запросу <table>. Результаты сортируются по времени редактирования документа в порядке от наиболее свежего к наиболее старому. Тип поиска — Русский (yandex.ru). Регион поиска — Новосибирская область. К результатам поиска применен семейный фильтр. Результаты группируются по домену. Каждая группа содержит три документа, а количество групп, возвращаемых на одной странице, равно десяти. Максимальное количество пассажей на один документ — два.

  3. Отправьте запрос к поисковой базе Яндекса. Для этого воспользуйтесь утилитой cURL:

    curl \
  --request POST \
  --header "Authorization: Api-Key <API-ключ>" \
  --data "@body.xml" \
  --output result.xml \
  'https://yandex.ru/search/xml?folderid=b1gt6g8ht345********&filter=strict&lr=11316&l10n=ru'

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

    Для того чтобы получить ответ в формате HTML, добавьте /html в путь URL запроса. Например: https://yandex.ru/search/xml/html?folderid=b1.... Подробнее см. в разделе Формат запроса.

В настоящий момент для поиска по картинкам можно использовать только GET-запросы.

Важно

Специальные символы, передаваемые в качестве значений параметров, необходимо заменять на соответствующие экранированные последовательности в соответствии с percent-encoding. Например, вместо знака равно = используйте последовательность %3D.

  1. Сформируйте GET-запрос в следующем формате:

    https://yandex.<домен>/images-xml
  ? [folderid=<идентификатор_каталога>]
  & [apikey=<API-ключ>]
  & [text=<текст_поискового_запроса>]
  & [groupby=<настройки_группировки_результатов>]
  & [p=<номер_страницы>]
  & [fyandex=<фильтр_семейный_поиск>]
  & [site=<доменное_имя_сайта>]
  & [itype=<формат_картинки>]
  & [iorient=<тип_ориентации_изображения>]
  & [isize=<размер_картинки>]
  & [icolor=<цвет_картинки>]

    Подробную информацию о параметрах запроса см. в разделе Параметры запроса.

    Пример запроса:

    https://yandex.ru/images-xml?folderid=b1gt6g8ht345********&apikey=your_service_account_API_key********&text=funny+cats&groupby=attr=ii.groups-on-page=3&p=2&fyandex=1&site=somepics.ru&itype=jpg&iorient=horizontal&isize=medium&icolor=color

    Этот запрос возвращает третью страницу результатов поиска картинок по запросу funny cats. Тип поиска — Русский (yandex.ru). Сервис возвращает результаты для найденных на сайте somepics.ru цветных картинок среднего размера в формате JPG с горизонтальной ориентацией изображения. К результатам поиска будет применен фильтр «Семейный поиск». Страница будет содержать три группы результатов поиска.

  2. Отправьте запрос к поисковой базе картинок Яндекса. Для этого воспользуйтесь утилитой cURL:

    curl \
  --request GET \
  --output result.xml \
  'https://yandex.ru/images-xml?folderid=b1gt6g8ht345********&apikey=your_service_account_API_key********&text=funny+cats&groupby=attr=ii.groups-on-page=3&p=2&fyandex=1&site=somepics.ru&itype=jpg&iorient=horizontal&isize=medium&icolor=color'

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

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