> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Brave 搜索结果 API

> 针对一个查询返回 Brave 自有索引的自然搜索结果、FAQ、知识面板、新闻、视频、讨论和地点。

`BRAVE_SEARCH` 用一个查询打开 Brave 的结果页，返回自然搜索结果、广告、FAQ、知识面板、新闻、视频、讨论、地点和相关查询。Brave 用自己的索引作答并在服务端渲染页面，所以结果随页面一起返回，浏览器不运行。

| | |
| - | - |
| `taskType` | `BRAVE_SEARCH` |
| 输入 | `query` 或 `prompt`(必填)，600 字符、75 词以内；`country`、`lang`、`safesearch`、`freshness`、`page` |
| 额度 | 每个任务 0.3 |
| 国家 | 默认 `US`。以下是 Brave 的市场。 |
| 位置 | 不支持(`422 LOCATION_UNSUPPORTED`)。 |

## 请求

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "BRAVE_SEARCH", "payload": { "query": "热泵在寒冷天气如何工作", "country": "CN" } }'
```

任务异步执行。按[异步任务](https://docs.querying.ai/zh/concepts/async-tasks.md)读取结果。

## 参数

| 字段 | 必填 | 说明 |
| - | - | - |
| `query` | 是，或 `prompt` | 搜索查询，600 字符、75 词以内。 |
| `prompt` | 是，或 `query` | 没有 `query` 时接受。两者都发时 `BRAVE_SEARCH` 读取 `query`。 |
| `country` | 否 | 要搜索的市场：`AR`、`AU`、`AT`、`BE`、`BR`、`CA`、`CL`、`DK`、`FI`、`FR`、`DE`、`GR`、`HK`、`IN`、`ID`、`IT`、`JP`、`KR`、`MY`、`MX`、`NL`、`NZ`、`NO`、`CN`、`PL`、`PT`、`PH`、`RU`、`SA`、`ZA`、`ES`、`SE`、`CH`、`TW`、`TR`、`GB`、`US` 或 `ALL`。默认 `US`，`ALL` 搜索所有市场。 |
| `lang` | 否 | 结果语言，Brave 的代码，例如 `en`、`ko`、`ja`、`de`、`pt-br`、`zh-hant`。默认取国家的语言。 |
| `safesearch` | 否 | `off`、`moderate`(默认)、`strict`。 |
| `freshness` | 否 | `pd`(过去一天)、`pw`(过去一周)、`pm`(过去一月)、`py`(过去一年)，或 `YYYY-MM-DDtoYYYY-MM-DD` 范围。 |
| `page` | 否 | 结果页，1 到 10。每页最多 20 条结果，Brave 每次只前进一小段，因此相邻页会重叠。 |

## 响应

只包含响应中出现的块，缺少的块会省略。

```json theme={"theme":"css-variables"}
{
  "organicResults": [
    { "position": 1, "title": "...", "link": "https://...", "snippet": "...", "date": "2026-11-13T04:00:00.000Z", "siteName": "...", "extraSnippets": ["..."] }
  ],
  "ads": [{ "position": 1, "title": "...", "link": "https://...", "description": "...", "displayedLink": "..." }],
  "peopleAlsoAsk": [{ "question": "...", "snippet": "...", "link": "https://..." }],
  "knowledgeGraph": { "title": "...", "type": "...", "description": "...", "attributes": [{ "key": "...", "value": "..." }], "profiles": ["https://..."] },
  "topStories": [{ "title": "...", "link": "https://...", "source": "...", "date": "2 days ago", "snippet": "..." }],
  "videoResults": [{ "title": "...", "link": "https://...", "platform": "...", "duration": "1:02", "views": 1234 }],
  "discussions": [{ "position": 1, "title": "...", "link": "https://...", "source": "...", "question": "...", "topComment": "..." }],
  "locations": [{ "position": 1, "title": "...", "link": "https://...", "address": "...", "coordinates": { "latitude": 37.5, "longitude": 127 } }],
  "alteredQuery": "...",
  "relatedSearches": [{ "query": "...", "link": "https://..." }],
  "moreResultsAvailable": true,
  "page": 1
}
```

| 字段 | 说明 |
| - | - |
| `organicResults` | 始终存在。`position` 在每页从 1 计。`snippet` 是 Brave 的描述，保留其标记。`date` 在页面于摘录前印出日期时原样保留。`siteName` 是发布者名称。 |
| `ads` | 广告：广告主的落地 `link` 与显示的 `displayedLink`。Brave 把它插在自然结果之间，`position` 即该顺序。 |
| `peopleAlsoAsk` | Brave 的 FAQ 块：`question`、作为 `snippet` 的答案，以及答案来源页面。 |
| `knowledgeGraph` | 知识面板：标题、分类、描述、`attributes` 中的事实，以及 `profiles` 的官方页面。 |
| `topStories` | 新闻结果。`date` 是 Brave 的表述("2 days ago")。 |
| `videoResults` | 视频：`platform`、`channel`、`duration`、`views`。 |
| `discussions` | 论坛帖子。Brave 提供时一并返回帖子的 `question` 与 `topComment`。 |
| `locations` | 位置查询的地点：`address`、`coordinates`、`phoneNumber`、`openingHours` 与提供方的 `link`。 |
| `alteredQuery` | Brave 的拼写检查在搜索前改了查询时出现。 |
| `relatedSearches` | Brave 的相关查询，以及执行每条的 `link`。 |
| `moreResultsAvailable` | 本页之后还有结果时为 `true`。 |
| `page` | 返回的页。 |

没有 HTML payload，因此 `include` 没有可添加的内容。

Brave API 条款限制超出应用运行所需范围的 API 结果存储。现在读取页面，适用范围不同，长期保留前需要 Brave 的答复。

## 限制与错误

* 超过 600 字符或 75 词的查询在提交时返回 `422 VALIDATION_ERROR`。
* 上述列表之外的 `country`、未知的 `lang`、三个值之外的 `safesearch`、格式错误的 `freshness`、1 到 10 之外的 `page` 均为 `422 VALIDATION_ERROR`。
* Brave 限速时换地址重试后以 `BRAVE_HTTP_429` 作答。`BRAVE_UNEXPECTED_PAGE` 表示它返回了本引擎不读取的页面，`BRAVE_TIMEOUT` 表示没有及时作答。
* 其他请求错误见[错误](https://docs.querying.ai/zh/concepts/errors.md)。

## 相关

* Bing 结果页与其 AI 摘要见 [Bing 搜索](https://docs.querying.ai/zh/engines/bing-search.md)
* 读取一条结果的整页内容用[Scrape](https://docs.querying.ai/zh/engines/web-scrape.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.