POST requests
Search API allows you to search the Yandex search database using set parameters and get search results in XML format. You can transmit search parameters to the service in an HTTP request using the POST method. Search API generates a response as an XML document.
To use the search, when signing up for the service, specify the list of IP addresses you will use to run queries to the service and select the appropriate search type. Based on the selected search type, specify the appropriate domain name in your query:
yandex.ru
: For theRussian
search typeyandex.com.tr
: For theTurkish
search typeyandex.com
: For theInternational
search type
To run a query, you need a service account with the search-api.executor
role and a relevant API key you created.
Warning
If you have any special characters in the parameter values provided in the request body, replace them with the respective escaped sequences based on the XML encoding. For example, use &
for ampersand (&
).
Request format
https://yandex.<domain>/search/xml
? [folderid=<folder_ID>]
& [filter=<filtering_type>]
& [lr=<search_region_ID>]
& [l10n=<notification_language>]
Request parameters
Folder ID and API key
The folderid
field contains the folder ID of the service account you will use to send requests. You will need it for user authentication together with the apikey
parameter (the service account's API key).
Provide the API key value in the Authorization
header in the following format:
Authorization: Api-Key <API_key>
Filtering results
The filter
field contains a rule for filtering search results and determines whether any documents should be excluded from search results. The possible values include:
none
: Filtering is disabled. Search results include any documents regardless of their contents.moderate
: Moderate filter (default value). Documents of the Adult category are excluded from search results unless a query is explicitly made for searching resources of this category.strict
: Family filter. Regardless of a search query, documents of the Adult category and those with profanity are excluded from search results.
Search region ID
Only supported for Russian and Turkish search types.
The lr
field contains the ID of the search country or region that impacts the document ranking rules. For example, if you set this field to 11316
(Novosibirsk region), the search results will be generated based on the formula specified for the Novosibirsk region.
For a list of frequently used country and region IDs, see Search regions.
Notification language
The l10n
field defines the notification language for a search response and impacts the text provided in the found-docs-human
tag and in error messages.
Possible values depend on the selected search type.
Russian search type (yandex.ru):
ru
: Russian (default value)uk
: Ukrainianbe
: Belarusiankk
: Kazakh
Turkish search type (yandex.com.tr): Only the tr
value (Turkish) is supported.
International search type (yandex.com): Only the en
value (English) is supported.
Request body format
<?xml version="1.0" encoding="<XML_file_encoding>"?>
<request>
<!--Grouping tag-->
<query>
<!--Search query text-->
</query>
<sortby order="<!--Sorting order of documents-->">
<!--Search result sorting type-->
</sortby>
<groupings>
<!--Grouping parameters in child tags-->
<groupby attr="d" mode="deep" groups-on-page="10" docs-in-group="1" />
</groupings>
<maxpassages>
<!--Maximum number of passages-->
</maxpassages>
<page>
<!--Number of the requested search result page-->
</page>
</request>
Request body parameters
The <request>
grouping tag integrates all contents of the request body. Child tags contain search query parameters.
Query
Search query text is provided in the query
field. Search queries are handled based on the Yandex query language
The maximum length of a query is 40 words and 400 characters.
Sorting results
The sortby
field contains a rule for sorting search results that defines the sequence of the returned search results. The possible values include:
rlv
: By relevance (default).tm
: By document update time.
When sorting by update time, the parameter may contain the order
attribute with the document sorting order:
descending
: Direct order from most recent to oldest (default).ascending
: Reverse order from oldest to most recent.
Maximum number of passages
A passage is a fragment of found document that contains words from a search query. Passages are used to generate snippets that are text annotations to found documents.
The maxpassages
field defines the maximum number of passages that can be used when generating a document snippet.
The possible values range from 1 to 5. A search result may contain fewer passages than specified by this parameter. By default, a maximum of four passages with search query text is returned per document.
Requested page number
The page
field contains the number of a requested page with search results. The number defines a range of positions of documents returned in response. Page numbering starts from zero (the 0
value stands for page 1).
For example, if the number of documents returned on a page is n
and the provided parameter is set to p
, the search results will include documents within the result position range from p*n+1
to p*n+n
, inclusive.
By default, the first page with search results is returned.
The groupings
grouping tag integrates the grouping results parameters.
Groupby
result grouping
The groupby
parameter combines rules for grouping results. Grouping is used to group documents from a single domain into a container. Within the container, the documents are ranked by the sorting rules set in the sortby
field. The results provided in the container can be used to include multiple documents from the same domain in search results.
Possible groupby
parameters:
mode
: Grouping method. The possible values include:flat
: Flat grouping. Each group contains a single document. This value is provided with theattr
parameter set tonull
.deep
: Grouping by domain. Each group contains documents from one domain. This value is provided with theattr
parameter set tod
.
If you skip this parameter, grouping by domain is used.
attr
: Service attribute that depends on themode
attribute value.groups-on-page
: Maximum number of groups that can be returned per page with search results. The range of possible values is 1 to 100.docs-in-group
: Maximum number of documents that can be returned per group. The range of possible values is 1 to 3.
Sample POST request
The URL and request body presented below return the fifth page of search results for the <table>
request. The results are sorted by the document editing time, from the newest to the oldest. The search type is Russian
(yandex.ru). Search region: Novosibirsk Oblast. The Family search filter is applied to the search results. The results are grouped by domain. Each group contains three documents, and the number of groups returned per page is 10. The maximum number of passages per document is 2. Yandex Search API returns a UTF-8 encoded XML file.
Request URL:
https://yandex.ru/search/xml?folderid=b1gt6g8ht345********&filter=strict&lr=11316&l10n=ru
Request body:
<?xml version="1.0" encoding="UTF-8"?>
<request>
<query><table></query>
<sortby order="descending">tm</sortby>
<maxpassages>2</maxpassages>
<page>4</page>
<groupings>
<groupby attr="d" mode="deep" groups-on-page="10" docs-in-group="3" />
</groupings>
</request>