Contact UsGet started

Performing search queries in Search API

Written by
Updated at October 24, 2024

Search API allows you to perform text and image search in the Yandex search database and get search results in XML format. Search results depend on the parameters specified in the query.

Getting started

Sign up for Yandex Cloud and create a billing account:

  1. Go to the management console and log in to Yandex Cloud or create an account if you do not have one yet.
  2. On the Yandex Cloud Billing page, make sure you have a billing account linked and it has the ACTIVE or TRIAL_ACTIVE status. If you do not have a billing account, create one.

If you have an active billing account, you can go to the cloud page to create or select a folder for your infrastructure to operate in.

Learn more about clouds and folders.

Prepare your cloud

  1. Create a service account.
  2. Assign the search-api.executor role to the created service account.
  3. Create an API key for the created service account.
  4. Sign up for Search API.

Create a search query

Based on the search type selected when signing up for the service, specify the appropriate domain name in the query:

  • yandex.ru: For the Russian search type.
  • yandex.com.tr: For the Turkish search type.
  • yandex.com: For the International search type.

For text search, you can use GET requests.

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.

  1. Make a GET request in the following format:

    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>]

    For more information about request parameters, see Request parameters.

    Request example:

    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

    This request returns the fifth page of search results for the <table> prompt. The search type is Russian (yandex.ru). Search region: Novosibirsk Oblast. Notification language: Russian. The Family search filter will be 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.

  2. Send a query to the Yandex search database. To do this, use the cURL utility:

    curl \
  --request GET \
  --output result.xml \
  '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'

    As a result of running the query, the result.xml file containing the search query results in XML format will be saved to the current directory.

For text search, you can use POST requests.

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 &amp; for ampersand (&).

  1. Create a URL of the POST request in the following format:

    https://yandex.<domain>/search/xml
  ? [folderid=<folder_ID>]
  & [filter=<filtering_type>]
  & [lr=<search_region_ID>]
  & [l10n=<notification_language>]

    For more information about request URL parameters, see Request parameters.

    Request example:

    https://yandex.ru/search/xml?folderid=b1gt6g8ht345********&filter=strict&lr=11316&l10n=ru

  2. Prepare a file with the request body, e.g., body.xml.

    Example of a file with the 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>

    For detailed information about the parameters specified in the request body, see Request body parameters.

    The following request example returns the fifth page of search results for the <table> prompt. 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.

  3. Send a query to the Yandex search database. To do this, use the cURL utility:

    curl \
  --request POST \
  --header "Authorization: Api-Key <API_key>" \
  --data "@body.xml" \
  --output result.xml \
  'https://yandex.ru/search/xml?folderid=b1gt6g8ht345********&filter=strict&lr=11316&l10n=ru'

    As a result of running the query, the result.xml file containing the search query results in XML format will be saved to the current directory.

Currently, you can use only GET requests to search by images.

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.

  1. Make a GET request in the following format:

    https://yandex.<domain>/images-xml
  ? [folderid=<folder_ID>]
  & [apikey=<API_key>]
  & [text=<search_query_text>]
  & [groupby=<result_grouping_options>]
  & [p=<page_number>]
  & [fyandex=<family_search_filter>]
  & [site=<website_domain_name>]
  & [itype=<image_format>]
  & [iorient=<image_orientation>]
  & [isize=<image_size>]
  & [icolor=<image_color>]

    For more information about request parameters, see Request parameters.

    Request example:

    https://yandex.ru/images-xml?folderid=b1gt6g8ht345********&apikey=your_service_account_API_key********&text=funny+cats&groupby=attr=ii.groups-on-page=3&p=2&fyandex=1&site=somepics.ru&itype=jpg&iorient=horizontal&isize=medium&icolor=color

    This request returns the third page of image search results for the funny cats query. The search type is Russian (yandex.ru). Search API will return results for medium-sized colored images found on somepics.ru in JPG format with the horizontal image orientation. The Family search filter will be applied to the search results. The page will contain three groups of search results.

  2. Send a query to the Yandex image search database. To do this, use the cURL utility:

    curl \
  --request GET \
  --output result.xml \
  'https://yandex.ru/images-xml?folderid=b1gt6g8ht345********&apikey=your_service_account_API_key********&text=funny+cats&groupby=attr=ii.groups-on-page=3&p=2&fyandex=1&site=somepics.ru&itype=jpg&iorient=horizontal&isize=medium&icolor=color'

    As a result of running the query, the result.xml file containing the search query results in XML format will be saved to the current directory.

Previous
Requesting limits
Next
Mobile search results