POST requests

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.

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, documents that are “adults only” or contain profanity are removed from the search results.

If the parameter is omitted, moderate filtering is used.

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

showmecaptcha

Initiates user verification for possible protection from robots.

The only value used is “yes”.

Parameter

Description

request

Grouping tag. Child tags contain parameters of the search query.

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.

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

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.

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.

groupings

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

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:

• mode — Grouping method. Possible values:

  • “flat” — Flat grouping. Each group contains a single document. Passed with an empty attr parameter value.
  • “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 by domains 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.