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

POST-запросы

Статья создана
Обновлена 4 июня 2025 г.

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

Важно

Интерфейс API v1 устарел и перестанет поддерживаться 30 сентября 2025 года. До этого времени переведите свои проекты на интерфейс API v2, а также используйте API v2 в новых проектах.

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

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

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

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

Важно

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Параметр l10n не поддерживается при получении результата в HTML-формате.

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

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

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

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

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

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

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

Примечание

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

<?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 не поддерживается при получении результата в HTML-формате.

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

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

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

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

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

Параметр maxpassages не поддерживается при получении результата в HTML-формате.

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

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

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

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

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

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

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

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

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

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

Параметр groupby не поддерживается при получении результата в HTML-формате.

Параметр 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 запроса к сервису Yandex 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

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

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

См. также