Name: web-search
Author: brave

網路搜尋

需要 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 方法。長查詢或複雜的 Goggles 建議使用 POST。

認證：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 秒)
最佳用途	搜尋 UI、資料萃取、自訂排序	RAG 管線、AI 代理、事實查核	聊天介面、深入研究

參數

參數	類型	必填	預設值	說明
`q`	字串	是	-	搜尋查詢 (1-400 字元，最多 50 個單字)
`country`	字串	否	`US`	搜尋國家 (2 字母國家代碼或 `ALL`)
`search_lang`	字串	否	`en`	語言偏好 (2 字元以上語言代碼)
`ui_lang`	字串	否	`en-US`	介面語言 (例如 "en-US")
`count`	整數	否	`20`	每頁最大結果數 (1-20)
`offset`	整數	否	`0`	分頁偏移量 (0-9)
`safesearch`	字串	否	`moderate`	成人內容過濾 (`off`/`moderate`/`strict`)
`freshness`	字串	否	-	時間過濾 (`pd`/`pw`/`pm`/`py` 或日期範圍)
`text_decorations`	布林值	否	`true`	包含強調標記
`spellcheck`	布林值	否	`true`	自動修正查詢
`result_filter`	字串	否	-	過濾結果類型 (逗號分隔)
`goggles`	字串	否	-	自訂排序過濾器 (URL 或內嵌)
`extra_snippets`	布林值	否	-	每個結果最多取得 5 個額外摘要
`operators`	布林值	否	`true`	套用搜尋運算子
`units`	字串	否	-	度量單位 (`metric`/`imperial`)
`enable_rich_callback`	布林值	否	`false`	啟用豐富第三方資料回呼
`include_fetch_metadata`	布林值	否	`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`	浮點數	使用者緯度 (-90.0 至 90.0)
`X-Loc-Long`	浮點數	使用者經度 (-180.0 至 180.0)
`X-Loc-Timezone`	字串	IANA 時區 (例如 "America/San_Francisco")
`X-Loc-City`	字串	城市名稱
`X-Loc-State`	字串	州/區域代碼 (ISO 3166-2)
`X-Loc-State-Name`	字串	州/區域全名 (例如 "California")
`X-Loc-Country`	字串	2 字母國家代碼
`X-Loc-Postal-Code`	字串	郵遞區號 (例如 "94105")

優先順序：X-Loc-Lat + X-Loc-Long 優先。提供時，下游服務會直接從座標解析位置，文字型標頭 (城市、州、國家、郵遞區號) 不會用於位置解析。僅在沒有座標時提供文字型標頭。兩者都傳送不會造成問題 — 經緯度會優先採用。

回應格式

回應欄位

欄位	類型	說明
`type`	字串	固定為 `"search"`
`query.original`	字串	原始搜尋查詢
`query.altered`	字串?	經拼字檢查修正的查詢 (若有變更)
`query.cleaned`	字串?	清理/正規化後的查詢
`query.spellcheck_off`	布林值?	拼字檢查是否關閉
`query.more_results_available`	布林值	是否有更多頁面
`query.show_strict_warning`	布林值?	嚴格 SafeSearch 是否封鎖了成人結果
`query.search_operators`	物件?	已套用的搜尋運算子 (`applied`, `cleaned_query`, `sites`)
`web.type`	字串	固定為 `"search"`
`web.results[].title`	字串	頁面標題
`web.results[].url`	字串	頁面網址
`web.results[].description`	字串?	摘要/說明文字
`web.results[].age`	字串?	人類可讀的時效 (例如 "2 天前")
`web.results[].language`	字串?	內容語言代碼
`web.results[].meta_url`	物件	URL 元件 (`scheme`, `netloc`, `hostname`, `path`)
`web.results[].thumbnail`	物件?	縮圖 (`src`, `original`)
`web.results[].thumbnail.original`	字串?	原始完整尺寸圖片網址
`web.results[].thumbnail.logo`	布林值?	縮圖是否為標誌
`web.results[].profile`	物件?	發布者身分 (`name`, `url`, `long_name`, `img`)
`web.results[].page_age`	字串?	發布時間的 ISO 日期時間 (例如 `"2025-04-12T14:22:41"`)
`web.results[].extra_snippets`	列表[字串]?	最多 5 個額外摘錄
`web.results[].deep_results`	物件?	頁面中的額外連結 (`buttons`, `links`)
`web.results[].schemas`	列表?	原始 schema.org 結構化資料
`web.results[].product`	物件?	產品資訊與評論
`web.results[].recipe`	物件?	食譜詳細資訊 (食材、時間、評分)
`web.results[].article`	物件?	文章中繼資料 (作者、發布者、日期)
`web.results[].book`	物件?	書籍資訊 (作者、ISBN、評分)
`web.results[].software`	物件?	軟體產品資訊
`web.results[].rating`	物件?	綜合評分
`web.results[].faq`	物件?	頁面中的常見問題
`web.results[].movie`	物件?	電影資訊 (導演、演員、類型)
`web.results[].video`	物件?	影片中繼資料 (長度、觀看次數、創作者)
`web.results[].location`	物件?	地點/餐廳詳細資訊
`web.results[].qa`	物件?	問答資訊
`web.results[].creative_work`	物件?	創作作品資料
`web.results[].music_recording`	物件?	音樂/歌曲資料
`web.results[].organization`	物件?	組織資訊
`web.results[].review`	物件?	評論資料
`web.results[].content_type`	字串?	內容類型分類
`web.results[].fetched_content_timestamp`	整數?	擷取時間戳記 (啟用 `include_fetch_metadata=true` 時)
`web.mutated_by_goggles`	布林值	結果是否經 Goggles 重新排序
`web.family_friendly`	布林值	結果是否適合闔家觀賞
`mixed`	物件?	建議的顯示順序 (請參閱下方混合回應)
`discussions.results[]`	陣列?	論壇討論群組
`discussions.results[].data.forum_name`	字串?	論壇/社群名稱
`discussions.results[].data.num_answers`	整數?	回答/回覆數量
`discussions.results[].data.question`	字串?	討論問題
`discussions.results[].data.top_comment`	字串?	最高票評論摘錄
`faq.results[]`	陣列?	FAQ 條目
`news.results[]`	陣列?	新聞文章
`videos.results[]`	陣列?	影片結果
`infobox.results[]`	陣列?	知識圖譜條目
`locations.results[]`	陣列?	本地景點結果
`rich.hint.vertical`	字串?	豐富結果類型
`rich.hint.callback_key`	字串?	豐富資料的回呼金鑰

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`	字串	是	來自網路搜尋 `rich.hint.callback_key` 欄位的回呼金鑰

使用案例

通用搜尋整合：一次呼叫取得最豐富的結果集 (網頁、新聞、影片、討論、FAQ、資訊框、地點)。若用於 RAG/LLM 事實查核，建議使用 llm-context。
結構化資料萃取：透過 schemas 和結果上的類型化欄位取得產品、食譜、評分、文章。
使用 Goggles 自訂搜尋：Brave 獨家功能。使用內嵌規則或託管 Goggles 提升/排除網站，實現完全自訂排序。

注意事項

分頁：使用 offset (0-9) 搭配 count 進行分頁
Count：網路搜尋最多 20 筆；實際結果可能少於要求數量

web-search

相關技能