Выполнение поисковых запросов с помощью API v1
API v1 сервиса Search API позволяет выполнять текстовый поиск и поиск по картинкам в поисковой базе Яндекса и получать результат поиска в формате XML или HTML (для текстового поиска) в синхронном режиме. Поисковая выдача зависит от заданных в запросе параметров.
Перед началом работы
Зарегистрируйтесь в Yandex Cloud и создайте платежный аккаунт:
- Перейдите в консоль управления
, затем войдите в Yandex Cloud или зарегистрируйтесь. - На странице Yandex Cloud Billing
убедитесь, что у вас подключен платежный аккаунт, и он находится в статусеACTIVE
илиTRIAL_ACTIVE
. Если платежного аккаунта нет, создайте его и привяжите к нему облако.
Если у вас есть активный платежный аккаунт, вы можете создать или выбрать каталог, в котором будет работать ваша инфраструктура, на странице облака
Подробнее об облаках и каталогах.
Подготовьте облако к работе
- Создайте сервисный аккаунт.
- Назначьте созданному сервисному аккаунту роль
search-api.executor
. - Создайте API-ключ для созданного сервисного аккаунта.
- Зарегистрируйтесь в сервисе Search API.
Сформируйте поисковый запрос
В зависимости от типа поиска, выбранного при регистрации в сервисе, указывайте в запросе подходящее имя домена:
yandex.ru
— для типа поискаРусский
;yandex.com.tr
— для типа поискаТурецкий
;yandex.com
— для типа поискаМеждународный
.
Для текстового поиска вы можете использовать GET-запросы.
Важно
Специальные символы, передаваемые в качестве значений параметров, необходимо заменять на соответствующие экранированные последовательности в соответствии с percent-encoding. Например, вместо знака равно =
используйте последовательность %3D
.
-
Чтобы получить ответ в 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). Регион поиска — Новосибирская область. Язык уведомлений — русский. К результатам поиска будет применен семейный фильтр. Количество пассажей — три. Результаты группируются по домену и сортируются по релевантности. Каждая группа содержит три документа, а количество групп, возвращаемых на одной странице, равно пяти. -
Отправьте запрос к поисковой базе Яндекса. Для этого воспользуйтесь утилитой 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. Например, вместо символа амперсанд &
используйте последовательность &
.
-
Чтобы получить ответ в 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
-
Подготовьте файл с телом запроса, например
body.xml
.Пример файла с телом запроса:
<?xml version="1.0" encoding="UTF-8"?> <request> <query><table></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). Регион поиска — Новосибирская область. К результатам поиска применен семейный фильтр. Результаты группируются по домену. Каждая группа содержит три документа, а количество групп, возвращаемых на одной странице, равно десяти. Максимальное количество пассажей на один документ — два. -
Отправьте запрос к поисковой базе Яндекса. Для этого воспользуйтесь утилитой 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
.
-
Сформируйте 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 с горизонтальной ориентацией изображения. К результатам поиска будет применен фильтр «Семейный поиск». Страница будет содержать три группы результатов поиска. -
Отправьте запрос к поисковой базе картинок Яндекса. Для этого воспользуйтесь утилитой 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.