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 方法。对于长查询或复杂的 Goggles，POST 更适用。

参数

参数	类型	必填	默认值	描述
q	string	是	-	搜索查询（1-400 个字符，最多 50 个单词）
country	string	否	US	搜索国家（两位国家代码或 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	在结果中包含抓取时间戳

时效性值

值	描述
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?	如果严格安全搜索阻止了结果，则为 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?	网站图标 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 个额外摘要