> ## Documentation Index
> Fetch the complete documentation index at: https://docs.evocrawl.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 搜索

> 搜索网络并获取结果的完整内容

进行网页搜索，并通过一次 API 调用从每个结果中获取干净、结构化的内容。将查询传递给 `/search`，Evocrawl 会返回标题、描述和 URL。添加 `scrapeOptions` 后，还可为每个结果获取完整页面的 markdown、HTML、links 或 screenshots。

完整参数列表请参阅 [Search Endpoint API Reference](https://docs.evocrawl.com/api-reference/endpoint/search)。

<Card title="在 Playground 中试用" icon="play" href="https://www.evocrawl.com/playground?endpoint=search">
  在交互式 Playground 中试用搜索功能——无需写代码。
</Card>

<div id="performing-a-search-with-evocrawl">
  ## 使用 Evocrawl 进行搜索
</div>

<div id="search-endpoint">
  ### /search 端点
</div>

用于执行网页搜索，并可选择从结果中获取内容。

<div id="installation">
  ### 安装
</div>

<CodeGroup>
  ```python Python theme={null}
  # 使用 pip 安装 evocrawl-py

  from evocrawl import Evocrawl

  evocrawl = Evocrawl(api_key="fc-YOUR-API-KEY")
  ```

  ```js Node theme={null}
  # 使用 npm 安装 @mendable/evocrawl-js

  import Evocrawl from '@mendable/evocrawl-js';

  const evocrawl = new Evocrawl({ apiKey: "fc-YOUR-API-KEY" });
  ```

  ```bash CLI theme={null}
  # 使用 npm 全局安装
  npm install -g evocrawl

  # 身份验证(一次性设置)
  evocrawl login
  ```
</CodeGroup>

<div id="basic-usage">
  ### 基本用法
</div>

<CodeGroup>
  ```python Python theme={null}
  from evocrawl import Evocrawl

  evocrawl = Evocrawl(api_key="fc-YOUR-API-KEY")

  results = evocrawl.search(
      query="Evocrawl",
      limit=3,
  )
  print(results)
  ```

  ```js Node theme={null}
  import Evocrawl from '@mendable/evocrawl-js';

  const evocrawl = new Evocrawl({ apiKey: "fc-你的 API 密钥" });

  const results = await evocrawl.search('evocrawl', {
    limit: 3,
    scrapeOptions: { formats: ['markdown'] }
  });
  console.log(results);
  ```

  ```bash cURL theme={null}
  curl -s -X POST "https://api.evocrawl.com/v2/search" \
    -H "Authorization: Bearer $EVOCRAWL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "evocrawl",
      "limit": 3
    }'
  ```

  ```bash CLI theme={null}
  # 搜索网络
  evocrawl search "evocrawl web scraping" --limit 5 --pretty
  ```
</CodeGroup>

<div id="response">
  ### 响应
</div>

SDK 将直接返回数据对象；cURL 将返回完整的有效负载。

```json JSON theme={null}
{
  "success": true,
  "data": {
    "web": [
      {
        "url": "https://www.evocrawl.com/",
        "title": "Evocrawl - 面向 AI 的 Web 数据 API",
        "description": "用于 AI 的网页爬取、抓取与搜索 API。为规模而建。Evocrawl 将整个互联网送达 AI 代理与开发者。",
        "position": 1
      },
      {
        "url": "https://github.com/superaihuman/evocrawl",
        "title": "mendableai/evocrawl：将整站转换为可供 LLM 使用的内容 - GitHub",
        "description": "Evocrawl 是一项 API 服务，接收一个 URL，对其进行爬取，并将其转换为干净的 Markdown 或结构化数据。",
        "position": 2
      },
      ...
    ],
    "images": [
      {
        "title": "快速上手 | Evocrawl",
        "imageUrl": "https://mintlify.s3.us-west-1.amazonaws.com/evocrawl/logo/logo.png",
        "imageWidth": 5814,
        "imageHeight": 1200,
        "url": "https://docs.evocrawl.com/",
        "position": 1
      },
      ...
    ],
    "news": [
      {
        "title": "Y Combinator 创业公司 Evocrawl 准备出资 100 万美元雇用三名 AI 代理作为员工",
        "url": "https://techcrunch.com/2025/05/17/y-combinator-startup-evocrawl-is-ready-to-pay-1m-to-hire-three-ai-agents-as-employees/",
        "snippet": "目前它在 YC 的招聘板发布了三则"仅限 AI 代理"的新职位，并为此预留了总计 100 万美元的预算。",
        "date": "3 个月前",
        "position": 1
      },
      ...
    ]
  }
}
```

<div id="search-result-types">
  ## 搜索结果类型
</div>

除了常规网页结果外，Search 还可通过 `sources` 参数支持以下专用结果类型：

* `web`：标准网页结果 (默认)
* `news`：新闻结果
* `images`：图片搜索结果

你可以在一次调用中请求多个 source (例如 `sources: ["web", "news"]`) 。此时，`limit` 参数会**按每种 source 类型分别生效**——因此，当 `limit: 5` 且 `sources: ["web", "news"]` 时，会分别返回最多 5 条 web 结果和最多 5 条 news 结果 (合计最多 10 条) 。如果你需要为不同的 source 设置不同的参数 (例如不同的 `limit` 值或不同的 `scrapeOptions`) ，请分别发起独立的调用。

<div id="search-categories">
  ## 搜索类别
</div>

使用 `categories` 参数按特定类别过滤搜索结果：

* `github`：在 GitHub 的仓库、代码、Issue 和文档中搜索
* `research`：搜索学术与科研网站 (arXiv、Nature、IEEE、PubMed 等)
* `pdf`：搜索 PDF 文档

<div id="github-category-search">
  ### GitHub 分类搜索
</div>

在 GitHub 仓库中进行定向搜索：

```bash cURL theme={null}
curl -X POST https://api.evocrawl.com/v2/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fc-YOUR_API_KEY" \
  -d '{
    "query": "Python 网页抓取",
    "categories": ["github"],
    "limit": 10
  }'
```

<div id="research-category-search">
  ### 研究类别搜索
</div>

搜索学术与科研类网站：

```bash cURL theme={null}
curl -X POST https://api.evocrawl.com/v2/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fc-YOUR_API_KEY" \
  -d '{
    "query": "机器学习 transformer",
    "categories": ["研究"],
    "limit": 10
  }'
```

<div id="mixed-category-search">
  ### 混合类别搜索
</div>

在一次搜索中合并多个类别：

```bash cURL theme={null}
curl -X POST https://api.evocrawl.com/v2/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fc-YOUR_API_KEY" \
  -d '{
    "query": "神经网络",
    "categories": ["github", "research"],
    "limit": 15
  }'
```

<div id="category-response-format">
  ### 分类响应格式
</div>

每条搜索结果都包含一个 `category` 字段，用于标示其来源：

```json theme={null}
{
  "success": true,
  "data": {
    "web": [
      {
        "url": "https://github.com/example/neural-network",
        "title": "神经网络实现",
        "description": "基于 PyTorch 的神经网络实现",
        "category": "github"
      },
      {
        "url": "https://arxiv.org/abs/2024.12345",
        "title": "神经网络架构的最新进展",
        "description": "探讨神经网络改进的研究论文"
        "category": "research"
      }
    ]
  }
}
```

示例：

```bash cURL theme={null}
curl -X POST https://api.evocrawl.com/v2/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fc-YOUR_API_KEY" \
  -d '{
    "query": "openai",
    "sources": ["news"],
    "limit": 5
  }'
```

```bash cURL theme={null}
curl -X POST https://api.evocrawl.com/v2/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fc-YOUR_API_KEY" \
  -d '{
    "query": "jupiter",
    "sources": ["images"],
    "limit": 8
  }'
```

<div id="hd-image-search-with-size-filtering">
  ### 按尺寸筛选的高清图片搜索
</div>

使用 images 源的搜索运算符查找高分辨率图片：

```bash cURL theme={null}
curl -X POST https://api.evocrawl.com/v2/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fc-YOUR_API_KEY" \
  -d '{
    "query": "sunset imagesize:1920x1080",
    "sources": ["images"],
    "limit": 5
  }'
```

```bash cURL theme={null}
curl -X POST https://api.evocrawl.com/v2/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fc-YOUR_API_KEY" \
  -d '{
    "query": "mountain wallpaper larger:2560x1440",
    "sources": ["images"],
    "limit": 8
  }'
```

**常见高清分辨率：**

* `imagesize:1920x1080` - 全高清 (1080p)
* `imagesize:2560x1440` - QHD (1440p)
* `imagesize:3840x2160` - 4K UHD
* `larger:1920x1080` - 高清及以上
* `larger:2560x1440` - QHD 及以上

<div id="search-with-content-scraping">
  ## 搜索并抓取内容
</div>

在一次操作中完成搜索并从结果中提取内容。

<CodeGroup>
  ```python Python theme={null}
  from evocrawl import Evocrawl

  evocrawl = Evocrawl(api_key="fc-YOUR_API_KEY")

  # 搜索并爬取内容
  results = evocrawl.search(
      "evocrawl web scraping",
      limit=3,
      scrape_options={
          "formats": ["markdown", "links"]
      }
  )
  ```

  ```js Node theme={null}
  import Evocrawl from '@mendable/evocrawl-js';

  const evocrawl = new Evocrawl({ apiKey: "fc-你的 API Key" });

  const results = await evocrawl.search('evocrawl', {
    limit: 3,
    scrapeOptions: { formats: ['markdown'] }
  });
  console.log(results);
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.evocrawl.com/v2/search \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer fc-YOUR_API_KEY" \
    -d '{
      "query": "evocrawl 网页抓取",
      "limit": 3,
      "scrapeOptions": {
        "formats": ["markdown", "links"]
      }
    }'
  ```

  ```bash CLI theme={null}
  # 搜索并抓取结果
  evocrawl search "evocrawl" --scrape --scrape-formats markdown --limit 5 --pretty
  ```
</CodeGroup>

通过 `scrapeOptions` 参数，该搜索端点支持 /scrape 端点中的所有选项。

<div id="response-with-scraped-content">
  ### 包含爬取内容的响应
</div>

```json theme={null}
{
  "success": true,
  "data": [
    {
      "title": "Evocrawl - 终极网页抓取 API",
      "description": "Evocrawl 是强大的网页抓取 API，可将任意网站转化为干净且结构化的数据，供 AI 与分析使用。",
      "url": "https://evocrawl.com/",
      "markdown": "# Evocrawl\n\n终极网页抓取 API\n\n## 将任意网站转化为干净且结构化的数据\n\nEvocrawl 让从网站提取数据变得简单高效，适用于 AI 应用、市场研究、内容聚合等场景……",
      "links": [
        "https://evocrawl.com/pricing",
        "https://evocrawl.com/docs",
        "https://evocrawl.com/guides"
      ],
      "metadata": {
        "title": "Evocrawl - 终极网页抓取 API",
        "description": "Evocrawl 是强大的网页抓取 API，可将任意网站转化为干净且结构化的数据，供 AI 与分析使用。"
        "sourceURL": "https://evocrawl.com/",
        "statusCode": 200
      }
    }
  ]
}
```

<div id="advanced-search-options">
  ## 高级搜索选项
</div>

Evocrawl 的搜索 API 支持通过多种参数自定义搜索：

<div id="location-customization">
  ### 位置定制
</div>

<CodeGroup>
  ```python Python theme={null}
  from evocrawl import Evocrawl

  evocrawl = Evocrawl(api_key="fc-YOUR_API_KEY")

  # 带位置设置的搜索（德国）
  search_result = evocrawl.search(
      "web scraping tools",
      limit=5,
      location="Germany"
  )

  # 处理结果
  for result in search_result.data:
      print(f"标题：{result['title']}")
      print(f"URL：{result['url']}")
  ```

  ```js Node theme={null}
  import Evocrawl from '@mendable/evocrawl-js';

  const evocrawl = new Evocrawl({ apiKey: "fc-YOUR-API-KEY" });

  // 使用地理位置设置进行搜索（德国）
  const results = await evocrawl.search('web scraping tools', {
    limit: 5,
    location: "Germany"
  });

  // 处理搜索结果
  console.log(results);
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.evocrawl.com/v2/search \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer fc-YOUR_API_KEY" \
    -d '{
      "query": "网络爬取工具",
      "limit": 5,
      "location": "德国"
    }'
  ```

  ```bash CLI theme={null}
  # 根据位置搜索
  evocrawl search "local restaurants" --location "San Francisco,California,United States" --country US --pretty
  ```
</CodeGroup>

<div id="time-based-search">
  ### 基于时间的搜索
</div>

使用 `tbs` 参数按时间过滤结果。注意，`tbs` 仅适用于 `web` 源结果，不会过滤 `news` 或 `images` 结果。如果你需要按时间过滤的新闻结果，建议使用 `web` 源并配合 `site:` 运算符限定到特定新闻域名。

<CodeGroup>
  ```python Python theme={null}
  from evocrawl import Evocrawl

  evocrawl = Evocrawl(api_key="fc-你的API密钥")

  results = evocrawl.search(
      query="evocrawl",
      limit=5,
      tbs="qdr:d",
  )
  print(len(results.get('web', [])))
  ```

  ```js Node theme={null}
  import Evocrawl from '@mendable/evocrawl-js';

  const evocrawl = new Evocrawl({ apiKey: "fc-YOUR-API-KEY" });

  const results = await evocrawl.search('evocrawl', {
    limit: 5,
    tbs: 'qdr:d', // 最近一天
  });

  console.log(results.web);
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.evocrawl.com/v2/search \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer fc-YOUR_API_KEY" \
    -d '{
      "query": "最新的网页爬取技术",
      "limit": 5,
      "tbs": "qdr:w"
    }'
  ```

  ```bash CLI theme={null}
  # 使用时间过滤器搜索(过去一周)
  evocrawl search "evocrawl updates" --tbs qdr:w --limit 5 --pretty
  ```
</CodeGroup>

常用 `tbs` 值：

* `qdr:h` - 过去 1 小时
* `qdr:d` - 过去 24 小时
* `qdr:w` - 过去 1 周
* `qdr:m` - 过去 1 个月
* `qdr:y` - 过去 1 年
* `sbd:1` - 按日期排序 (最新优先)

若需更精确的时间过滤，可使用自定义日期范围格式指定确切的区间：

<CodeGroup>
  ```python Python theme={null}
  from evocrawl import Evocrawl

  # 使用你的 API key 初始化客户端
  evocrawl = Evocrawl(api_key="fc-YOUR_API_KEY")

  # 搜索 2024 年 12 月的结果
  search_result = evocrawl.search(
      "evocrawl updates",
      limit=10,
      tbs="cdr:1,cd_min:12/1/2024,cd_max:12/31/2024"
  )
  ```

  ```js JavaScript theme={null}
  import Evocrawl from '@mendable/evocrawl-js';

  // 使用你的 API key 初始化客户端
  const evocrawl = new Evocrawl({apiKey: "fc-YOUR_API_KEY"});

  // 搜索 2024 年 12 月的结果
  evocrawl.search("evocrawl updates", {
    limit: 10,
    tbs: "cdr:1,cd_min:12/1/2024,cd_max:12/31/2024"
  })
  .then(searchResult => {
    console.log(searchResult.data);
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.evocrawl.com/v2/search \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer fc-YOUR_API_KEY" \
    -d '{
      "query": "evocrawl updates",
      "limit": 10,
      "tbs": "cdr:1,cd_min:12/1/2024,cd_max:12/31/2024"
    }'
  ```
</CodeGroup>

你可以将 `sbd:1` 与时间过滤条件组合使用，在时间范围内按日期排序返回结果。例如，`sbd:1,qdr:w` 会返回过去一周内的结果，并按最新优先排序；`sbd:1,cdr:1,cd_min:12/1/2024,cd_max:12/31/2024` 会返回 2024 年 12 月内的结果，并按日期排序。

<div id="custom-timeout">
  ### 自定义超时
</div>

为搜索操作设置自定义超时时间：

<CodeGroup>
  ```python Python theme={null}
  from evocrawl import EvocrawlApp

  # 使用你的 API key 初始化客户端
  app = EvocrawlApp(api_key="fc-YOUR_API_KEY")

  # 设置 30 秒超时
  search_result = app.search(
      "complex search query",
      limit=10,
      timeout=30000  # 30 秒（毫秒）
  )
  ```

  ```js JavaScript theme={null}
  import EvocrawlApp from '@mendable/evocrawl-js';

  // 使用你的 API key 初始化客户端
  const app = new EvocrawlApp({apiKey: "fc-YOUR_API_KEY"});

  // 设置 30 秒超时
  app.search("complex search query", {
    limit: 10,
    timeout: 30000  // 30 秒（毫秒）
  })
  .then(searchResult => {
    // 处理结果
    console.log(searchResult.data);
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.evocrawl.com/v2/search \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer fc-YOUR_API_KEY" \
    -d '{
      "query": "complex search query",
      "limit": 10,
      "timeout": 30000
    }'
  ```
</CodeGroup>

<div id="zero-data-retention-zdr">
  ## 零数据保留 (ZDR)
</div>

对于有严格数据处理要求的团队，Evocrawl 可通过 `enterprise` 参数为 `/search` 端点提供零数据保留 (ZDR) 选项。ZDR 搜索功能适用于 Enterprise 计划——访问 [evocrawl.dev/enterprise](https://www.evocrawl.com/enterprise) 即可开始使用。

<Note>
  这与 `zeroDataRetention` 抓取选项不同，后者用于控制抓取操作的 ZDR。详见 [Scrape ZDR](/zh/features/scrape#zero-data-retention-zdr)。`enterprise` 参数仅适用于请求中的搜索部分。
</Note>

<div id="end-to-end-zdr">
  ### 端到端 ZDR
</div>

使用端到端 ZDR 时，Evocrawl 及我们的上游搜索服务提供商均实行零数据保留。整个流程中的任何环节都不会存储查询或结果数据。

* **成本：** 每 10 个结果 10 额度
* **参数：** `enterprise: ["zdr"]`

```bash cURL theme={null}
curl -X POST https://api.evocrawl.com/v2/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fc-YOUR_API_KEY" \
  -d '{
    "query": "sensitive topic",
    "limit": 10,
    "enterprise": ["zdr"]
  }'
```

<div id="anonymized-zdr">
  ### 匿名化 ZDR
</div>

使用匿名化 ZDR 时，Evocrawl 会在我们这一侧实施完全的零数据保留。我们的搜索提供商可能会缓存查询，但这些查询已被完全匿名化——不附带任何可识别信息。

* **成本：** 每 10 个结果 2 个额度
* **参数：** `enterprise: ["anon"]`

```bash cURL theme={null}
curl -X POST https://api.evocrawl.com/v2/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fc-YOUR_API_KEY" \
  -d '{
    "query": "sensitive topic",
    "limit": 10,
    "enterprise": ["anon"]
  }'
```

<div id="combining-search-zdr-with-scrape-zdr">
  ### 结合使用 Search ZDR 和 Scrape ZDR
</div>

如果你使用的是带内容抓取 (`scrapeOptions`) 的 search，则 `enterprise` 参数适用于搜索部分，而 `scrapeOptions` 中的 `zeroDataRetention` 则适用于抓取部分。要让这两部分都实现完整的 ZDR，请同时设置这两个参数：

```bash cURL theme={null}
curl -X POST https://api.evocrawl.com/v2/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fc-YOUR_API_KEY" \
  -d '{
    "query": "sensitive topic",
    "limit": 5,
    "enterprise": ["zdr"],
    "scrapeOptions": {
      "formats": ["markdown"],
      "zeroDataRetention": true
    }
  }'
```

<div id="cost-implications">
  ## 成本影响
</div>

每次搜索的费用为每 10 条搜索结果消耗 2 个额度，并向上取整 (1–10 条结果 = 2 个额度，11–20 条 = 4 个额度，依此类推) 。如果启用了抓取选项，每个搜索结果会按标准抓取费用计费：

* **Basic scrape**：每个网页 1 个额度
* **PDF parsing**：每个 PDF 页面 1 个额度
* **Enhanced proxy mode**：每个网页额外 4 个额度
* **JSON mode**：每个网页额外 4 个额度

为控制成本，可以：

* 如果不需要 PDF 解析，将其设置为 `parsers: []`
* 在可能的情况下使用 `proxy: "basic"` 而不是 `"enhanced"`，或者将其设置为 `"auto"`
* 使用 `limit` 参数限制搜索结果数量

<div id="advanced-scraping-options">
  ## 高级抓取选项
</div>

有关抓取选项的更多详细信息，请参阅 [Scrape 功能文档](https://docs.evocrawl.com/features/scrape)。除 FIRE-1 Agent 和 Change-Tracking 功能外，其余均受此搜索端点支持。

> 你是需要 EvoCrawl API 密钥的 AI 代理吗？请参见 [evocrawl.dev/agent-onboarding/SKILL.md](https://www.evocrawl.com/agent-onboarding/SKILL.md) 了解自动化入门说明。