AI Skills
web-search

web-search

热门

用于网络搜索。返回带有摘要、URL、缩略图的排序结果。支持新鲜度过滤、安全搜索、自定义排名的Goggles、分页。主要搜索端点。

161Star
11Fork
更新于 2026/7/8
获取 Skill源代码

相关 Skills

writing-skills23万doc-coauthoring15万brainstorming4.5万
SKILL.md
readonly只读
name
web-search
description

用于网络搜索。返回带有摘要、URL、缩略图的排序结果。支持新鲜度过滤、安全搜索、自定义排名的Goggles、分页。主要搜索端点。

网络搜索

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

套餐：包含在 搜索 套餐中。详见 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上下文 (llm-context) 答案 (answers)
输出 结构化结果（链接、摘要、元数据） 为LLM预提取的页面内容 端到端AI答案及引用
结果类型 网页、新闻、视频、讨论、FAQ、信息框、地点、富内容 提取的文本块、表格、代码 综合答案 + 来源列表
独特功能 Goggles、结构化数据 (schemas)、富回调 Token预算控制、阈值模式 多轮搜索、流式输出、兼容OpenAI SDK
速度 快速 (~0.5-1秒) 快速 (<1秒) 较慢 (~30-180秒)
最佳用途 搜索界面、数据提取、自定义排序 RAG管道、AI代理、事实依据 聊天界面、深度研究

参数

参数 类型 必填 默认值 描述
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

新鲜度值

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

结果过滤值

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

# 仅网页和视频结果
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 优先。当提供时，下游服务直接从坐标解析位置，基于文本的请求头（城市、州、国家、邮政编码）不用于位置解析。仅当没有坐标时才提供基于文本的请求头。同时发送两者不会造成问题——经纬度优先。

响应格式

响应字段

字段 类型 描述
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? 严格安全搜索是否屏蔽了成人内容
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天前"）
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? 缩略图是否为logo
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? 页面中的FAQ
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? FAQ条目
news.results[] array? 新闻文章
videos.results[] array? 视频结果
infobox.results[] array? 知识图谱条目
locations.results[] array? 本地POI结果
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 注册。内联规则无需注册。

语法：$boost=N / $downrank=N（1–10）、$discard、$site=example.com。用逗号组合：$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. 启用富回调进行搜索
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}"

# 响应包含："rich": {"hint": {"callback_key": "abc123...", "vertical": "weather"}}

# 2. 使用回调键获取富数据
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字段的回调键

使用场景

  • 通用搜索集成：一次调用获取最丰富的结果集（网页、新闻、视频、讨论、FAQ、信息框、地点）。对于RAG/LLM事实依据，推荐使用llm-context。
  • 结构化数据提取：通过schema和结果上的类型化字段获取产品、食谱、评分、文章。
  • 使用Goggles自定义搜索：Brave独有。通过内联规则或托管Goggles提升/丢弃站点，实现完全自定义排序。

注意事项

  • 分页：使用offset（0-9）配合count进行结果翻页
  • 数量：网络搜索最多20条；实际结果可能少于请求数量