Документация

POST-запросы

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

URL запроса

https://yandex.<домен>/search/xml ? 
user
[no-highlight[

Имя пользователя. Должно совпадать с логином в Яндекс.Паспорте, заданным при регистрации.

]no-highlight]
=<имя пользователя> & key
[no-highlight[

Значение API-ключа, выданного при регистрации.

]no-highlight]
=<API-ключ> & filter
[no-highlight[

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

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

Если параметр не задан, используется умеренная фильтрация.

]no-highlight]
=<тип фильтрации> & [lr
[no-highlight[

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

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

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

]no-highlight]
=<идентификатор региона поиска>] & [l10n
[no-highlight[

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

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

  • «русский (yandex.ru)» — «ru» (русский), «uk» (украинский), «be» (белорусский), «kk» (казахский). Если не задан, уведомления передаются на русском языке;
  • «турецкий (yandex.com.tr)» — поддерживается только значение «tr» (турецкий);
  • «мировой (yandex.com)» — поддерживается только значение «en» (английский).
]no-highlight]
=<язык уведомлений>] & [showmecaptcha
[no-highlight[

Инициирует проверку пользователя для возможной защиты от роботов.

Единственное используемое значение — «yes».

]no-highlight]
=<yes>]
user

Имя пользователя. Должно совпадать с логином в Яндекс.Паспорте, заданным при регистрации.

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» (английский).
showmecaptcha
 

Инициирует проверку пользователя для возможной защиты от роботов.

Единственное используемое значение — «yes».

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

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

query

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

На запрос наложены следующие ограничения: максимальная длина запроса — 400 символов; максимальное количество слов — 40.

sortby

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

  • «rlv» — по релевантности;
  • «tm» — по времени изменения документа.

Если параметр не задан, результаты сортируются по релевантности.

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

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

maxpassages

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

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

Если параметр не задан, для каждого документа возвращается не более четырех пассажей с текстом запроса.

page

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

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

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

Группирующий тег groupings. Дочерний тег содержит параметры группировки результатов.

groupby

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

Содержит следующие атрибуты:

  • mode — метод группировки. Возможные значения:

    • «flat» — плоская группировка. Каждая группа содержит один документ. Передается с пустым значением параметра attr («""»);
    • «deep» — группировка по доменам. Каждая группа содержит документы одного домена. Передается со значением «d» параметра attr.

    Если параметр не задан, используется плоская группировка;

  • attr — служебный атрибут. Зависит от значения атрибута mode;

  • groups-on-page — максимальное количество групп, которые могут быть возвращены на одной странице результатов поиска. Допустимые значения — от 1 до 100;
  • docs-in-group — максимальное количество документов, которое могут быть возвращены в одной группе. Допустимые значения — от 1 до 3.
Совет. 

При необходимости используйте Валидатор XML-фидов сервиса Яндекс.Вебмастер. Подробные сведения о валидации приведены в приложении.

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

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

URL запроса:

https://yandex.ru/search/xml?user=xml-search-user&key=03.44583456:c876e1b098gh65khg834ggg1jk4ll9j8

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

<?xml version="1.0" encoding="UTF-8"?> 
<request>   
<query>%3Ctable%3E</query>
      <sortby>tm</sortby>
      <maxpassages>2</maxpassages>
      <page>2</page> 
      <groupings>
      <groupby attr="d" mode="deep" groups-on-page="10" docs-in-group="3" /> 
</groupings>        
</request>