Getting started with Yandex Search API

Yandex Search API allows you to send queries to the Yandex search database via the REST API, gRPC API, or Yandex Cloud ML SDK. In this tutorial, you will set up access to Yandex Search API and run your first search query in synchronous mode: you will get the result immediately once the query is processed.

For all Yandex Search API features, see About Yandex Search API. For Yandex Search API prices, see Yandex Search API pricing policy.

Get your cloud ready

AI Studio follows the Yandex Cloud resource model, where most services store their resources in folders. Folders belong to clouds, and clouds belong to organizations. You will need a folder to work with AI Studio.

Log in to AI Studio under your personal Yandex account (Yandex ID). For a detailed guide on how to create such an account, see Yandex ID Help.
Create an organization:
- Enter the organization name.
- Specify the cloud name. This name will be used for all the Yandex Cloud resources.
- Click Open AI Studio.
The organization will automatically get a new folder named default.

Linking a billing account

To work with AI Studio, you need an active billing account linked to your cloud. When you create your first billing account and add a credit/debit card, you will get your initial grant.

After you log in to AI Studio, click Link billing account in the top-right corner of the UI.
Create a billing account or select an existing one.
- Click Add card.
- Specify your card details: 16-digit number, expiration date, and CVV (you can find it on the back side of your card).
- Click Link.
Make sure the billing account status is ACTIVE or TRIAL_ACTIVE.

Create an API key

To create an API key:

AI Studio UI

In the AI Studio interface, click Create API key in the top-right corner.
Optionally, change the description of the API key so you can easily find the key later.
Select the API key expiration date.
Click Create.
Save the ID and secret key.

Alert

Do not share your API key with anyone. After you close this dialog, the key value will no longer be available.

Together with the API key, the system will create a service account with a role to work with Yandex Search API.

Run your first search query

After creating the API key, you can immediately run a search query. Choose the method you prefer: cURL via the REST API or Yandex Cloud ML SDK.

cURL

ML SDK

To work with the REST API, install cURL and jq:

# For Ubuntu/Debian
        sudo apt-get install curl jq
        
        # For macOS
        brew install curl jq

Create a file with the request body named body.json:

{
          "query": {
            "searchType": "SEARCH_TYPE_RU",
            "queryText": "coffee machine"
          },
          "folderId": "<folder_ID>",
          "responseFormat": "FORMAT_HTML"
        }

Where:

searchType: Search type. SEARCH_TYPE_RU restricts search to the Russian-language internet segment.
queryText: Search query text.
folderId: ID of the folder the API key was created in.
responseFormat: Response format. FORMAT_HTML returns results in HTML format.

Run this request:

curl \
          --request POST \
          --header "Authorization: Api-Key <API_key>" \
          --data "@body.json" \
          "https://searchapi.api.cloud.yandex.net/v2/web/search"

Where <API_key> is the API key you created earlier.

Result:

{
          "rawData": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4KPHlhbmRleHNlYXJjaCB2ZXJzaW9uPSIxLjAiPgo8cmVxdWVzdD4..."
        }

The rawData field contains search results in Base64 encoding.

Decode the result:

curl \
          --request POST \
          --header "Authorization: Api-Key <API_key>" \
          --data "@body.json" \
          "https://searchapi.api.cloud.yandex.net/v2/web/search" | \
          jq -r .rawData | \
          base64 --decode > result.html

The search results will be saved to a file named result.html.

Tip

To get the results in XML format, change "responseFormat": "FORMAT_HTML" to "responseFormat": "FORMAT_XML". For more information on formats, see XML format of response to a text search query and HTML format of response to a text search query.

To work with ML SDK, install Python version 3.10 or higher and the Yandex Cloud ML SDK library:

# Check the Python version.
        python3 --version
        
        # Install the library.
        pip install yandex-ai-studio-sdk

Create a file named search.py and paste the following code into it:

#!/usr/bin/env python3
        
        from yandex_ai_studio_sdk import AIStudio
        
        # Initializing the SDK
        sdk = AIStudio(
            folder_id="<folder_ID>",
            auth="<API_key>",
        )
        
        # Running a search
        search = sdk.search_api.web(search_type="ru")
        result = search.run_sync("coffee machine", format="html")
        
        # Saving the result to a file
        with open("result.html", "w", encoding="utf-8") as f:
            f.write(result.decode("utf-8"))
        
        print("Results saved to result.html")

Where:

<folder_ID>: ID of the folder the API key was created in.
<API_key>: API key you created earlier.
search_type="ru": Search type (Russian-language segment).
format="html": Results format.

Run the script:
```
python3 search.py
        
```
The result will be saved to the result.html file.

Tip

To get the results in XML format, change format="html" to format="xml". For more information about SDK parameters, see this Yandex Cloud ML SDK guide.