GET requests

Attention. Special characters that are passed as parameter values must be replaced with the appropriate escape sequences for percent-encoding. For example, instead of the equal sign (“=”), the escape sequence “%3D” must be used.

Request format

https://yandex.<domain>/search/xml
 ? [user=<user name>]
 & [key=<API key>]
 & [query=<search query text>]
 & [lr=<ID of the search country/region>]
 & [l10n=<notification language>]
 & [sortby=<type of sorting>]
 & [filter=<filter type>]
 & [maxpassages=<number of passages>]
 & [groupby=<parameters for grouping results>]
 & [page=<page number>]
 & [showmecaptcha=<yes>]
Query parameters
user

User name. Must match the login for Yandex.Passport that was set during registration.

key

Value of the API key that was issued during registration.

query

Text of the search query. Instead of special symbols, the corresponding escape sequences must be used.

The query has the following restrictions: maximum query length — 400 characters; maximum number of words — 40.

lr

Supported only for “Russian” and “Turkish” search types.

ID of the country or region to search. Determines the rules for ranking documents. For example, if we pass the value “11316” in this parameter (Novosibirsk region), when generating search results, a formula is used that is defined for the Novosibirsk region.

A list of IDs of common countries and regions is provided in the appendix.

l10n

The notification language for the search response. It affects the text that is passed in the found-docs-human tag, as well as in error messages.

Acceptable values depend on the type of search used:

  • “Russian (yandex.ru)”“ru” (Russian), “uk” (Ukrainian), “be” (Belarusian), “kk” (Kazakh). If omitted, notifications are sent in Russian.
  • “Turkish (yandex.com.tr)” — Supports only the value “tr” (Turkish).
  • “Worldwide (yandex.com)” — Supports only the value “en” (English).
sortby

Rules for sorting search results. Possible values:

  • “rlv” — By relevancy.
  • “tm” — By time when the document was changed.

If omitted, results are sorted by relevancy.

When sorting by change time, the parameter may contain the order attribute, which is the order for sorting documents. Possible values:

  • “descending” — Forward (from most recent to oldest). Used by default.
  • “ascending” — Reverse (from oldest to most recent).

Format: sortby=<type of sorting>.order%3D<sort order>. For example, for reverse sorting by date, use the following: sortby=tm.order%3Dascending.

filter

Rules for filtering search results (excluding documents from search results based on one of the rules). Possible values:

  • “none” — Filtering is disabled. The output includes any documents, regardless of their content.
  • “moderate” — Moderate filtering. The output excludes documents that fall into the “adults only” category, if the search is not explicitly directed at finding these types of resources.
  • “strict” — Family filter. Regardless of the search query, the output excludes documents that fall into the “adults only” category, as well as those that contain foul language.

If the parameter is omitted, moderate filtering is used.

maxpassages

The maximum number of passages that can be used when creating a snippet for the document. A passage is an excerpt from a found document that contains the query words. Passages are used for creating snippets, which are textual annotations to found documents.

Acceptable values — from 1 to 5. The search result may contain fewer passages than the value set for this parameter.

If the parameter is omitted, no more than four passages with the query text are returned for each document.

groupby

Set of parameters that define the rules for grouping results. Grouping is used to put documents from the same domain in a container. Within the container, documents are ranked using the sorting rules defined in the sortby parameter. Results passed to the container can be used for including several documents from the same domain in search output.

Parameters are comma-separated and set in the format:
attr%3D<service attribute>.mode%3D<type of grouping>.groups-on-page%3D<number of groups per page>.docs-in-group%3D<number of documents per group>

You can find a description of the parameters mode, attr, groups-on-page and docs-in-group in the POST requests section.

page

Number of the requested page in the search output. This determines the range of document positions returned for the request. Numbering starts from zero (the first page corresponds to the value “0”).

For example, if the number of documents returned on a page is equal to “n”, and the value “p” is passed in the parameter, the search results will include documents that fall within the range of output positions from p*n+1 to p*n+n inclusively.

If the parameter is omitted, the first page of search output is returned.

showmecaptcha

Initiates user verification for possible protection from robots.

The only value used is “yes”.

Sample GET request

The following request returns the second page of search results for the query “<table>” for the user “xml-search-user”. Search type: Russian (yandex.ru). Results are grouped by domain. Each group contains three documents, and five groups can be returned per page.

https://yandex.ru/search/xml?user=xml-search-user&key=03.44583456:c876e1b098gh65khg834ggg1jk4ll9j8&query=%3Ctable%3E&groupby=attr%3Dd.mode%3Ddeep.groups-on-page%3D5.docs-in-group%3D3&maxpassages=3&page=1