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

Примечание

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

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

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

XML-файлы состоят из группирующих тегов 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

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

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

Теги блока 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

Адрес сохраненной копии документа

Отсутствует.

См. также

Предыдущая
Текстовый поиск
Следующая
HTML-ответ