GET requests
With Yandex Search API's API v1, you can run requests with preset parameters to the Yandex search database. You can submit search parameters to the service as an HTTP request using the GET method. Yandex Search API will return a response as an XML or HTML 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 theRussiansearch typeyandex.com.tr: For theTurkishsearch typeyandex.com: For theInternationalsearch type
To run a query, you need a service account with the search-api.executor role and a relevant API key you created.
Request format
Warning
If you have any special characters in parameter values, replace them with the respective escaped sequences based on percent-encoding. For example, instead of the equals sign (=), use %3D.
The URL of your request to Yandex Search API and the list of supported parameters will be different depending on the format you want the result in: XML or HTML.
https://yandex.<domain>/search/xml
? [folderid=<folder_ID>]
& [apikey=<API_key>]
& [query=<search_query_text>]
& [lr=<search_region_ID>]
& [l10n=<notification_language>]
& [sortby=<sorting_type>]
& [filter=<filtering_type>]
& [maxpassages=<number_of_passages>]
& [groupby=<result_grouping_options>]
& [page=<page_number>]
https://yandex.<domain>/search/xml/html
? [folderid=<folder_ID>]
& [apikey=<API_key>]
& [query=<search_query_text>]
& [lr=<search_region_ID>]
& [filter=<filtering_type>]
& [page=<page_number>]
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).
Query
Search query text is provided in the query field. Search queries are handled based on the Yandex query language specifics. Use the appropriate escaped sequences instead of special characters.
The maximum length of a query is 40 words and 400 characters.
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 parameter is not supported when getting the result in HTML format.
The l10n field sets the notification language for the 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)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.
Sorting results
The sortby parameter is not supported when getting the result in HTML format.
The sortby field contains the sorting rule for how the search results must be sorted. The possible values are:
rlv: By relevance (default).tm: By document update time.
When sorting by update time, the parameter may contain the order attribute for document sorting order:
descending: Direct order, i.e., from most recent to oldest (default).ascending: Reverse order, i.e., from oldest to most recent.
The format is as follows: sortby=<sorting_type>.order%3D<sorting_order>. For example, for reverse sorting by date, use sortby=tm.order%3Dascending.
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.
Maximum number of passages
The maxpassages parameter is not supported when getting the result in HTML format.
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 sets 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.
Rules for grouping results
The groupby parameter is not supported when getting the result in HTML format.
The groupby parameter consolidates 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 defined in the sortby field. The results provided in the container can be used to include multiple documents from the same domain in search results.
Dot-separated parameters are specified in the following format:
attr%3D<service_attribute>.mode%3D<grouping_type>.groups-on-page%3D<number_of_groups_per_page>.docs-in-group%3D<number_of_documents_per_group>
Where:
mode: Grouping method. The possible values are:flat: Flat grouping. Each group contains a single document. Provided with an empty value for theattrparameter.deep: Grouping by domain. Each group contains documents from one domain. Provided with theattrparameter set tod.
If the parameter is not set, grouping by domain is used.
attr: Service attribute. It depends on themodeattribute value.groups-on-page: Maximum number of groups that can be returned per search results page. The values range from 1 to 100.docs-in-group: Maximum number of documents that can be returned per group. The values range from 1 to 3.
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.
GET request example
The request below returns the fifth page of search results for the <table> query. The search type is Russian (yandex.ru). Search region: Novosibirsk Oblast. Notification language: Russian. The Family search filter is applied to the search results. The number of passages is three. The results are grouped by domain and sorted by relevance. Each group contains three documents, and the number of groups returned per page is five.
The URL of your request to Yandex Search API and the list of supported parameters will be different depending on the format you want the result in: XML or HTML.
https://yandex.ru/search/xml?folderid=b1gt6g8ht345********&apikey=your_service_account_API_key********&query=%3Ctable%3E&lr=11316&l10n=ru&sortby=rlv&filter=strict&groupby=attr%3Dd.mode%3Ddeep.groups-on-page%3D5.docs-in-group%3D3&maxpassages=3&page=4
https://yandex.ru/search/xml/html?folderid=b1gt6g8ht345********&apikey=your_service_account_API_key********&query=%3Ctable%3E&lr=11316&l10n=ru&sortby=rlv&filter=strict&groupby=attr%3Dd.mode%3Ddeep.groups-on-page%3D5.docs-in-group%3D3&maxpassages=3&page=4