---
title: "Search"
description: "Yandex 검색 결과 페이지 하나를 가져옵니다. 모든 블록이 페이지 순서대로 옵니다."
---

> Every apinoa docs page as markdown: https://apinoa.com/llms.txt (all in one file: https://apinoa.com/llms-full.txt; this API family in one file: https://apinoa.com/docs/serp/llms.txt)

```http
GET | POST /v1/yandex/search
```

파라미터는 `GET`의 쿼리 문자열로도, `POST`의 JSON 본문으로도 보낼 수 있습니다. 둘은 같습니다.

## 요청

```bash tab="cURL"
curl "https://gateway.apinoa.com/v1/yandex/search?q=moscow+kremlin&type=images" \
  -H "x-api-key: $APINOA_API_KEY"
```

```js tab="JavaScript"
const params = new URLSearchParams({ q: "moscow kremlin", type: "images" });
const res = await fetch(`https://gateway.apinoa.com/v1/yandex/search?${params}`, {
  headers: { "x-api-key": process.env.APINOA_API_KEY },
});
const { success, data, error } = await res.json();
```

```python tab="Python"
import os

import requests

res = requests.get(
    "https://gateway.apinoa.com/v1/yandex/search",
    params={"q": "moscow kremlin", "type": "images"},
    headers={"x-api-key": os.environ["APINOA_API_KEY"]},
)
body = res.json()
```

## 파라미터

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `country` | enum |  | The market, as an ISO 3166 country code. `US` `RU` `TR` `KZ` `BY` `UA` `UZ` `DE` `GB` `FR` |
| `cursor` | string |  | The previous page's `cursor`. Pass it alone for the next page. |
| `device` | enum |  | Which page to read: the desktop (default) or the mobile one. `desktop` `mobile` |
| `image` | string |  | An image URL: a reverse-image search instead of `q` (`type=image`). |
| `lang` | enum |  | Interface language: en (yandex.com, the default) or ru (yandex.ru). `en` `ru` |
| `limit` | integer 1–100 |  | Results wanted (default 20, at most 100). More than one page is charged per page. |
| `q` | string |  | The query, search operators included. |
| `timeRange` | enum |  | Only results from this past period. `hour` `day` `week` `month` `year` |
| `type` | enum |  | What to search: news, images, videos, or `image` for a reverse-image search. Yandex's web results are not offered. `news` `images` `videos` `image` |

The same parameters, and every response type, are in the OpenAPI document: https://apinoa.com/openapi.json

## 응답

`data`에 [`ResultsPage`](/docs/api-reference/serp/response-schema#resultspage)를 돌려줍니다. 실제 응답을 줄인 것입니다. 배열은 앞쪽 항목만 남기고 긴 텍스트는 잘랐습니다.

```json
{
  "success": true,
  "data": {
    "engine": "yandex",
    "query": "moscow kremlin",
    "type": "images",
    "outcome": "results",
    "country": "US",
    "lang": "en",
    "device": "desktop",
    "page": 1,
    "items": [
      {
        "type": "image",
        "imageUrl": "https://upload.wikimedia.org/wikipedia/commons/thumb/c/c1/DSC07437-%D0%9C%D0%BE%D1%81%D0%BA%D0%BE%D0%B2%D1%81%D0%BA%D0%B8%D0%B9_%D0%9A%D1%80%D0%B5%D0%BC%D0%BB%D…",
        "thumbnail": "https://avatars.mds.yandex.net/i?id=0478d2b2c1e3bc635da290a7ec93ed7a8389541d-4568991-images-thumbs&n=13",
        "width": 1280,
        "height": 854,
        "title": "Кремль - Википедия",
        "url": "https://ru.wikipedia.org/wiki/%D0%9A%D1%80%D0%B5%D0%BC%D0%BD%D0%B8%D0%BA",
        "source": "ru.wikipedia.org",
        "ext": {
          "id": "c13a461cad3531a9d14e15d194b1f453",
          "snippet": "Кремль — Википедия",
          "copies": [
            {
              "url": "https://day.ru/public/styles/1920x1080_16_9_watermark/public/image/2026-07/screenshot_8.jpg.webp?itok=tgB7-t6o",
              "width": 1920,
              "height": 1080,
              "bytes": 239798
            },
            {
              "url": "https://apostrophe.ua/uploads/image/a2d88e4418642f7271777de4cf54216f.jpg",
              "width": 1500,
              "height": 1001,
              "bytes": 1802215
            }
          ]
        },
        "rank": 1
      },
      {
        "type": "image",
        "imageUrl": "https://cdn.culture.ru/c/367836.jpg",
        "thumbnail": "https://avatars.mds.yandex.net/i?id=8b172529aea8e52da70a8539d9ee647e8646aea7-5338433-images-thumbs&n=13",
        "width": 1350,
        "height": 900,
        "title": "Музеи Московского Кремля: история основания, экспозиции, соборы на территории Кр",
        "url": "https://www.culture.ru/materials/94949/muzei-moskovskogo-kremlya-chto-i-gde?7",
        "source": "culture.ru",
        "ext": {
          "id": "e07ff0761619f4d6f544159823e1163d",
          "snippet": "Telegram.",
          "copies": [
            {"url": "https://cdn.culture.ru/c/367836.jpg", "width": 1350, "height": 900, "bytes": 152243},
            {
              "url": "https://moscowrussian.com/images/kremlin-church.jpg",
              "width": 1200,
              "height": 800,
              "bytes": 263551
            }
          ]
        },
        "rank": 2
      },
      {
        "type": "image",
        "imageUrl": "https://news.store.rambler.ru/img/b4d984f9a02f4f2f79bdc5a25fec1378?img-format=avif&img-1-resize=width:1280",
        "thumbnail": "https://avatars.mds.yandex.net/i?id=2a6a772473ef11a574759d3c2ef99700d60d3073-12935885-images-thumbs&n=13",
        "width": 1280,
        "height": 720,
        "title": "Что посмотреть в Московском Кремле: краткая история, достопримечательности и цен",
        "url": "https://weekend.rambler.ru/tourism/56962355-chto-posmotret-v-moskovskom-kremle-kratkaya-istoriya-dostoprimechatelnosti-i-tseny-na-ekskursii/",
        "source": "weekend.rambler.ru",
        "ext": {
          "id": "19300ddc2386aec2e7a879ec0a199c96",
          "snippet": "© yulenochekk/iStock.com",
          "copies": [
            {
              "url": "https://www.his-j.com/oe/up_img/LED0097/Tr00100420201016215043586.jpg",
              "width": 4774,
              "height": 3106,
              "bytes": 5002584
            },
            {
              "url": "https://cdn1.img.spnfa.ir/img/03/76/037659_0:139:3147:1909_1920x0_80_0_0_8aabe5681b4393b85463dc85a65e816a.jpg",
              "width": 1920,
              "height": 1080,
              "bytes": 373184
            }
          ]
        },
        "rank": 3
      }
    ],
    "fetchedAt": "2026-10-30T01:00:16.470Z"
  }
}
```

## 에러

| 상태 | 코드 | 의미 |
|---|---|---|
| 400 | `INVALID_CURSOR` | 이 오퍼레이션이 돌려준 `cursor`가 아닙니다. `cursor` 없이 처음부터 다시 호출하세요. |
| 400 | `INVALID_PARAMS` | 파라미터가 없거나, 알 수 없거나, 범위를 벗어났거나, 이 엔진이 받지 않는 값입니다. 메시지에 이름이 나옵니다. |
| 401 | `UNAUTHORIZED` | `x-api-key` 헤더가 없거나, 폐기되었거나 알 수 없는 키입니다. |
| 402 | `INSUFFICIENT_BALANCE` | 잔액이 이 호출 비용에 모자랍니다. 대시보드에서 충전하세요. |
| 429 | `MARKETPLACE_SATURATED` | 동시 호출이 너무 많습니다. `Retry-After` 초만큼 기다린 뒤 다시 시도하세요. |
| 502 | `UPSTREAM_ERROR` | 엔진이 쓸 수 없는 응답을 보냈습니다. 간격을 두고 다시 시도하세요. |
| 503 | `SERVICE_UNAVAILABLE` | 일시적인 장애입니다. 간격을 두고 다시 시도하세요. |

모든 코드는 [Errors](/docs/errors)에 있습니다. 실패한 호출은 과금되지 않습니다.

## 가격

**Price** $0.0012 per call, plus $0.0012 for each extra call it makes — at most 4 more, so $0.006 in total. [List price](https://apinoa.com/en/pricing); the rate steps down above 1,000 calls a day.

## 참고

- `type`을 넘겨야 합니다. Yandex 웹 검색 결과는 제공하지 않습니다. 뉴스는 Yandex 러시아어 뉴스판에서 오며 `country`와 `lang`을 받지 않습니다.
- `q` 대신 `image` URL과 `type=image`를 넘기면 이미지로 검색(역방향 이미지 검색)합니다.
- `limit`이 한 페이지보다 크면 다음 페이지들도 읽으며, 페이지마다 1단위입니다.