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

GET-запросы

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

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

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

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

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

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

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

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

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

]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]
=<язык уведомлений>] & [sortby
[no-highlight[

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

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

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

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

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

Формат: sortby=<тип сортировки>.order%3D<порядок сортировки>. Например, для обратной сортировки по дате необходимо использовать следующую конструкцию: sortby=tm.order%3Dascending.

]no-highlight]
=<тип сортировки>] & [filter
[no-highlight[

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

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

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

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

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

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

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

]no-highlight]
=<количество пассажей>] & [groupby
[no-highlight[

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

Параметры задаются через точку в формате:

attr%3D<служебный атрибут>.mode%3D<тип группировки>.groups-on-page%3D<количество групп на одной странице>.docs-in-group%3D<количество документов в каждой группе>

Описание параметров mode, attr, groups-on-page и docs-in-group приведено в разделе POST-запросы.

]no-highlight]
=<параметры группировки результатов>] & [page
[no-highlight[

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

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

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

]no-highlight]
=<номер страницы>] & [showmecaptcha
[no-highlight[

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

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

]no-highlight]
=<yes>]
user

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

key

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

query

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

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

lr

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

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

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

l10n

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

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

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

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

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

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

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

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

Формат: sortby=<тип сортировки>.order%3D<порядок сортировки>. Например, для обратной сортировки по дате необходимо использовать следующую конструкцию: sortby=tm.order%3Dascending.

filter

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

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

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

maxpassages

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

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

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

groupby

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

Параметры задаются через точку в формате:

attr%3D<служебный атрибут>.mode%3D<тип группировки>.groups-on-page%3D<количество групп на одной странице>.docs-in-group%3D<количество документов в каждой группе>

Описание параметров mode, attr, groups-on-page и docs-in-group приведено в разделе POST-запросы.

page

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

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

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

showmecaptcha
 

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

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

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

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

https://yandex.ru/search/xml?user=xml-search-user&key=03.44583456:c876e1b098gh65khg834ggg1jk4ll9j8&query=%3Ctable%3E&groupby=attr%3Dd.mode%3Ddeep.groups-on-page%3D5.docs-in-group%3D3&maxpassages=3&page=1