POST requests

Attention. Special characters that are passed as parameter values in the request body must be replaced with the appropriate escape sequences for XML-encoding. For example, instead of the ampersand sign (“&”), the escape sequence “&” must be used.

Request URL

 ? [user=<user name>]
 & [key=<API key>]
 & [filter=<filter type>]
 & [lr=<search region ID>]
 & [l10n=<notification language>]
 & [showmecaptcha=<yes>]
Query parameters

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


Value of the API key that was issued during registration.


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.


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.


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 (”“ru” (Russian), “uk” (Ukrainian), “be” (Belarusian), “kk” (Kazakh). If omitted, notifications are sent in Russian.
  • “Turkish (” — Supports only the value “tr” (Turkish).
  • “Worldwide (” — Supports only the value “en” (English).

Initiates user verification for possible protection from robots.

The only value used is “yes”.

Request body format

<?xml version= "1.0" encoding="XML file encoding"?>
<!--Grouping tag-->
   <!--Search query-->
   <!--Type of sorting for search results-->
   <!--Parameters for grouping child tags-->
      <groupby attr="d" mode="deep" groups-on-page="10" docs-in-group="1" />
   <!--Request page number in search results-->
Parameter Description
request Grouping tag. Child tags contain parameters of the search 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.


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).


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.


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.

groupings Grouping tag. The child tag contains parameters for grouping results.


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.

Contains the following attributes:

  • mode — Grouping method. Possible values:

    • “flat” — Flat grouping. Each group contains a single document. Passed with an empty value for the attr parameter (“" "”).
    • “deep” — Grouping by domain. Each group contains documents from a single domain. Passed with the value “d” for the attr parameter.

    If the parameter is not defined, flat grouping is used.

  • attr — Utility attribute. Depends on the value of the mode attribute.

  • groups-on-page — Maximum number of groups that can be returned per page of search results. Acceptable values — from 1 to 100.
  • docs-in-group — Maximum number of documents that can be returned per group. Acceptable values — from 1 to 3.

If necessary, use the XML feed validator in the Yandex.Webmaster service. Detailed information about validation is provided in the appendix.

Sample POST request

The request and request URL shown below return the third page of search results for the query “<table>” for the user “xml-search-user”. Results are sorted by time when the document was changed. Search type: Russian ( Results are grouped by domain. Each group contains three documents, and ten groups can be returned per page. The maximum number of passages per document is two. The service returns an XML file in UTF-8 encoding.

Request URL:

Request body:

<?xml version="1.0" encoding="UTF-8"?> 
      <groupby attr="d" mode="deep" groups-on-page="10" docs-in-group="3" />