# Yandex Search API Documentation

Search the Yandex web index and read the first result page as JSON. Each organic result has the position, title, link, source site, displayed link, snippet, favicon and sitelinks. The response also lists ads, related searches and, when Yandex shows one, an entity card with a title, description and images. Narrow the search with lang (en, ru or tr), family_mode (true filters adult results), period (day, 2weeks or month) and, on the Russian site, lr (a Yandex region ID such as 213 for Moscow). A period with few matches returns fewer results; the list is never padded. Web search returns page 1 only (about 10 organic results): Yandex gives no later page to automated clients, so page above 1 answers 422. A request costs 1 credit. When Yandex blocks the normal route, a premium route answers it and the request costs 38 credits; the response meta shows the credits. A request that fails is not charged.

- **Documentation:** [https://scrappa.co/docs/yandex-api/yandex_search](https://scrappa.co/docs/yandex-api/yandex_search)
- **API group:** Yandex API
- **Endpoint:** `GET https://scrappa.co/api/yandex/search`

## Authentication

Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `text` | string | Yes | Search text. Alias: q. |
| `yandex_domain` | string | No | Yandex site to search. Web and videos: com (default), ru, kz, by or com.tr. Images: com (default), ru, kz or by. Each site has its own index. |
| `lang` | string | No | Result language: en, ru or tr. |
| `lr` | integer | No | Yandex region ID, for example 213 for Moscow or 2 for Saint Petersburg. Works with yandex_domain=ru only. |
| `family_mode` | boolean | No | true filters adult results, false allows them. Yandex default applies when omitted. |
| `period` | string | No | Only recent results: day, 2weeks or month. |
| `page` | integer | No | Only 1 is accepted. Yandex serves the first result page only. |

## Example response

```json
{
    "ads": [
        {
            "link": "https://ads.example.com/click",
            "title": "Pizza delivery offer",
            "source": "example.com",
            "favicon": null,
            "snippet": "Free delivery on the first order.",
            "position": 1,
            "sitelinks": [],
            "displayed_link": "example.com"
        }
    ],
    "meta": {
        "billable": true,
        "duration_ms": 2400,
        "upstream_calls": 2
    },
    "success": true,
    "answer_box": {
        "title": "Pizza",
        "images": [
            "https://avatars.mds.yandex.net/i?id=example"
        ],
        "description": "Pizza is a dish of Italian origin."
    },
    "pagination": {
        "page": 1,
        "max_page": 1
    },
    "organic_results": [
        {
            "link": "https://www.doordash.com/cuisine/pizza-near-me/",
            "title": "Best Pizza Near Me - Order Pizza on DoorDash",
            "source": "Doordash.com",
            "favicon": "https://favicon.yandex.net/favicon/v2/https%3A%2F%2Fwww.doordash.com?size=32",
            "snippet": "Order Pizza near you. Choose from the largest selection of Pizza restaurants and have your meal delivered to your door.",
            "position": 1,
            "sitelinks": [
                {
                    "link": "https://www.doordash.com/menu",
                    "title": "Menu"
                }
            ],
            "displayed_link": "doordash.com \u203a cuisine \u203a pizza-near-me"
        }
    ],
    "related_searches": [
        {
            "query": "pizza restaurants near me",
            "position": 1
        }
    ],
    "search_information": {
        "lang": "en",
        "query": "pizza restaurant",
        "yandex_domain": "com"
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | Returned when a required parameter is missing, a value is out of range or a parameter is not supported. No credits are charged. |
| 503 | Service Unavailable | Returned when Yandex could not be read after several attempts. Failed requests are not charged. Try again. |
| 502 | Unexpected Response | Returned when Yandex answers with a page this API cannot read, or an image cannot be read. Failed requests are not charged. |

## More Scrappa resources

- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)