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	搜索国家（2 个字母的国家代码或 ALL）
search_lang	string	否	en	语言偏好（至少 2 个字符的语言代码）
ui_lang	string	否	en-US	UI 语言（例如，“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 datetime）
results[].page_fetched	string?	页面上次抓取时间（ISO datetime）
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 条额外摘录