Формат ответа

В ответ на поисковый запрос Яндекс.XML возвращает XML-файл в кодировке UTF-8, содержащий результаты поиска.

Ограничение.

По каждому поисковому запросу возвращается не более 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=e3737561fc3d1105967d1ce619dbd3c7&amp;keyno=0</saved-copy-url>
            </doc>
         </group>
      </grouping>
   </results>
</response>
</yandexsearch>

request

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

Теги 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:b631r9j587dkl4jko987hgg7bn2kl8a2&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

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

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

Теги блока results Описание Атрибуты
results

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

Отсутствуют.
grouping

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

Атрибуты отражают правила группировки найденных документов.

  • mode — метод группировки;
  • attr — служебный. Зависит от значения атрибута mode;
  • groups-on-page — количество групп, возвращаемых на одной странице результатов поиска;
  • docs-in-group — количество документов, возвращаемых в одной группе;
  • curcateg — служебный. Принимает значение «-1».
found Приблизительная оценка количества сформированных групп.

priority — служебный. Возможные значения:

  • «phrase»;
  • «strict»;
  • «all».

found-docs

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

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

priority — служебный. Возможные значения:

  • «phrase»;
  • «strict»;
  • «all».

found-docs-human

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

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

Отсутствуют.
page Номер возвращенной страницы результатов поиска. Нумерация начинается с нуля (первой странице соответствует значение «0»).
  • first — порядковый номер первой группы с результатами поиска, отображаемой на странице;
  • last — порядковый номер последней группы с результатами поиска, отображаемой на странице.
group

Группирующий.

Каждый тег group содержит сведения о найденной группе документов.

Отсутствуют.
categ Идентификационные данные о группе найденных документов.
  • attr — служебный. Должен совпадать со значением, переданным в запросе;
  • name — уникальный идентификатор группы.
doccount

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

Документы, претендующие на включение в группу, ранжируются в соответствии с условиями запроса (параметр sortby). В зависимости от значения параметра docs-in-group в группу включается от одного до трех первых документов.

Отсутствуют.
relevance

Служебный.

priority — служебный.

doc

Группирующий.

Каждый тег doc содержит информацию о найденном документе.

В зависимости от значения параметра docs-in-group каждая группа может содержать от одного до трех группирующих тегов doc.

id — уникальный идентификатор найденного документа.
url Адрес найденного документа. Отсутствуют.
domain Домен, на котором расположен найденный документ. Отсутствуют.
title

Заголовок найденного документа.

Слова, входящие в поисковый запрос, выделяются тегом hlword.

Отсутствуют.
headline

Опциональный. Аннотация документа.

Для формирования используется HTML-тег meta, содержащий атрибут name со значением «description».

Отсутствуют.
modtime

Дата и время изменения документа в формате:

<год><месяц><день>Т<час><минута><секунда>
Внимание.

Тег является необязательным и в некоторых случаях может отсутствовать.

Отсутствуют.
size Размер найденного документа в байтах. Отсутствуют.
charset Кодировка найденного документа. Отсутствуют.
passages Группирующий тег, содержащий список пассажей документа. Отсутствуют.
passage

Пассаж с аннотацией к документу.

Слова, входящие в поисковый запрос, выделяются тегом hlword.

Максимальное количество пассажей, передаваемых в одном теге passages, определяется значением параметра maxpassages поискового запроса.

Отсутствуют.
mime-type Тип документа в соответствии с RFC2046. Отсутствуют.
properties Группирующий тег, содержащий свойства документа. Отсутствуют.
_PassagesType

Тип пассажа. Возможные значения:

  • «0» — стандартный пассаж (сформирован из текста документа);
  • «1» — пассаж на основе текста ссылки. Используется, если документ найден по ссылке.
Отсутствуют.
lang

Опциональный.

Язык документа.

Отсутствуют.
saved-copy-url Адрес сохраненной копии документа. Отсутствует.