Связаться с намиПодключиться

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

Статья создана
Обновлена 21 октября 2024 г.

В ответ на текстовый поисковый запрос 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

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

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

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

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

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

См. также

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