web-search

网页搜索

需要 API 密钥：请在 https://api.search.brave.com 获取

套餐：已包含在 Search 套餐中。请参阅 https://api-dashboard.search.brave.com/app/subscriptions/subscribe

快速入门（cURL）

基本搜索

curl -s "https://api.search.brave.com/res/v1/web/search?q=python+web+frameworks" \
  -H "Accept: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}"

使用参数

curl -s "https://api.search.brave.com/res/v1/web/search" \
  -H "Accept: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
  -G \
  --data-urlencode "q=rust programming tutorials" \
  --data-urlencode "country=US" \
  --data-urlencode "search_lang=en" \
  --data-urlencode "count=10" \
  --data-urlencode "safesearch=moderate" \
  --data-urlencode "freshness=pm"

端点

GET https://api.search.brave.com/res/v1/web/search
POST https://api.search.brave.com/res/v1/web/search

注意：支持 GET 和 POST 方法。POST 适用于较长的查询或复杂的 Goggles。

身份验证：X-Subscription-Token: <API_KEY> 请求头

可选请求头：

• Accept-Encoding: gzip — 启用 gzip 压缩

何时使用网页搜索

功能	网页搜索（此工具）	大模型上下文（llm-context）	Answers（answers）
输出	结构化结果（链接、摘要、元数据）	为大模型预先提取的页面内容	带引用的端到端 AI 答案
结果类型	网页、新闻、视频、讨论、常见问题、信息框、地点、富媒体	提取的文本片段、表格、代码	综合答案 + 来源列表
独特功能	Goggles、结构化数据（schemas）、富媒体回调	Token 预算控制、阈值模式	多轮搜索、流式传输、兼容 OpenAI SDK
速度	快（约 0.5-1 秒）	快（<1 秒）	较慢（约 30-180 秒）
最适用于	搜索界面、数据提取、自定义排序	RAG 工作流、AI Agent、信息溯源	聊天界面、深入研究

参数

参数	类型	必填	默认值	说明
q	string	是	-	搜索查询（1-400 个字符，最多 50 个单词）
country	string	否	US	搜索国家（2 个字母的国家代码或 ALL）
search_lang	string	否	en	语言偏好（至少 2 个字符的语言代码）
ui_lang	string	否	en-US	UI 语言（例如，“en-US”）
count	int	否	20	每页结果数上限（1-20）
offset	int	否	0	分页偏移量（0-9）
safesearch	string	否	moderate	成人内容过滤器（off/moderate/strict）
freshness	string	否	-	时间过滤器（pd/pw/pm/py 或日期范围）
text_decorations	bool	否	true	包含高亮标记
spellcheck	bool	否	true	自动更正查询
result_filter	string	否	-	过滤结果类型（以逗号分隔）
goggles	string	否	-	自定义排序过滤器（URL 或内联内容）
extra_snippets	bool	否	-	每条结果最多获取 5 条额外摘要
operators	bool	否	true	应用搜索运算符
units	string	否	-	测量单位（metric/imperial）
enable_rich_callback	bool	否	false	启用富媒体第三方数据回调
include_fetch_metadata	bool	否	false	在结果中包含 fetched_content_timestamp

Freshness 值

值	说明
pd	过去一天（24 小时）
pw	过去一周（7 天）
pm	过去一个月（31 天）
py	过去一年（365 天）
YYYY-MM-DDtoYYYY-MM-DD	自定义日期范围

Result Filter 值

过滤类型：discussions、faq、infobox、news、query、videos、web、locations

# Only web and video results
curl "...&result_filter=web,videos"

位置标头（可选）

对于需要感知位置的结果，请添加这些标头。已知坐标时，纬度/经度就足够了——只有在无法获取坐标时，才需要将其他标头作为备用方案。

标头	类型	描述
X-Loc-Lat	float	用户纬度（-90.0 至 90.0）
X-Loc-Long	float	用户经度（-180.0 至 180.0）
X-Loc-Timezone	string	IANA 时区（例如："America/San_Francisco"）
X-Loc-City	string	城市名称
X-Loc-State	string	州/地区代码（ISO 3166-2）
X-Loc-State-Name	string	州/地区全称（例如："California"）
X-Loc-Country	string	2 字母国家代码
X-Loc-Postal-Code	string	邮政编码（例如："94105"）

优先级：X-Loc-Lat + X-Loc-Long 优先级最高。提供这两项后，下游服务会直接根据坐标解析位置，不会使用基于文本的标头（City、State、Country、Postal-Code）来解析位置。只有在没有坐标时，才提供基于文本的标头。同时发送两者不会造成问题——纬度/经度始终优先。

响应格式

响应字段

字段	类型	描述
type	string	始终为 "search"
query.original	string	原始搜索查询
query.altered	string?	拼写检查更正后的查询（如有更改）
query.cleaned	string?	清理/规范化后的查询
query.spellcheck_off	bool?	是否禁用了拼写检查
query.more_results_available	bool	是否还有更多页面
query.show_strict_warning	bool?	如果严格安全搜索屏蔽了成人内容结果，则为 True
query.search_operators	object?	应用的搜索运算符（applied、cleaned_query、sites）
web.type	string	始终为 "search"
web.results[].title	string	页面标题
web.results[].url	string	页面 URL
web.results[].description	string?	摘要/描述文本
web.results[].age	string?	易读的时间信息（例如，“2 days ago”）
web.results[].language	string?	内容语言代码
web.results[].meta_url	object	URL 组件（scheme、netloc、hostname、path）
web.results[].thumbnail	object?	缩略图（src、original）
web.results[].thumbnail.original	string?	原始全尺寸图片 URL
web.results[].thumbnail.logo	bool?	缩略图是否为徽标
web.results[].profile	object?	发布者身份信息（name、url、long_name、img）
web.results[].page_age	string?	发布日期的 ISO 日期时间（例如，"2025-04-12T14:22:41"）
web.results[].extra_snippets	list[str]?	最多 5 条额外摘录
web.results[].deep_results	object?	页面中的其他链接（buttons、links）
web.results[].schemas	list?	原始 schema.org 结构化数据
web.results[].product	object?	产品信息和评价
web.results[].recipe	object?	食谱详情（配料、时间、评分）
web.results[].article	object?	文章元数据（作者、发布者、日期）
web.results[].book	object?	图书信息（作者、ISBN、评分）
web.results[].software	object?	软件产品信息
web.results[].rating	object?	综合评分
web.results[].faq	object?	页面中找到的常见问题
web.results[].movie	object?	电影信息（导演、演员、类型）
web.results[].video	object?	视频元数据（时长、观看次数、创作者）
web.results[].location	object?	地点/餐厅详情
web.results[].qa	object?	问答信息
web.results[].creative_work	object?	创意作品数据
web.results[].music_recording	object?	音乐/歌曲数据
web.results[].organization	object?	组织信息
web.results[].review	object?	评价数据
web.results[].content_type	string?	内容类型分类
web.results[].fetched_content_timestamp	int?	抓取时间戳（使用 include_fetch_metadata=true 时）
web.mutated_by_goggles	bool	结果是否经 Goggles 重新排序
web.family_friendly	bool	结果是否适合家庭浏览
mixed	object?	首选显示顺序（见下方“混合响应”）
discussions.results[]	array?	论坛讨论聚类
discussions.results[].data.forum_name	string?	论坛/社区名称
discussions.results[].data.num_answers	int?	答复/回复数量
discussions.results[].data.question	string?	讨论问题
discussions.results[].data.top_comment	string?	得票最高的评论摘录
faq.results[]	array?	常见问题条目
news.results[]	array?	新闻文章
videos.results[]	array?	视频结果
infobox.results[]	array?	知识图谱条目
locations.results[]	array?	本地兴趣点结果
rich.hint.vertical	string?	富结果类型
rich.hint.callback_key	string?	富数据的回调键

JSON 示例

{
  "type": "search",
  "query": {
    "original": "python frameworks",
    "altered": "python web frameworks",
    "spellcheck_off": false,
    "more_results_available": true
  },
  "web": {
    "type": "search",
    "results": [
      {
        "title": "Top Python Web Frameworks",
        "url": "https://example.com/python-frameworks",
        "description": "A comprehensive guide to Python web frameworks...",
        "age": "2 days ago",
        "language": "en",
        "meta_url": {
          "scheme": "https",
          "netloc": "example.com",
          "hostname": "example.com",
          "path": "/python-frameworks"
        },
        "thumbnail": {
          "src": "https://...",
          "original": "https://original-image-url.com/img.jpg"
        },
        "extra_snippets": ["Additional excerpt 1...", "Additional excerpt 2..."]
      }
    ],
    "family_friendly": true
  },
  "mixed": {
    "type": "mixed",
    "main": [
      {"type": "web", "index": 0, "all": false},
      {"type": "web", "index": 1, "all": false},
      {"type": "videos", "all": true}
    ],
    "top": [],
    "side": []
  },
  "videos": { "...": "..." },
  "news": { "...": "..." },
  "rich": {
    "type": "rich",
    "hint": {
      "vertical": "weather",
      "callback_key": "<callback_key_hex>"
    }
  }
}

混合响应

mixed 对象定义了不同类型结果的首选显示顺序。它包含三个数组：

数组	用途
main	主要结果列表（按顺序显示的结果序列）
top	显示在主要结果上方的结果
side	与主要结果并列显示的结果（例如，信息框）

每个条目都是一个 ResultReference，包含 type（例如 "web"、"videos"）、index（指向相应结果数组的索引）和 all（设为 true 可在此位置纳入该类型的所有结果）。

搜索运算符

运算符	语法	说明
站点	site:example.com	将结果限制在特定域名
文件扩展名	ext:pdf	查找具有特定文件扩展名的结果
文件类型	filetype:pdf	查找以特定文件类型创建的结果
标题中	intitle:python	查找标题中包含指定词语的页面
正文中	inbody:tutorial	查找正文中包含指定词语的页面
页面中	inpage:guide	查找标题或正文中包含指定词语的页面
语言	lang:es	查找使用特定语言的页面（ISO 639-1）
位置	loc:us	查找来自特定国家/地区的页面（ISO 3166-1 alpha-2）
包含	+term	强制包含某个词语
排除	-term	排除包含某个词语的页面
精确匹配	"exact phrase"	按顺序匹配确切短语
AND	term1 AND term2	必须包含两个词语（大写）
OR / NOT	term1 OR term2、NOT term	逻辑运算符（大写）

设置 operators=false 可禁用运算符解析。

Goggles（自定义排名）——Brave 独有

Goggles 可让你重新排列搜索结果——提升可信来源的排名、抑制 SEO 垃圾内容，或构建有针对性的搜索范围。

方法	示例
托管	--data-urlencode "goggles=https://raw.githubusercontent.com/brave/goggles-quickstart/main/goggles/rust_programming.goggle"
内联	--data-urlencode 'goggles=$discard\n$site=example.com'

托管 Goggles 必须位于 GitHub/GitLab 上，包含 ! name:、! description:、! author: 标头，并在 https://search.brave.com/goggles/create 注册。内联规则无需注册。

语法：规则以 $ 开头，后接逗号分隔的选项。操作（任选其一）：discard、boost[=N]、downrank[=N]——N 为 1–10 的整数。站点过滤器：site=DOMAIN。示例：$site=example.com,boost=3。使用 \n（%0A）分隔规则。

允许列表：$discard\n$site=docs.python.org\n$site=developer.mozilla.org——屏蔽列表：$discard,site=pinterest.com\n$discard,site=quora.com

资源：发现 · 语法 · 快速入门

丰富数据增强

对于天气、股票、体育、货币等查询，请使用丰富数据回调工作流：

# 1. Search with rich callback enabled
curl -s "https://api.search.brave.com/res/v1/web/search?q=weather+san+francisco&enable_rich_callback=true" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}"

# Response includes: "rich": {"hint": {"callback_key": "abc123...", "vertical": "weather"}}

# 2. Get rich data with the callback key
curl -s "https://api.search.brave.com/res/v1/web/rich?callback_key=abc123..." \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}"

支持的丰富数据类型：计算器、定义、单位换算、Unix 时间戳、包裹追踪、股票、货币、加密货币、天气、美式橄榄球、棒球、篮球、板球、足球、冰球、Web3、翻译器

丰富数据回调端点

GET https://api.search.brave.com/res/v1/web/rich

参数	类型	必需	说明
callback_key	string	是	来自网页搜索 rich.hint.callback_key 字段的回调密钥

使用场景

• 通用搜索集成：一次调用即可获取最丰富的结果集（网页、新闻、视频、讨论、常见问题、信息框、位置）。用于 RAG/LLM 内容依据时，优先使用 llm-context。
• 结构化数据提取：通过 schemas 和结果中的类型化字段提取产品、食谱、评分和文章。
• 使用 Goggles 自定义搜索：Brave 独有。通过内联规则或托管 Goggles 提升或舍弃站点，实现完全自定义的排名。

注意事项

• 分页：使用 offset（0–9）和 count 对结果分页
• 数量：网页搜索最多为 20 条；实际结果可能少于请求数量