> ## Documentation Index
> Fetch the complete documentation index at: https://student-213fb9fc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 搜索

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

Firecrawl 的搜索 API 允许你进行网页搜索，并可选在一次操作中抓取搜索结果。

* 选择特定输出 formats（markdown、HTML、links、screenshots）
* 使用可自定义参数（如 location）进行网页搜索
* 可选以多种 formats 从搜索结果中提取内容
* 控制结果数量并设置超时

详情参见 [Search Endpoint API Reference](https://docs.firecrawl.dev/api-reference/endpoint/search)。

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

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

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

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

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

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

  from firecrawl import Firecrawl

  firecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")
  ```

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

  import Firecrawl from '@mendable/firecrawl-js';

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

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

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

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

<CodeGroup>
  ```python Python theme={null}
  from firecrawl import Firecrawl

  firecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")

  results = firecrawl.search(
      query="Firecrawl",
      limit=3,
  )
  print(results)
  ```

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

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

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

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

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

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

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

```json JSON theme={null}
{
  "success": true,
  "data": {
    "web": [
      {
        "url": "https://www.firecrawl.dev/",
        "title": "Firecrawl - 面向 AI 的 Web 数据 API",
        "description": "用于 AI 的网页爬取、抓取与搜索 API。为规模而建。Firecrawl 将整个互联网送达 AI 代理与开发者。",
        "position": 1
      },
      {
        "url": "https://github.com/firecrawl/firecrawl",
        "title": "mendableai/firecrawl：将整站转换为可供 LLM 使用的内容 - GitHub",
        "description": "Firecrawl 是一项 API 服务，接收一个 URL，对其进行爬取，并将其转换为干净的 Markdown 或结构化数据。",
        "position": 2
      },
      ...
    ],
    "images": [
      {
        "title": "快速上手 | Firecrawl",
        "imageUrl": "https://mintlify.s3.us-west-1.amazonaws.com/firecrawl/logo/logo.png",
        "imageWidth": 5814,
        "imageHeight": 1200,
        "url": "https://docs.firecrawl.dev/",
        "position": 1
      },
      ...
    ],
    "news": [
      {
        "title": "Y Combinator 创业公司 Firecrawl 准备出资 100 万美元雇用三名 AI 代理作为员工",
        "url": "https://techcrunch.com/2025/05/17/y-combinator-startup-firecrawl-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.firecrawl.dev/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.firecrawl.dev/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.firecrawl.dev/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.firecrawl.dev/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.firecrawl.dev/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.firecrawl.dev/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.firecrawl.dev/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 firecrawl import Firecrawl

  firecrawl = Firecrawl(api_key="fc-YOUR_API_KEY")

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

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

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

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

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

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

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

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

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

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

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

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

<CodeGroup>
  ```python Python theme={null}
  from firecrawl import Firecrawl

  firecrawl = Firecrawl(api_key="fc-YOUR_API_KEY")

  # 带位置设置的搜索（德国）
  search_result = firecrawl.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 Firecrawl from '@mendable/firecrawl-js';

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

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

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

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

  ```bash CLI theme={null}
  # 根据位置搜索
  firecrawl 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 firecrawl import Firecrawl

  firecrawl = Firecrawl(api_key="fc-你的API密钥")

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

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

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

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

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

  ```bash cURL theme={null}
  curl -X POST https://api.firecrawl.dev/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}
  # 使用时间过滤器搜索(过去一周)
  firecrawl search "firecrawl 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 firecrawl import Firecrawl

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

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

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

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

  // 搜索 2024 年 12 月的结果
  firecrawl.search("firecrawl 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.firecrawl.dev/v2/search \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer fc-YOUR_API_KEY" \
    -d '{
      "query": "firecrawl 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 firecrawl import FirecrawlApp

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

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

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

  // 使用你的 API key 初始化客户端
  const app = new FirecrawlApp({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.firecrawl.dev/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="cost-implications">
  ## 成本影响
</div>

每次搜索的费用为每 10 条搜索结果消耗 2 个积分。如果启用了抓取选项，每个搜索结果会按标准抓取费用计费：

* **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.firecrawl.dev/features/scrape)。除 FIRE-1（代理）和 changeTracking 功能外，其余均受此 Search 端点支持。