Back to Details

suggest

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Suggest / Autocomplete

建议/自动补全

Requires API Key: Get one at https://api.search.brave.com
Plan: Included in the Suggest plan. See https://api-dashboard.search.brave.com/app/subscriptions/subscribe
需要API Key: 前往https://api.search.brave.com获取
套餐: 包含在Suggest套餐中。查看https://api-dashboard.search.brave.com/app/subscriptions/subscribe

Quick Start (cURL)

快速开始（cURL）

Basic Suggestions

基础建议

bash
curl -s "https://api.search.brave.com/res/v1/suggest/search?q=how+to+" \
  -H "Accept: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}"
bash
curl -s "https://api.search.brave.com/res/v1/suggest/search?q=how+to+" \
  -H "Accept: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}"

With All Parameters

包含所有参数

bash
curl -s "https://api.search.brave.com/res/v1/suggest/search" \
  -H "Accept: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
  -G \
  --data-urlencode "q=albert" \
  --data-urlencode "country=US" \
  --data-urlencode "lang=en" \
  --data-urlencode "count=10" \
  --data-urlencode "rich=true"
bash
curl -s "https://api.search.brave.com/res/v1/suggest/search" \
  -H "Accept: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
  -G \
  --data-urlencode "q=albert" \
  --data-urlencode "country=US" \
  --data-urlencode "lang=en" \
  --data-urlencode "count=10" \
  --data-urlencode "rich=true"

Endpoint

接口地址

http
GET https://api.search.brave.com/res/v1/suggest/search
Authentication: 
X-Subscription-Token: <API_KEY>
header
Optional Headers:
  • Accept-Encoding: gzip
    — Enable response compression
http
GET https://api.search.brave.com/res/v1/suggest/search
身份验证: 
X-Subscription-Token: <API_KEY>
请求头
可选请求头:
  • Accept-Encoding: gzip
    — 启用响应压缩

Parameters

参数

ParameterTypeRequiredDefaultDescription
q
stringYes—Suggest search query (1-400 chars, max 50 words)
lang
stringNo
en
Language preference (2+ char language code, e.g. 
fr
, 
de
, 
zh-hans
)
country
stringNo
US
Search country (2-letter country code or 
ALL
)
count
intNo
5
Number of suggestions (1-20). Actual results may be fewer
rich
boolNo
false
Enhance with entity info (title, description, image). Paid Search plan required
参数类型是否必填默认值描述
q
字符串是—建议搜索查询词（1-400字符，最多50个单词）
lang
字符串否
en
语言偏好（2个及以上字符的语言代码，例如 
fr
、
de
、
zh-hans
）
country
字符串否
US
搜索国家（2字母国家代码或 
ALL
）
count
整数否
5
建议结果数量（1-20）。实际返回结果可能更少
rich
布尔值否
false
附带实体信息（标题、描述、图片）。需要付费Search套餐

Response Fields

响应字段

FieldTypeDescription
type
stringAlways 
"suggest"
query.original
stringThe original suggest search query
results
arrayList of suggestions (may be empty)
results[].query
stringSuggested query completion
results[].is_entity
bool?Whether the suggested enriched query is an entity (rich only)
results[].title
string?The suggested query enriched title (rich only)
results[].description
string?The suggested query enriched description (rich only)
results[].img
string?The suggested query enriched image URL (rich only)
Fields with 
null
values are excluded from the response. Non-rich results contain only the 
query
field.
字段类型描述
type
字符串固定为
"suggest"
query.original
字符串原始的建议搜索查询词
results
数组建议结果列表（可能为空）
results[].query
字符串建议的查询词补全结果
results[].is_entity
布尔值（可选）该增强建议查询词是否为实体（仅rich模式下返回）
results[].title
字符串（可选）增强建议查询词的标题（仅rich模式下返回）
results[].description
字符串（可选）增强建议查询词的描述（仅rich模式下返回）
results[].img
字符串（可选）增强建议查询词的图片URL（仅rich模式下返回）
值为
null
的字段不会包含在响应中。非rich模式的结果仅包含
query
字段。

Rich Response Example (
rich=true
)

Rich模式响应示例（
rich=true
）

json
{
  "type": "suggest",
  "query": { "original": "albert" },
  "results": [
    {
      "query": "albert einstein",
      "is_entity": true,
      "title": "Albert Einstein",
      "description": "German-born theoretical physicist",
      "img": "https://imgs.search.brave.com/..."
    },
    { "query": "albert einstein quotes", "is_entity": false }
  ]
}
json
{
  "type": "suggest",
  "query": { "original": "albert" },
  "results": [
    {
      "query": "albert einstein",
      "is_entity": true,
      "title": "Albert Einstein",
      "description": "German-born theoretical physicist",
      "img": "https://imgs.search.brave.com/..."
    },
    { "query": "albert einstein quotes", "is_entity": false }
  ]
}

Use Cases

使用场景

  • Search-as-you-type UI: Real-time autocomplete dropdown. Debounce 150-300ms.
  • Query refinement for RAG: Expand partial/ambiguous queries before calling 
    web-search
    or 
    llm-context
    .
  • Entity detection: Use 
    rich=true
    to detect entities with title, description, and image for preview cards.
  • Typo-tolerant input: Get clean suggestions from misspelled input without separate spellcheck.
  • 随输随搜UI: 实时自动补全下拉框。设置150-300毫秒的防抖。
  • RAG的查询优化: 在调用
    web-search
    或
    llm-context
    之前，扩展部分/模糊查询词。
  • 实体检测: 使用
    rich=true
    检测实体并获取标题、描述和图片，用于预览卡片。
  • 拼写容错输入: 从拼写错误的输入中获取清晰的建议，无需单独的拼写检查。

Notes

注意事项

  • Latency: Designed for <100ms response times
  • Country/lang: Hints for suggestion relevance, not strict filters
  • Typo handling: Suggestions handle common typos without separate spellcheck
  • 延迟: 设计目标为响应时间<100毫秒
  • 国家/语言: 用于提示建议相关性，而非严格过滤
  • 拼写处理: 建议功能可处理常见拼写错误，无需单独的拼写检查