Contact UsGet started

Running search queries via API v1

Written by
Updated at November 20, 2024

With Search API's API v1, you can perform text and image search through the Yandex search database and get search results in XML or HTML format (for text search) in synchronous mode. The search results you get depend on the parameters specified in your 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 service account you created.
  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. To get an XML response, make a GET request formatted as follows:

    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> query. The search type is Russian (yandex.ru). Search region: Novosibirsk Oblast. Notification language: Russian. The family 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.

    To get an HTML response, add /html to the request URL path, e.g., https://yandex.ru/search/xml/html?folderid=b1.... For more information, see Request format.

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. To get an XML response, the URL of the POST request must be formatted as follows:

    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.

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

    To get an HTML response, add /html to the request URL path, e.g., https://yandex.ru/search/xml/html?folderid=b1.... For more information, see Request format.

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 color images in JPG format with horizontal image orientation found on somepics.ru. The Family search filter will be applied. 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