Response format

In response to the search request, Yandex.XML returns an XML file in UTF-8 encoding that contains the search results.

Alert

For each search query, no more than 1000 results are returned. Depending on the value of the docs-in-group attribute, each result may contain from one to three documents. The maximum number of pages with search results is determined by the number of document groups returned on each page (the value of the groups-on-page attribute). For example, if the groups-on-page attribute is passed with the value “10“, no more than 100 pages containing search results can be made.

Files consist of the grouping tags request (general information about query parameters) and response (results of processing the search query).

Below you will find the general structure of a resulting XML document with sample values.

Warning

This structure is for illustrative purposes. It contains mutually exclusive elements.

<?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">Sorry, there are no results for this search</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 million pages found</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 million pages found</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>"<hlword>Yandex</hlword>" search engine and internet portal</title>
               <headline>Search the entire internet based on the user's region.</headline>
               <modtime>20060814T040000</modtime>
               <size>26938</size>
               <charset>utf-8</charset>
               <passages>
                  <passage><hlword>Yandex </hlword> — a search engine...</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&url=https%3A%2F%2Fwww.yandex.ru%2F&fmode=inject&mime=html&l10n=ru&sign=e3737561fc3d1105967d1ce619dbd3c7&keyno=0</saved-copy-url>
            </doc>
         </group>
      </grouping>
   </results>
</response>
</yandexsearch>

request

Generalized information about request parameters. May be omitted if the response contains errors.

The request tags are described in the table below.

The "request" group tags

Description

Attributes

query

Text of the search query that was passed.

None.

page

Number of the search results page returned. Numbering starts from zero (the first page corresponds to the value “0”).

None.

sortby

Parameters for sorting results Possible values:

  • “rlv” — By relevancy.
  • “tm” — By time when the document was changed.
  • order — Sorting order. The “descending” value (forward) is used by default. When sorting by change time, it can take the value “ascending” (reverse).
  • priority — For service use. Takes the value "no".

maxpassages

Maximum number of passages that can be passed in a single search result.

None.

groupings

Grouping.

Contains grouping parameters in the groupby tag. No attributes

None.

groupby

Grouping parameters for found search results.
  • mode — Grouping method.
  • attr — For service use.
  • groups-on-page — Maximum number of groups that can be returned per page of search results.
  • docs-in-group — Maximum number of documents that can be returned per group. Any group may contain fewer documents than the value set in this parameter.
  • curcateg — For service use. Takes the value “-1”.

The following example shows the content of the request grouping tag that is returned for the 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

Results of processing the search query for which information is provided in the request child tags.

Contains the date attribute, the date and time of the request in the format <year><month><day>T<hour><minute><second> in UTC.

Consists of the following sections:

General information about search results

The tags for the block with general information about search results are shown in the table below.

Tags with general information about search results

Description

Attributes

error

Error description.
Present only when the search request is processed incorrectly (for example, for an empty request, incorrect parameters, etc.).

In certain cases, it is mutually exclusive of other tags in the response grouping tag.

code — Error code.

reqid

Unique request ID.

None.

found

Approximation of the number of documents found for the query.

priority — For service use. Possible values:

  • “phrase”
  • “strict”
  • “all”

found-human

A string in the language corresponding to the search type selected. Contains information about the number of documents found and accompanying information.

None.

The misspell / reask block

Optional. Present if a typo was found (misspell) or corrected (reask) in the query.

The block tags are presented in the table below.

Tags for the misspell / reask blocks

Description

Attributes

misspell

Grouping.

Contains information about a possible typo in the search query.

None.

reask

Grouping.

Contains information about corrections made to the source query before searching for documents.

None.

rule

The type of error found in the query.

Possible values:

  • “Misspell” — Typo.
  • “KeyboardLayout” — Wrong keyboard layout.
  • “Volapyuk” — Query made in Russian using English transliteration. Used if the search type is set to “Russian (yandex.ru)”.

None.

source-text

Source text of the query.

The fragment of the search query that presumably contains an error is highlighted by the hlword tag.

None.

text-to-show

Optional (only for the reask grouping tag).

Contains the corrected text of the search query. In most cases it matches the value passed in the text tag.

None.

text

Corrected text of the search query.

None.

The results block

Optional. Present if results were found for the query.

The block tags are presented in the table below.

Tags for the results block

Description

Attributes

results

Grouping. Child tags contain information about search parameters and found documents.

None.

grouping

Grouping. Child tags contain information about search parameters and found documents.

Attributes reflect the grouping rules for found documents.

  • mode — Grouping method.
  • attr — For service use. Depends on the value of the mode attribute.
  • groups-on-page — Number of groups that can be returned per page of search results.
  • docs-in-group — Number of documents that can be returned per group.
  • curcateg — For service use. Takes the value “-1”.

found

Estimated number of groups formed.

priority — For service use. Possible values:

  • “phrase”
  • “strict”
  • “all”

found-docs

Approximation of the number of documents found for the query.

A more precise estimate compared to the value passed in the found tag for the block with general information about search results.

priority — For service use. Possible values:

  • “phrase”
  • “strict”
  • “all”

found-docs-human

A string in the language corresponding to the search type selected. Contains information about the number of documents found and accompanying information.

The value that is passed should be used when formatting search results.

None.

page

Number of the search results page returned. Numbering starts from zero (the first page corresponds to the value “0”).
  • first — Ordinal number of the first group with search results that is displayed on the page.
  • last — Ordinal number of the last group with search results that is displayed on the page.

group

Grouping.

Each group tag contains information about a found group of documents.

None.

categ

Identifying data about a group of found documents.

doccount

Approximation of the number of documents that are used for forming the group.

Documents that potentially may be included in the group are ranked according to the request conditions (the sortby parameter). Depending on the value of the docs-in-group parameter, from one to three of the first documents are included in the group.

None.

relevance

For service use.

priority — For service use.

doc

Grouping.

Each doc tag contains information about a found document.

Depending on the value of the docs-in-group parameter, each group can contain from one to three of the doc grouping tags.

name — Unique ID of a found document.

url

Address of a found document.

None.

domain

The domain that the found document is in.

None.

title

Title of the found document.

Words that are in the search query are highlighted with the hlword tag.

None.

headline

Optional. Document summary.

It is created using the HTML meta tag containing the name attribute with the “description” value.

None.

modtime

Date and time the document was changed, in the format:

<year><month><day>T<hour><minute><second>

Warning

This tag is optional and may be omitted.

None.

size

Size of the found document, in bytes.

None.

charset

Encoding of the found document.

None.

passages

Grouping tag that contains a list of document passages.

None.

passage

Passage with the document summary.

Words that are in the search query are highlighted with the hlword tag.

The maximum number of passages to be passed in a single passages tag is defined by the value of the maxpassages parameter for the search request.

None.

mime-type

The document type in accordance with RFC2046.

None.

properties

Grouping tag that contains document properties.

None.

_PassagesType

Passage type. Possible values:

  • “0” — Standard passage (created from the document text).
  • “1” — Passage based on the link text. It is used if the document was found via a link.

None.

lang

Optional.

Document language.

None.

saved-copy-url

Address of a saved copy of the document.

None.
Previous
POST requests
Next
Request for limits for the next day
In this article: