--- title: "Search" description: "获取一页 Yahoo 搜索结果，所有区块按页面顺序返回。" --- > 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/yahoo/search ``` 参数可以用 `GET` 的查询字符串发送，也可以用 `POST` 的 JSON 请求体发送，两者等价。 ## 请求 ```bash tab="cURL" curl "https://gateway.apinoa.com/v1/yahoo/search?q=best+running+shoes&country=US" \ -H "x-api-key: $APINOA_API_KEY" ``` ```js tab="JavaScript" const params = new URLSearchParams({ q: "best running shoes", country: "US" }); const res = await fetch(`https://gateway.apinoa.com/v1/yahoo/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/yahoo/search", params={"q": "best running shoes", "country": "US"}, 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` `GB` `CA` `DE` `FR` `IT` `ES` `IN` `SG` `PH` `BR` `MX` `AR` | | `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` | | `limit` | integer 1–60 | | Results wanted (default 7, at most 60). More than one page is charged per page. | | `q` | string | | The query, search operators included. | | `safe` | enum | | Safe search. `on` `off` | | `timeRange` | enum | | Only results from this past period. `hour` `day` `week` `month` `year` | | `type` | enum | | What to search: web results (default), news, images or videos. `web` `news` `images` `videos` | 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": "yahoo", "query": "best running shoes", "type": "web", "outcome": "results", "country": "US", "device": "desktop", "page": 1, "items": [ { "type": "topStories", "rank": 1, "title": "Top Stories", "items": [ { "url": "https://health.yahoo.com/wellness/fitness/article/best-weightlifting-shoes-143108986.html", "title": "Best shoes for lifting weights, according to a weightlifting coach and a podiatrist", "source": "Yahoo Life", "date": "2026-10-29T14:58:00.000Z", "thumbnail": "https://s.yimg.com/fz/api/res/1.2/pi5DctierhZS3W8V8xQSiw--~C/YXBwaWQ9c3JjaGRkO2ZpPXN0cmltO2g9NDQwO3E9ODA7dz02MDA-/https://d29szjachogqwa.cloudfront.net/images/u…" }, { "url": "https://shopping.yahoo.com/style/shoes/articles/8-best-slip-walking-shoes-193723689.html", "title": "The 8 Best Slip-On Walking Shoes, According to Our Editors", "source": "Men's Health via Yahoo", "date": "2026-10-28", "thumbnail": "https://s.yimg.com/fz/api/res/1.2/8uRmYIee9jSKpFqwJQ66zQ--~C/YXBwaWQ9c3JjaGRkO2ZpPXN0cmltO2g9MTYwO3E9ODA7c209MTt3PTE2MA--/https://media.zenfs.com/en/men_s_healt…" } ] }, { "type": "organic", "rank": 2, "position": 1, "url": "https://www.runnersworld.com/gear/a19663621/best-running-shoes/", "title": "The 15 Best Running Shoes of 2026, Tested by Runner’s World", "snippet": "Find the best running shoes of 2026, including Runner’s World–tested picks from Adidas, Brooks, New Balance, Nike, Hoka, Asics, and more.", "site": "Runner's World", "displayUrl": "https://www.runnersworld.com › best-running-shoes", "date": "2026-10-22", "favicon": "https://s.yimg.com/pv/static/search_favicon/images/40x40_9cce582be4ef04e7.png" }, { "type": "organic", "rank": 3, "position": 2, "url": "https://www.outdoorgearlab.com/topics/shoes-and-boots/best-running-shoes", "title": "10 Best Running Shoes of 2026 | Tested & Ranked - GearLab", "snippet": "10 Best Running Shoes of 2026 We run more than 50 miles in every pair of shoes we test, putting top models head to head to find the best from Nike, Hoka, Saucon…", "site": "GearLab", "displayUrl": "https://www.outdoorgearlab.com › best-running-shoes", "date": "2026-05-14", "favicon": "https://s.yimg.com/pv/static/search_favicon/images/32x32_d9bdf3c2ca847615.png", "facts": [{"label": "Brand", "value": "Asics"}, {"label": "Author", "value": "Nathaniel Bailey"}], "rating": 4.8 }, { "type": "peopleAlsoAsk", "rank": 4, "questions": [ { "question": "What are the best running shoes to buy?", "answer": "When selecting the best running shoes, consider factors like your foot type, running style, and the terrain you'll be covering. Popular options for 2026 include…" }, { "question": "Which running shoes have the best ratings?", "answer": "The best running shoes are evaluated based on various performance metrics, including comfort, durability, and support. Recent rankings highlight top models like…" } ] }, { "type": "other", "rank": 6, "kind": "LocalPc-listings", "title": "Running Shoes", "text": "Running Shoes Results near Sacramento, CA Use Precise Location Sacramento Running Company Shoe Store 5.0 ( 13 ) Yelp • 1.26 mi Open • Open until 7:00 PM Work Sh…", "links": [ { "url": "https://search.yahoo.com/local/s?p=best+running+shoes&selectedId=240220726", "title": "Sacramento Running Company Shoe Store 5.0 ( 13 ) Yelp • 1.26 mi Open • Open until 7:00 PM" }, { "url": "https://search.yahoo.com/local/s?p=best+running+shoes&selectedId=228362071", "title": "Work Shoes Plus Shoe Store 4.5 ( 29 ) Yelp • 4.73 mi Open • Open until 6:00 PM" } ] }, { "type": "relatedSearches", "rank": 11, "queries": ["best running shoes for women", "best running shoes for plantar fasciitis"] } ], "cursor": "UlITYMg95D_DebacC8SVNrpRv0EcAZ-oJq7T3lai56eOYPOcQvK7LiGvdN4an817QM6r3rjf5XGZebmDgaDSucdrgnxPHx9dQ8RLSmOucm0ujCEQGioo1SmX0YwCttrpp87tn0BT9EXo4ku_G2jRASOCjYKnyE_H…", "fetchedAt": "2026-10-30T00:58:01.645Z" } } ``` ## 错误 | 状态 | 代码 | 含义 | |---|---|---| | 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 8 more, so $0.0108 in total. [List price](https://apinoa.com/en/pricing); the rate steps down above 1,000 calls a day.