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

POST-запросы

Статья создана
Обновлена 21 октября 2024 г.

Интерфейс API v1 сервиса Search API позволяет выполнять запросы к поисковой базе Яндекса с заданным набором параметров. Параметры поиска можно передавать в сервис в виде HTTP-запроса методом POST. Search API формирует ответ в виде документа в формате XML или в формате HTML.

Чтобы воспользоваться поиском, при регистрации в сервисе укажите список IP-адресов, с которых будут выполняться запросы к сервису, и выберите нужный тип поиска. В зависимости от выбранного типа поиска указывайте в запросе подходящее имя домена:

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

Для выполнения запросов необходим сервисный аккаунт с ролью search-api.executor и созданный для него API-ключ.

Формат запроса

Важно

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

URL запроса к сервису Search API различается в зависимости от того, в каком формате требуется получить результат: XML или HTML.

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

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

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

Идентификатор каталога и API-ключ

Поле folderid содержит идентификатор каталога сервисного аккаунта, от имени которого вы будете отправлять запросы. Вместе с параметром apikey — значением API-ключа сервисного аккаунта — необходим для аутентификации пользователя.

Значение API-ключа передавайте в заголовке Authorization в формате:

Authorization: Api-Key <API-ключ>

Фильтрация результатов

Поле filter содержит правило фильтрации результатов поиска и определяет, исключать ли из результатов поиска какие-либо документы. Возможные значения:

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

Идентификатор региона поиска

Поддерживается только для типов поиска Русский и Турецкий.

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

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

Язык уведомлений

Поле l10n определяет язык уведомлений поискового ответа влияет на текст, передаваемый в теге found-docs-human и в сообщениях об ошибках.

Возможные значения зависят от используемого типа поиска.

Тип поиска Русский (yandex.ru):

  • ru — русский язык (значение по умолчанию);
  • uk — украинский язык;
  • be — белорусский язык;
  • kk — казахский язык.

Тип поиска Турецкий (yandex.com.tr) — поддерживается только значение tr (турецкий язык).

Тип поиска Международный (yandex.com) — поддерживается только значение en (английский язык).

Формат тела запроса

<?xml version="1.0" encoding="<кодировка_XML-файла>"?>
<request>
<!--Группирующий тег-->
  <query>
     <!--Текст поискового запроса-->
  </query>
  <sortby order="<!--порядок сортировки документов-->">
     <!--Тип сортировки результатов поиска-->
  </sortby>
  <groupings>
    <!--Параметры группировки в дочерних тегах-->
    <groupby attr="d" mode="deep" groups-on-page="10" docs-in-group="1" />
  </groupings>
  <maxpassages>
    <!--максимальное количество пассажей-->
  </maxpassages>
  <page>
    <!--Номер запрашиваемой страницы результатов поиска-->
  </page>
</request>

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

Группирующий тег

Группирующий тег <request> объединяет все содержимое тела запроса. Дочерние теги содержат параметры поискового запроса.

Запрос

Текст поискового запроса передается в поле query. При обработке учитываются особенности языка запросов Яндекса. Вместо специальных символов используйте соответствующие экранированные последовательности.

Максимальная длина запроса — 40 слов и 400 символов.

Сортировка результатов

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

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

При сортировке по времени изменения параметр может содержать атрибут order — порядок сортировки документов:

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

Максимальное количество пассажей

Пассаж — это фрагмент найденного документа, содержащий слова запроса. Пассажи используются для формирования сниппетов — текстовых аннотаций к найденному документу.

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

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

Номер запрашиваемой страницы

Поле page содержит номер запрашиваемой страницы поисковой выдачи. Номер определяет диапазон позиций документов, возвращаемых по запросу. Нумерация страниц начинается с нуля (первой странице соответствует значение 0).

Например, если количество документов, возвращаемых на странице, равно n, а в параметре передано значение p, то в результаты поиска будут включены документы, находящиеся в диапазоне позиций выдачи от p*n+1 до p*n+n включительно.

По умолчанию возвращается первая страница поисковой выдачи.

Группирующий тег

Группирующий тег groupings объединяет параметры группировки результатов.

Группировка результатов groupby

Параметр groupby объединяет правила группировки результатов. Группировка используются для объединения документов одного домена в контейнер. В рамках контейнера документы ранжируются по правилам сортировки, определенным в поле sortby. Результаты, переданные в контейнере, могут быть использованы для включения в поисковую выдачу нескольких документов одного домена.

Возможные параметры groupby:

  • mode — метод группировки. Возможные значения:
    • flat — плоская группировка. Каждая группа содержит один документ. Передается с пустым значением параметра attr.
    • deep — группировка по доменам. Каждая группа содержит документы одного домена. Передается со значением d параметра attr.
      Если параметр не задан, используется группировка по доменам.
  • attr — служебный атрибут. Зависит от значения атрибута mode.
  • groups-on-page — максимальное количество групп, которые могут быть возвращены на одной странице результатов поиска. Допустимые значения — от 1 до 100.
  • docs-in-group — максимальное количество документов, которые могут быть возвращены в одной группе. Допустимые значения — от 1 до 3.

Пример POST-запроса

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

URL запроса к сервису Search API различается в зависимости от того, в каком формате требуется получить результат: XML или HTML.

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

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

Тело запроса:

<?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>

См. также

Предыдущая
GET-запросы
Следующая
HTML-ответ