> ## 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.
# Search（搜索）
`search` 端点将网页搜索与 Firecrawl 的抓取能力相结合，为任意查询返回完整页面内容。
在请求中包含 `scrapeOptions`，并设置 `formats: [{"type": "markdown"}]`，即可为每条搜索结果获取完整的 markdown 内容；否则默认只返回结果（url、title、description）。你也可以使用其他 formats，例如 `{"type": "summary"}` 来获取精简内容。
## 支持的查询运算符
我们支持多种查询运算符，帮助你更高效地筛选搜索结果。
| 运算符 | 功能 | 示例 |
| ------------- | ------------------ | --------------------------------- |
| `""` | 精确（非模糊）匹配一段文本 | `"Firecrawl"` |
| `-` | 排除特定关键词或对其他运算符取反 | `-bad`, `-site:firecrawl.dev` |
| `site:` | 仅返回来自指定网站的结果 | `site:firecrawl.dev` |
| `filetype:` | 仅返回具有特定文件扩展名的结果 | `filetype:pdf`, `-filetype:pdf` |
| `inurl:` | 仅返回在 URL 中包含某个词的结果 | `inurl:firecrawl` |
| `allinurl:` | 仅返回在 URL 中包含多个词的结果 | `allinurl:git firecrawl` |
| `intitle:` | 仅返回在页面标题中包含某个词的结果 | `intitle:Firecrawl` |
| `allintitle:` | 仅返回在页面标题中包含多个词的结果 | `allintitle:firecrawl playground` |
| `related:` | 仅返回与特定域相关的结果 | `related:firecrawl.dev` |
| `imagesize:` | 仅返回尺寸完全匹配的图片 | `imagesize:1920x1080` |
| `larger:` | 仅返回大于指定尺寸的图片 | `larger:1920x1080` |
## location 参数
使用 `location` 参数获取按地理位置定向的搜索结果。格式："string"。示例："Germany"、"San Francisco,California,United States"。
查看[支持的位置完整列表](https://firecrawl.dev/search_locations.json)，了解所有可用的国家和语言。
## country 参数
使用 `country` 参数以 ISO 国家/地区代码指定搜索结果所属国家/地区。默认值："US"。
示例："US"、"DE"、"FR"、"JP"、"UK"、"CA"。
```json theme={null}
{
"query": "餐厅",
"country": "DE"
}
```
## `categories` 参数
使用 `categories` 参数按特定类别过滤搜索结果：
* **`github`**: 在 GitHub 仓库、代码、问题和文档中搜索
* **`research`**: 搜索学术和研究类网站（arXiv、Nature、IEEE、PubMed 等）
* **`pdf`**: 搜索 PDF
### 使用示例
```json theme={null}
{
"query": "机器学习",
"categories": ["github", "research"],
"limit": 10
}
```
### 分类响应
每个结果都包含一个 `category` 字段，用于表示其来源：
```json theme={null}
{
"success": true,
"data": {
"web": [
{
"url": "https://github.com/example/ml-project",
"title": "Machine Learning Project",
"description": "Implementation of ML algorithms",
"category": "github"
},
{
"url": "https://arxiv.org/abs/2024.12345",
"title": "ML Research Paper",
"description": "Latest advances in machine learning",
"category": "research"
}
]
}
}
```
## 基于时间的搜索
使用 `tbs` 参数按时间范围过滤搜索结果，包括自定义日期区间。详细示例及支持的 formats 请参见 [Search Feature 文档](https://docs.firecrawl.dev/features/search#time-based-search)。
## OpenAPI
````yaml zh/api-reference/v2-openapi.json post /search
openapi: 3.0.0
info:
title: Firecrawl API
version: v2
description: 用于与 Firecrawl 服务交互，执行网页抓取和爬取任务的 API。
contact:
name: Firecrawl Support
url: https://firecrawl.dev/support
email: support@firecrawl.dev
servers:
- url: https://api.firecrawl.dev/v2
security:
- bearerAuth: []
paths:
/search:
post:
tags:
- Search
summary: 搜索，并可选择抓取搜索结果
operationId: searchAndScrape
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
query:
type: string
description: 搜索查询语句
limit:
type: integer
description: 返回结果的最大数量
default: 5
maximum: 100
minimum: 1
sources:
type: array
items:
oneOf:
- type: object
title: Web
properties:
type:
type: string
enum:
- web
tbs:
type: string
description: >-
用于按时间过滤结果的搜索参数。支持预设时间范围（`qdr:h`、`qdr:d`、`qdr:w`、`qdr:m`、`qdr:y`）、自定义日期范围（`cdr:1,cd_min:MM/DD/YYYY,cd_max:MM/DD/YYYY`），以及按日期排序（`sbd:1`）。这些参数值可以组合使用，例如：`sbd:1,qdr:w`。
location:
type: string
description: 用于搜索结果的 location 参数
required:
- type
- type: object
title: Images
properties:
type:
type: string
enum:
- images
required:
- type
- type: object
title: News
properties:
type:
type: string
enum:
- news
required:
- type
description: 要搜索的数据源。将决定响应中可用的数组。默认为 ['web']。
default:
- web
categories:
type: array
items:
oneOf:
- type: object
title: GitHub
properties:
type:
type: string
enum:
- github
required:
- type
- type: object
title: Research
properties:
type:
type: string
enum:
- research
required:
- type
- type: object
title: PDF
properties:
type:
type: string
enum:
- pdf
required:
- type
description: 根据类别筛选结果。默认值为 []，表示结果不会按类别进行过滤。
tbs:
type: string
description: >-
用于按时间过滤结果的搜索参数。支持预设时间范围（`qdr:h`、`qdr:d`、`qdr:w`、`qdr:m`、`qdr:y`）、自定义日期范围（`cdr:1,cd_min:MM/DD/YYYY,cd_max:MM/DD/YYYY`），以及按日期排序（`sbd:1`）。这些参数值可以组合使用，例如：`sbd:1,qdr:w`。
location:
type: string
description: >-
用于搜索结果的位置参数（例如 `San Francisco,California,United
States`）。为获得最佳效果，请同时设置该参数和 `country` 参数。
country:
type: string
description: >-
用于按地域定向搜索结果的 ISO 国家代码（例如 `US`）。为获得最佳效果，请同时设置此参数和 `location`
参数。
default: US
timeout:
type: integer
description: 超时（毫秒）
default: 60000
ignoreInvalidURLs:
type: boolean
description: >-
从搜索结果中排除对其他 Firecrawl 端点无效的 URL。这样在将搜索结果数据输送到其他 Firecrawl
API 端点时，有助于减少错误。
default: false
scrapeOptions:
allOf:
- $ref: '#/components/schemas/ScrapeOptions'
description: 抓取搜索结果的选项
default: {}
required:
- query
responses:
'200':
description: 成功的响应
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
type: object
properties:
web:
type: array
items:
type: object
properties:
title:
type: string
description: 搜索结果标题
description:
type: string
description: 搜索结果中的描述
url:
type: string
description: 搜索结果的URL
markdown:
type: string
nullable: true
description: 在请求抓取时返回的 Markdown 内容
html:
type: string
nullable: true
description: 在 formats 中请求时返回 HTML 内容
rawHtml:
type: string
nullable: true
description: 如果在 formats 中请求，则为原始 HTML 内容
links:
type: array
items:
type: string
description: 如果在指定的 formats 中请求，将返回找到的链接
screenshot:
type: string
nullable: true
description: >-
如果在 formats 中请求截图，则会返回截图 URL。截图在 24
小时后过期，届时将无法再下载。
metadata:
type: object
properties:
title:
type: string
description:
type: string
sourceURL:
type: string
description: 发起请求时使用的原始 URL。如果发生重定向，可能与最终页面的 URL 不一致。
url:
type: string
description: 跟随所有重定向后得到的最终页面 URL。
statusCode:
type: integer
error:
type: string
nullable: true
images:
type: array
items:
type: object
properties:
title:
type: string
description: 搜索结果中的标题
imageUrl:
type: string
description: 图片 URL
imageWidth:
type: integer
description: 图片宽度
imageHeight:
type: integer
description: 图像高度
url:
type: string
description: 搜索结果的URL
position:
type: integer
description: 搜索结果的位置
news:
type: array
items:
type: object
properties:
title:
type: string
description: 文章标题
snippet:
type: string
description: 文章摘录
url:
type: string
description: 文章的 URL 地址
date:
type: string
description: 文章日期
imageUrl:
type: string
description: 文章图片的 URL
position:
type: integer
description: 文章位置
markdown:
type: string
nullable: true
description: 在请求抓取时返回的 Markdown 内容
html:
type: string
nullable: true
description: 在 formats 中请求时返回的 HTML 内容
rawHtml:
type: string
nullable: true
description: 在 formats 中请求时返回的原始 HTML 内容
links:
type: array
items:
type: string
description: 如果在 formats 中请求，则返回找到的链接
screenshot:
type: string
nullable: true
description: >-
如果在 formats 中请求截图，将返回其 URL。截图会在 24
小时后过期，之后将无法再下载。
metadata:
type: object
properties:
title:
type: string
description:
type: string
sourceURL:
type: string
description: 发起请求时使用的原始 URL。如果发生重定向，可能与最终页面的 URL 不一致。
url:
type: string
description: 跟随所有重定向后得到的最终页面 URL。
statusCode:
type: integer
error:
type: string
nullable: true
description: 搜索结果。可用的数组取决于你在请求中指定的源。默认情况下会返回 `web` 数组。
warning:
type: string
nullable: true
description: 在出现任何问题时显示的警告消息
id:
type: string
description: 搜索作业的 ID
creditsUsed:
type: integer
description: 本次搜索消耗的积分数量
'408':
description: 请求超时
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
example: Request timed out
'500':
description: 服务器错误
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
code:
type: string
example: UNKNOWN_ERROR
error:
type: string
example: An unexpected error occurred on the server.
security:
- bearerAuth: []
components:
schemas:
ScrapeOptions:
type: object
properties:
formats:
$ref: '#/components/schemas/Formats'
onlyMainContent:
type: boolean
description: 仅返回页面的主要内容，不包含 header、nav、footer 等元素。
default: true
includeTags:
type: array
items:
type: string
description: 在输出中要包含的标签。
excludeTags:
type: array
items:
type: string
description: 在输出中需要排除的标签。
maxAge:
type: integer
description: >-
如果页面的缓存版本的生成时间距今少于该毫秒数，则返回该缓存页面；如果缓存版本距今超过该时间，则会重新抓取页面。若你不需要特别新的数据，启用此选项可将抓取速度提升至
5 倍。默认值为 2 天。
default: 172800000
headers:
type: object
description: 随请求发送的请求头。可用于传递 cookies、User-Agent 等信息。
waitFor:
type: integer
description: 指定在抓取内容前的延迟时间（毫秒），以便页面有足够时间完成加载。该等待时间是在 Firecrawl 的智能等待功能基础上的额外等待。
default: 0
mobile:
type: boolean
description: 若要模拟在移动设备上进行抓取，请将其设置为 true。适用于测试响应式页面并获取移动端截图。
default: false
skipTlsVerification:
type: boolean
description: 在发起请求时跳过 TLS 证书验证。
default: true
timeout:
type: integer
description: 请求超时时间（毫秒）。默认 30000（30 秒），最大 300000（300 秒）。
default: 30000
maximum: 300000
parsers:
type: array
description: >-
用于控制在抓取过程中如何处理文件。包含 "pdf" 时（默认），会提取 PDF 内容并转换为 Markdown 格式，计费基于页数（每页
1 点数）。当传入空数组时，会以 base64 编码返回整个 PDF 文件，并对整份 PDF 按单一费率收取 1 点数。
items:
oneOf:
- type: object
properties:
type:
type: string
enum:
- pdf
mode:
type: string
enum:
- fast
- auto
- ocr
default: auto
description: >-
PDF 解析模式。"fast"：仅执行基于文本的提取（提取内嵌文本，速度最快）。"auto"（默认）：优先尝试
fast 提取，如有需要再回退到 OCR。"ocr"：对每一页强制执行 OCR 识别。
maxPages:
type: integer
minimum: 1
maximum: 10000
description: 从该 PDF 中最多解析的页数。必须为不超过 10000 的正整数。
required:
- type
additionalProperties: false
default:
- pdf
actions:
type: array
description: 在抓取页面内容之前需要执行的页面 actions
items:
oneOf:
- title: Wait
oneOf:
- type: object
title: Wait by Duration
properties:
type:
type: string
enum:
- wait
description: 等待指定的毫秒数
milliseconds:
type: integer
minimum: 1
description: 要等待的毫秒数
required:
- type
- milliseconds
additionalProperties: false
- type: object
title: Wait for Element
properties:
type:
type: string
enum:
- wait
description: 等待特定元素出现
selector:
type: string
description: 用于等待的 CSS 选择器
example: '#my-element'
required:
- type
- selector
additionalProperties: false
- type: object
title: Screenshot
properties:
type:
type: string
enum:
- screenshot
description: 截取屏幕截图。链接将在响应的 `actions.screenshots` 数组中返回。
fullPage:
type: boolean
description: 是否捕获整个页面的截图（忽略 viewport.height），还是仅截取当前视口区域。
default: false
quality:
type: integer
description: 截图质量，取值范围为 1 到 100，100 为最高质量。
viewport:
type: object
properties:
width:
type: integer
description: 以像素为单位的视口宽度
height:
type: integer
description: 视口高度（以像素为单位）
required:
- width
- height
required:
- type
- type: object
title: Click
properties:
type:
type: string
enum:
- click
description: 单击一个元素
selector:
type: string
description: 用于查找元素的查询选择器
example: '#load-more-button'
all:
type: boolean
description: 点击所有匹配该选择器的元素，而不仅仅是第一个。即使没有任何元素匹配该选择器，也不会抛出错误。
default: false
required:
- type
- selector
- type: object
title: Write text
properties:
type:
type: string
enum:
- write
description: >-
向输入框、文本区域或 contenteditable
元素写入文本。注意：在写入之前，你必须先使用「click」操作使该元素获得焦点。文本将以逐字符方式输入，以模拟键盘输入。
text:
type: string
description: 要键入的文本
example: Hello, world!
required:
- type
- text
- type: object
title: Press a key
description: >-
请在页面上按下一个按键。按键代码请参见：https://asawicki.info/nosense/doc/devices/keyboard/key_codes.html。
properties:
type:
type: string
enum:
- press
description: 在页面上按下任意键
key:
type: string
description: 要按的键
example: Enter
required:
- type
- key
- type: object
title: Scroll
properties:
type:
type: string
enum:
- scroll
description: 滚动整个页面或某个特定元素
direction:
type: string
enum:
- up
- down
description: 滚动方向
default: down
selector:
type: string
description: 用于滚动的元素选择器
example: '#my-element'
required:
- type
- type: object
title: Scrape
properties:
type:
type: string
enum:
- scrape
description: 抓取当前页面内容，并返回其 URL 和 HTML。
required:
- type
- type: object
title: Execute JavaScript
properties:
type:
type: string
enum:
- executeJavascript
description: 在页面上执行 JavaScript 代码
script:
type: string
description: 待执行的 JavaScript 代码
example: document.querySelector('.button').click();
required:
- type
- script
- type: object
title: Generate PDF
properties:
type:
type: string
enum:
- pdf
description: 生成当前页面的 PDF 文件。该 PDF 文件会通过响应中的 `actions.pdfs` 数组返回。
format:
type: string
enum:
- A0
- A1
- A2
- A3
- A4
- A5
- A6
- Letter
- Legal
- Tabloid
- Ledger
description: 生成的 PDF 的页面大小
default: Letter
landscape:
type: boolean
description: 是否以横向方向生成 PDF
default: false
scale:
type: number
description: 生成 PDF 的缩放比例
default: 1
required:
- type
location:
type: object
description: 请求的地理位置设置。指定后，如果有可用的代理，将使用合适的代理，并模拟相应的语言和时区设置。如果未指定，则默认为“US”。
properties:
country:
type: string
description: ISO 3166-1 alpha-2 国家/地区代码（例如：“US”、“AU”、“DE”、“JP”）
pattern: ^[A-Z]{2}$
default: US
languages:
type: array
description: >-
按优先级排序的请求首选语言和区域设置。默认为指定位置的语言。详情请参阅：https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language
items:
type: string
example: en-US
removeBase64Images:
type: boolean
description: 从输出中移除所有 Base64 编码图片，以避免内容过于冗长。图片的 alt 文本会保留在输出中，但其 URL 会被占位符替换。
default: true
blockAds:
type: boolean
description: 启用广告拦截和 Cookie 弹窗拦截功能。
default: true
proxy:
type: string
enum:
- basic
- enhanced
- auto
description: |-
指定要使用的代理类型。
- **basic**：用于抓取几乎没有或只有基础反爬策略的网站的代理。速度快，通常可用。
- **enhanced**：用于抓取具有高级反爬策略的网站的增强型代理。速度较慢，但在某些站点上更可靠。每个请求最多消耗 5 点积分。
- **auto**：当 basic 代理抓取失败时，Firecrawl 会自动重试并切换为 enhanced 代理。如果使用 enhanced 重试成功，该次抓取将收取 5 点积分；如果使用 basic 一次就成功，则只按常规定价计费。
default: auto
storeInCache:
type: boolean
description: >-
如果为 true，该页面会存储到 Firecrawl 的索引和缓存中。如果你的抓取操作可能涉及数据保护方面的顾虑，将其设置为 false
会很有用。使用某些与敏感抓取相关的参数（例如 actions、headers）时，会被强制将此参数设为 false。
default: true
Formats:
type: array
items:
oneOf:
- type: object
title: Markdown
properties:
type:
type: string
enum:
- markdown
required:
- type
- type: object
title: Summary
properties:
type:
type: string
enum:
- summary
required:
- type
- type: object
title: HTML
properties:
type:
type: string
enum:
- html
required:
- type
- type: object
title: Raw HTML
properties:
type:
type: string
enum:
- rawHtml
required:
- type
- type: object
title: Links
properties:
type:
type: string
enum:
- links
required:
- type
- type: object
title: Images
properties:
type:
type: string
enum:
- images
required:
- type
- type: object
title: Screenshot
properties:
type:
type: string
enum:
- screenshot
fullPage:
type: boolean
description: 是否捕获整个页面的截图（忽略 viewport.height），还是仅截取当前视口区域。
default: false
quality:
type: integer
description: 截图质量，范围为 1 到 100，100 为最高质量。
viewport:
type: object
properties:
width:
type: integer
description: 视口宽度（像素）
height:
type: integer
description: 视口高度（像素）
required:
- width
- height
required:
- type
- type: object
title: JSON
properties:
type:
type: string
enum:
- json
schema:
type: object
description: >-
用于 JSON 输出的 Schema，必须符合 [JSON
Schema](https://json-schema.org/) 规范。
prompt:
type: string
description: 用于生成 JSON 输出的提示
required:
- type
- type: object
title: Change Tracking
properties:
type:
type: string
enum:
- changeTracking
modes:
type: array
items:
type: string
enum:
- git-diff
- json
description: 用于变更跟踪的模式。`git-diff` 提供详细的差异对比，而 `json` 则对比提取出的 JSON 数据。
schema:
type: object
description: >-
在使用「json」模式进行 JSON 提取时所用的 schema。用于定义要提取和对比的数据结构。必须符合 [JSON
Schema](https://json-schema.org/) 标准。
prompt:
type: string
description: 在使用 `json` 模式进行变更跟踪时要使用的提示词。如果未提供，将使用默认提示词。
tag:
type: string
nullable: true
default: null
description: >-
用于变更跟踪的标签。标签可以将变更跟踪历史划分为不同的「分支」，带有特定标签的变更跟踪只会与同一标签下的抓取结果进行比较。如果未提供，则会使用默认标签（null）。
required:
- type
- type: object
title: Branding
properties:
type:
type: string
enum:
- branding
required:
- type
description: >-
要在响应中包含的输出 formats。你可以指定一个或多个
formats，既可以使用字符串（例如：`'markdown'`），也可以使用带有其他选项的对象（例如：`{ type: 'json',
schema: {...} }`）。某些 formats 需要配置特定选项。示例：`['markdown', { type: 'json',
schema: {...} }]`。
default:
- markdown
securitySchemes:
bearerAuth:
type: http
scheme: bearer
````