XML-формат ответа при текстовом поиске

Статья создана

Обновлена 30 января 2025 г.

Структура ответа
Параметры ответа
- request
- response

В ответ на текстовый поисковый запрос Yandex Search API может возвращать XML-файл в кодировке UTF-8, содержащий результаты поиска. Ответ в XML-формате возвращается для текстовых запросов с использованием как интерфейса API v1, так и интерфейса API v2.

Внимание

По каждому поисковому запросу возвращается не более 1000 результатов. В зависимости от значения атрибута docs-in-group, каждый результат может содержать от одного до трех документов. Максимальное количество страниц с результатами поиска определяется количеством групп документов, возвращаемых на каждой странице (значение атрибута groups-on-page). Например, если атрибут groups-on-page передан со значением 10, может быть сформировано не более 100 страниц, содержащих результаты поиска.

Файлы состоят из группирующих тегов request (обобщенная информация о параметрах запроса) и response (результаты обработки поискового запроса).

Ниже приведена общая структура результирующего XML-документа с примерами значений.

Важно

Структура является ознакомительной и содержит взаимоисключающие элементы.

Структура ответа

<?xml version="1.0" encoding="utf-8"?>
<yandexsearch version="1.0">
<request>
   <query>yandex</query>
   <page>0</page>
   <sortby order="descending" priority="no">rlv</sortby>
   <maxpassages>2</maxpassages>
   <groupings>
      <groupby  attr="d" mode="deep" groups-on-page="10" docs-in-group="3" curcateg="-1" />
   </groupings>
</request>
<response date="20120928T103130">
   <error code="15">Искомая комбинация слов нигде не встречается</error>
   <reqid>1348828873568466-1289158387737177180255457-3-011-XML</reqid>
   <found priority="phrase">206775197</found>
   <found priority="strict">206775197</found>
   <found priority="all">206775197</found>
   <found-human>Нашлось 207 млн ответов</found-human>
   <misspell>
      <rule>Misspell</rule>
      <source-text>yande<hlword>xx</hlword></source-text>
      <text>yandex</text>
   </misspell>
   <reask>
      <rule>Misspell</rule>
      <source-text><hlword>yn</hlword>dex</source-text>
      <text-to-show>yandex</text-to-show>
      <text>yandex</text>
   </reask>
   <results>
      <grouping attr="d" mode="deep" groups-on-page="10" docs-in-group="3" curcateg="-1">
         <found priority="phrase">45094</found>
         <found priority="strict">45094</found>
         <found priority="all">45094</found>
         <found-docs priority="phrase">192685602</found-docs>
         <found-docs priority="strict">192685602</found-docs>
         <found-docs priority="all">192685602</found-docs>
         <found-docs-human>нашёл 193 млн ответов</found-docs-human>
         <page first="1" last="10">0</page>
         <group>
            <categ attr="d" name="UngroupVital223.ru" />
            <doccount>34</doccount>
            <relevance priority="all" />
            <doc id="ZD831E1113BCFDD95">
               <relevance priority="phrase" />
               <url>https://www.yandex.ru/</url>
               <domain>www.yandex.ru</domain>
               <title>&quot;<hlword>Яндекс</hlword>&quot; - поисковая система и интернет-портал</title>
               <headline>Поиск по всему интернету с учетом региона пользователя.</headline>
               <modtime>20060814T040000</modtime>
               <size>26938</size>
               <charset>utf-8</charset>
               <passages>
                  <passage><hlword>Яндекс</hlword> — поисковая машина, способная по вашему запросу...</passage>
               </passages>
               <properties>
                   <_PassagesType>0</_PassagesType>
                   <lang>ru</lang>
               </properties>
               <mime-type>text/html</mime-type>
               <saved-copy-url>https://hghltd.yandex.net/yandbtm?text=yandex&amp;url=https%3A%2F%2Fwww.yandex.ru%2F&amp;fmode=inject&amp;mime=html&amp;l10n=ru&amp;sign=e3737561fc3d1105967d1ce6********&amp;keyno=0</saved-copy-url>
            </doc>
         </group>
      </grouping>
   </results>
</response>
</yandexsearch>

Параметры ответа

Обобщенная информация о параметрах запроса. Может отсутствовать, если ответ содержит ошибки.

request

Теги группы request	Описание	Атрибуты
query	Текст переданного поискового запроса	Отсутствуют.
page	Номер возвращенной страницы результатов поиска. Нумерация начинается с нуля (первой странице соответствует значение `0`).	Отсутствуют.
sortby	Параметры сортировки результатов. Возможные значения: `rlv` — по релевантности; `tm` — по времени изменения документа.	`order` — порядок сортировки. По умолчанию используется значение `descending` (прямой). При сортировке по времени изменения может принимать значение `ascending` (обратный); `priority` — служебный. Принимает значение «no».
maxpassages	Максимальное количество пассажей, которые могут быть переданы в одном результате поиска	Отсутствуют.
groupings	Группирующий Содержит параметры группировок в теге `groupby`	Отсутствуют.
groupby	Параметры группировки найденных результатов поиска	`mode` — метод группировки; `attr` — служебный; `groups-on-page` — максимальное количество групп, которые могут быть возвращены на одной странице результатов поиска; `docs-in-group` — максимальное количество документов, которые могут быть возвращены в одной группе. Любая группа может содержать меньшее количество документов, чем указанное в данном параметре значение; `curcateg` — служебный. Принимает значение `-1`.

В следующем примере приведено содержимое группирующего тега request, возвращаемого для запроса:

https://yandex.com.tr/search/xml?l10n=en&user=xml-search-user&key=03.79031114:b631r9j587dkl4jko987hgg7********&query=%22has%20sample%20applications%20for%20the%20most%20popular%20programming%22&sortby=tm&maxpassages=2&groupby=attr%3Dd.mode%3Ddeep.groups-on-page%3D5.docs-in-group%3D3&maxpassages=3&page=1

<request>
  <query>"has sample applications for the most popular programming"</query>
  <page>1</page>
  <sortby order="descending" priority="no">tm</sortby>
  <maxpassages>2</maxpassages>
  <groupings>
    <groupby attr="d" mode="deep" groups-on-page="5" docs-in-group="3" curcateg="-1"/>
  </groupings>
</request>

response

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

Содержит атрибут date — дата и время запроса в формате <год><месяц><день>Т<час><минута><секунда> по UTC.

Состоит из следующих блоков:

Общая информация о результатах поиска

Теги блока с общей информацией о результатах поиска представлены в таблице ниже.

Теги общей информации о результатах поиска	Описание	Атрибуты
error	Описание ошибки. Присутствует только в случае некорректной обработки поискового запроса (например, при пустом запросе, некорректных параметрах и т.п.). В некоторых случаях является взаимоисключающим с прочими тегами группирующего тега `response`.	`code` — код ошибки.
reqid	Уникальный идентификатор запроса	Отсутствуют.
found	Приблизительная оценка количества документов, найденных по запросу	`priority` — служебный. Возможные значения: `phrase`; `strict`; `all`.
found-human	Строка на языке, соответствующем выбранному типу поиска. Содержит сведения о количестве найденных документов и сопутствующую информацию	Отсутствуют.

Блок misspell / reask

Опциональный. Присутствует, если в запросе найдена (misspell) или исправлена (reask) опечатка.

Теги блока представлены в таблице ниже.

Теги блоков misspell / reask	Описание	Атрибуты
misspell	Группирующий. Содержит сведения о возможной опечатке в поисковом запросе.	Отсутствуют.
reask	Группирующий. Содержит сведения об исправлении, внесенном в исходный запрос перед поиском документов.	Отсутствуют.
rule	Тип ошибки, найденной в запросе. Возможные значения: `Misspell` — опечатка. `KeyboardLayout` — ошибка в раскладке клавиатуры. `Volapyuk` — запрос задан на русском языке в английской транслитерации. Используется, если в качестве типа поиска выбрано значение Русский (yandex.ru).	Отсутствуют.
source-text	Исходный текст запроса. Фрагмент поискового запроса, предположительно содержащий ошибку, выделяется тегом `hlword`.	Отсутствуют.
text-to-show	Опциональный (только для группирующего тега `reask`). Содержит исправленный текст поискового запроса. В большинстве случаев совпадает со значением, передаваемым в теге text.	Отсутствуют.
text	Исправленный текст поискового запроса	Отсутствуют.

Блок results

Опциональный. Присутствует, если по запросу найдены результаты.