news-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/news/search?q=space+exploration" \
  -H "Accept: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}"

最新新聞（過去 24 小時）

curl -s "https://api.search.brave.com/res/v1/news/search" \
  -H "Accept: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
  -G \
  --data-urlencode "q=cybersecurity" \
  --data-urlencode "country=US" \
  --data-urlencode "freshness=pd" \
  --data-urlencode "count=20"

日期範圍篩選

curl -s "https://api.search.brave.com/res/v1/news/search" \
  -H "Accept: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
  -G \
  --data-urlencode "q=climate summit" \
  --data-urlencode "freshness=2026-01-01to2026-01-31"

端點

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

驗證方式：X-Subscription-Token: <API_KEY> 標頭

注意：同時支援 GET 與 POST。POST 適用於長查詢或複雜的 Goggles。

參數

參數	型別	必填	預設值	說明
q	string	是	-	搜尋查詢（1-400 字元，最多 50 個單字）
country	string	否	US	搜尋國家（2 字母國家代碼或 ALL）
search_lang	string	否	en	語言偏好（2 個以上字元的語言代碼）
ui_lang	string	否	en-US	介面語言（例如 "en-US"）
count	int	否	20	結果數量（1-50）
offset	int	否	0	頁面偏移量（0-9）
safesearch	string	否	strict	成人內容過濾器（off/moderate/strict）
freshness	string	否	-	時間篩選（pd/pw/pm/py 或日期範圍）
spellcheck	bool	否	true	自動修正查詢
extra_snippets	bool	否	-	每個結果最多 5 個額外摘要
goggles	string 或 array	否	-	自訂排名篩選器（URL 或內嵌；重複參數以使用多個）
operators	bool	否	true	套用搜尋運算子
include_fetch_metadata	bool	否	false	在結果中包含擷取時間戳記

Freshness 值

值	說明
pd	過去一天（24 小時）- 適合即時新聞
pw	過去一週（7 天）
pm	過去一個月（31 天）
py	過去一年（365 天）
YYYY-MM-DDtoYYYY-MM-DD	自訂日期範圍

回應格式

{
  "type": "news",
  "query": {
    "original": "space exploration"
  },
  "results": [
    {
      "type": "news_result",
      "title": "New Developments in Space Exploration",
      "url": "https://news.example.com/space-exploration",
      "description": "Recent missions have advanced our understanding of...",
      "age": "2 hours ago",
      "page_age": "2026-01-15T14:30:00",
      "page_fetched": "2026-01-15T15:00:00Z",
      "meta_url": {
        "scheme": "https",
        "netloc": "news.example.com",
        "hostname": "news.example.com",
        "favicon": "https://imgs.search.brave.com/favicon/news.example.com",
        "path": "/space-exploration"
      },
      "profile": {
        "name": "Example Outlet",
        "url": "https://news.example.com/space-exploration"
      },
      "thumbnail": {
        "src": "https://imgs.search.brave.com/..."
      }
    }
  ]
}

回應欄位

欄位	型別	說明
type	string	永遠為 "news"
query.original	string	原始搜尋查詢
query.altered	string?	拼字檢查修正後的查詢（若有變更）
query.cleaned	string?	拼字檢查器清理/正規化後的查詢
query.spellcheck_off	bool?	拼字檢查是否已停用
query.show_strict_warning	bool?	若嚴格 SafeSearch 封鎖了結果則為 true
query.search_operators	object?	已套用的搜尋運算子
query.search_operators.applied	bool	運算子是否已套用
query.search_operators.cleaned_query	string?	運算子處理後的查詢
query.search_operators.sites	list[str]?	來自 site: 運算子的網域
results[].type	string	永遠為 "news_result"
results[].title	string	文章標題
results[].url	string	文章的來源 URL
results[].description	string?	文章描述/摘要
results[].age	string?	人類可讀的年齡（例如 "2 hours ago"）
results[].page_age	string?	來源的發布日期（ISO 日期時間）
results[].page_fetched	string?	頁面最後擷取時間（ISO 日期時間）
results[].fetched_content_timestamp	int?	擷取時間戳記（僅在 include_fetch_metadata=true 時）
results[].meta_url.scheme	string?	URL 協定
results[].meta_url.netloc	string?	網路位置
results[].meta_url.hostname	string?	小寫的網域名稱
results[].meta_url.favicon	string?	Favicon URL
results[].meta_url.path	string?	URL 路徑
results[].thumbnail.src	string	提供的縮圖 URL
results[].thumbnail.original	string?	原始縮圖 URL
results[].extra_snippets	list[str]?	每個結果最多 5 個額外摘要
results[].profile.name	string?	網站名稱
results[].profile.url	string?	提供設定檔的原始 URL
results[].profile.long_name	string?	網站的長名稱
results[].profile.img	string?	代表設定檔的圖片 URL

Goggles（自訂排名）— Brave 獨有

Goggles 讓您重新排名新聞結果 — 提升可信賴的來源或隱藏不想要的來源。

方法	範例
託管	--data-urlencode "goggles=https://raw.githubusercontent.com/brave/goggles-quickstart/main/goggles/hacker_news.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

資源：探索 · 語法 · 快速入門

搜尋運算子

使用搜尋運算子來精簡結果：

• site:local-paper.com - 限制為特定新聞網站
• "exact phrase" - 比對確切片語
• -exclude - 排除詞彙

設定 operators=false 以停用運算子解析。

使用案例

• 即時新聞監控：使用 freshness=pd 取得主題的最新文章。
• 使用 Goggles 自訂新聞饋送：提升可信賴的來源並隱藏其他來源 — Brave 獨有。
• 歷史新聞研究：使用 freshness=YYYY-MM-DDtoYYYY-MM-DD 尋找特定時間範圍的文章。
• 多語言新聞：結合 country、search_lang 和 ui_lang 以取得跨地區結果。
• 資料管線：設定 include_fetch_metadata=true 以在每個結果中取得 fetched_content_timestamp。

注意事項

• SafeSearch：預設為 strict
• 分頁：使用 offset（0-9）搭配 count
• 額外摘要：當 extra_snippets=true 時，最多 5 個額外摘要