> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/products/cn/web-api/search.md).

# /search

了解如何使用 Oxylabs Web API /search 端点搜索实时网络并采集排序结果。

该 `/v1/search` 端点执行实时网页搜索，并返回排序后的自然结果，包括标题、摘要、URL、位置元数据和相关查询。它可作为发现工具，用于在将目标 URL 传递给 [`/v1/scrape`](/products/cn/web-api/scrape.md) 端点进行整页提取之前识别权威网页。

## 请求示例

该端点接受包含搜索 **查询**, **结果数量限制**，以及 **地理位置** 参数的 JSON 请求体。

```bash
curl https://webapi.oxylabs.io/v1/search \\
  -H "Authorization: Bearer $OXYLABS_WEB_API_KEY" \\
  -H 'Content-Type: application/json' \\
  -d '{
    "query": "eu ai act compliance deadlines",
    "max_results": 3,
    "location": "DE"
  }'
```

### 请求参数

<table><thead><tr><th width="123">参数</th><th width="533">描述</th><th width="88">类型</th></tr></thead><tbody><tr><td><mark style="background-color:green;"><code>查询</code></mark></td><td>搜索关键词或短语（介于 <code>1</code> 和 <code>2,048</code> 个字符之间）。</td><td>字符串</td></tr><tr><td><code>max_results</code></td><td>返回的自然搜索结果数量（介于 <code>1</code> 和 <code>20</code>）。默认： <code>10</code></td><td>整数</td></tr><tr><td><code>location</code></td><td>ISO 3166-1 alpha-2 国家代码（例如 <code>DE</code>, <code>US</code>）用于本地化搜索。</td><td>字符串</td></tr></tbody></table>

&#x20;    — 必填参数。

{% hint style="warning" %}
未知或拼写错误的参数会被拒绝，并返回 HTTP `400 Bad Request` 状态码，而不是被忽略。
{% endhint %}

### 请求优化

<details>

<summary><strong><code>查询</code></strong></summary>

建议写成一个人在搜索框中会输入的内容。关键词式查询的表现优于句子式查询：

<table><thead><tr><th width="373">而不是</th><th>使用</th></tr></thead><tbody><tr><td>“欧盟人工智能法案的合规截止日期是什么？”</td><td><code>欧盟人工智能法案合规截止日期</code></td></tr><tr><td>“我想知道 Figma 每席位多少钱”</td><td><code>Figma 每席位定价</code></td></tr></tbody></table>

每个请求只问一个问题。复合查询返回的结果对任一部分都匹配不佳。

</details>

<details>

<summary><strong><code>max_results</code></strong></summary>

参数是上限，不是目标。匹配较少的查询会返回更少的结果，并按最佳优先排序。

</details>

<details>

<summary><strong><code>location</code></strong></summary>

价格、可用性、语言和排名通常会因国家而异。

ISO 3166-1 alpha-2 代码是唯一接受的格式（例如 `DE`, `US`）。不属于已分配国家的格式正确配对会被 `400` 错误代码拒绝。省略该参数会设置一个 `默认` 区域设置，而这只有在答案不依赖位置时才是最优的。

</details>

## 输出示例

```json
{
    "state": "done",
    "results": [
        {
            "title": "Implementation Timeline | EU Artificial Intelligence Act",
            "outline": [
                "Providers: Providers of GPAI models that have been placed on the market before this date need to be compliant with the AI Act by 2 August 2027. ... Member States: Deadline for Member States to report to the Commission on the status of the financial and human resources of the national competent ..."
            ],
            "url": "https://artificialintelligenceact.eu/implementation-timeline/",
            "metadata": {
                "position": 1
            }
        },
        {
            "title": "EU AI Act Timeline: Key Compliance Dates & Deadlines Explained",
            "outline": [
                "While the EU Commission is working with member states to build out the reporting and monitoring infrastructure of the AI Act until August 2025, companies have several key areas to focus on: establishing a risk management system, implementing data governance measures, drawing up technical ..."
            ],
            "url": "https://www.dataguard.com/eu-ai-act/timeline",
            "metadata": {
                "position": 2
            }
        },
        {
            "title": "Timeline for the Implementation of the EU AI Act | AI Act Service Desk",
            "outline": [
                "The EU’s AI Act legislation applies progressively, with a full roll-out of the main application milestones foreseen by 2 August 2028."
            ],
            "url": "https://ai-act-service-desk.ec.europa.eu/en/ai-act/timeline/timeline-implementation-eu-ai-act",
            "metadata": {
                "position": 3
            }
        }
    ],
    "related_questions": [],
    "related_searches": [],
    "params": {
        "query": "eu ai act compliance deadlines",
        "location": "DE",
        "max_results": 3
    },
    "metadata": {
        "timestamp": 1791289627,
        "request_id": "1791289625962078444"
    }
}
```

{% hint style="warning" %}
**`outline`** 只是一个代表性摘录。要获取页面本身的实时数据， [抓取该 URL](/products/cn/web-api/scrape.md).
{% endhint %}

### 输出字典

<table><thead><tr><th width="244">字段</th><th width="404.04296875">描述</th><th width="95.94140625">类型</th></tr></thead><tbody><tr><td><code>state</code></td><td><code>"done"</code> 成功时。遇到上游故障的搜索会返回 <code>500</code> 并带有 <code>state: "faulted"</code> （参见 <a href="/products/cn/web-api/gu-zhang-pai-chu.md">错误代码</a>).</td><td>字符串</td></tr><tr><td><code>results</code></td><td>按最佳优先排序的自然结果。始终存在，因此空输出表示没有匹配项。</td><td>数组</td></tr><tr><td><code>results[].title</code></td><td>抓取到的页面标题。</td><td>字符串</td></tr><tr><td><code>results[].outline[]</code></td><td>SERP 结果摘要。中途截断。</td><td>字符串数组</td></tr><tr><td><code>results[].url</code></td><td>结果的绝对 URL。传递给 <a href="/products/cn/web-api/scrape.md"><code>/v1/scrape</code></a>.</td><td>字符串</td></tr><tr><td><code>results[].metadata.position</code></td><td>自然 SERP 位置，从 <code>1</code>.</td><td>整数</td></tr><tr><td><code>related_questions</code></td><td>包含“People also ask”问题对象，其中包含 <code>question</code>, <code>title</code>，以及 <code>snippet</code> （如有）。</td><td>数组</td></tr><tr><td><code>related_searches</code></td><td>相关搜索查询，每个都包含 <code>查询</code>.</td><td>数组</td></tr><tr><td><code>params</code></td><td>包含默认值的执行参数。</td><td>对象</td></tr><tr><td><code>metadata.timestamp</code></td><td>Unix 秒级时间戳。</td><td>整数</td></tr><tr><td><code>metadata.request_id</code></td><td>19 位请求句柄。 <strong>请包含在支持工单中。</strong></td><td>字符串</td></tr></tbody></table>

{% hint style="info" %}
`related_searches` 当第一次搜索结果较少时，这对查询扩展很有用。它提供覆盖更广的表述。
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.oxylabs.io/products/cn/web-api/search.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.