--- 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` 不是本操作返回的。请不带它重新开始。 | | 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`。 - 用 `image` URL 加 `type=image` 代替 `q`，即可以图搜图。 - `limit` 超过一页时会继续读取后续页面，每页 1 个单位。