Google 搜索建议 API
获取实时搜索建议与输入框自动补全词,支持多轮 SEO 关键词挖掘。
这是什么 API?
Serqo 的 Google 搜索建议 API(亦称 Google Autocomplete 自动补全接口)能够以编程方式获取 Google 实时搜索建议与下拉联想词。除基础的单次查询自动补全外,还支持多轮扩展策略——包括 A-Z 字母表拼缀、疑问词、介词、商业意图词以及递归树状挖掘,专为关键词发现与 SEO 深度研究而设计。
常见使用场景
- 驱动实时搜索框下拉建议、联想词与即时查询词自动补全。
- 利用 26 个字母(A-Z)挖掘深度长尾关键词,用于内容规划与 SEO。
- 提取常见用户疑问词(
how、why、what),用于 FAQ 与博客选题大纲。 - 分析商业意图与对比搜索模式(
vs、best、review)。 - 构建关键词树状主题聚类与搜索意图层级。
请求示例
POST https://api.serqo.io/v1/autocomplete
/v1/autocomplete 和 /v1/suggest 均同时支持 POST(JSON 请求体)与 GET(URL 查询参数)。
请求头
创建 API Key 并保存在服务端,通过 x-api-key 请求头传入。
| 请求头 | 取值 | 说明 |
|---|---|---|
| Content-Type | application/json | 请求正文为 JSON。 |
| x-api-key | YOUR_API_KEY | 用于验证请求的 API Key。 |
export SERP_API_KEY='YOUR_API_KEY'
curl https://api.serqo.io/v1/autocomplete \
-H "x-api-key: $SERP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"q": "nextjs",
"strategy": "alphabet",
"gl": "us",
"hl": "en"
}' 代码示例
可使用标准 HTTP 客户端调用,无需安装 SDK。以下示例分别使用 Node.js 22 及以上版本和 Python 3。
const response = await fetch('https://api.serqo.io/v1/autocomplete', {
method: 'POST',
headers: {
'x-api-key': process.env.SERP_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
q: 'nextjs',
strategy: 'alphabet',
gl: 'us',
hl: 'en',
}),
});
const result = await response.json();
if (!response.ok) {
console.error(response.status, result.requestId, result.error);
} else {
console.log(`Discovered ${result.meta.totalKeywords} keywords in ${result.meta.durationMs}ms`);
console.log(result.data.suggestions.slice(0, 10));
} import json
import os
from urllib.error import HTTPError
from urllib.request import Request, urlopen
payload = {
'q': 'nextjs',
'strategy': 'questions',
'gl': 'us',
'hl': 'en',
}
req = Request(
'https://api.serqo.io/v1/autocomplete',
data=json.dumps(payload).encode('utf-8'),
headers={
'x-api-key': os.environ['SERP_API_KEY'],
'Content-Type': 'application/json',
},
)
try:
with urlopen(req) as resp:
data = json.load(resp)
print(f"Total suggestions: {data['meta']['totalKeywords']}")
for item in data['data']['suggestions'][:5]:
print(f"- {item['keyword']} (relevance: {item['relevance']})")
except HTTPError as err:
print(err.code, json.load(err)) 参数
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| q | string | 是 | — | 种子关键词。最大长度 300 字符。支持别名 query。 |
| strategy | string | 否 | normal | 扩展策略:normal、alphabet、questions、prepositions、intent、seo_matrix、deep。 |
| gl | string | 否 | us | 两位 ISO 国家代码。支持别名 country。 |
| hl | string | 否 | en | 界面语言代码。支持别名 lang。 |
| depth | integer | 否 | 1 | 递归深度(1 到 3)。当策略为 deep 时生效。 |
| limit | integer | 否 | — | 最多返回的建议词数量(1 到 1000)。 |
| timeout | integer | 否 | 25000 | 全局执行超时毫秒数(100 到 30000)。 |
| includeGroups | boolean | 否 | true | 为 true 时,在 data.groups 中返回分类关键词。 |
| noCache | boolean | 否 | false | 为 true 时,跳过服务端查询缓存。 |
扩展策略说明
normal:种子词的直接自动补全。约 200ms 内返回 8 至 15 个即时建议词。alphabet:并发发起 26 组字母后缀请求(q a至q z)。产出 150 至 220 个去重后的长尾关键词。questions:追加疑问前缀词(how to、why does、what is)。特别适合制作 FAQ 常见问答。prepositions:追加对比与语境连接词(vs、for、with)。intent:测试高商业价值的交易与意图词(best、buy、price、review)。seo_matrix:综合矩阵策略,涵盖字母表、疑问词和商业修饰词,最多并发执行 40 轮。deep:多层树状深度探索,最多下钻 3 层。在data.tree中返回层级分明的父子聚类。
响应
HTTP 200。标准统一的 JSON 响应信封结构:
{
"success": true,
"requestId": "ac_01jm9x48...",
"data": {
"seedQuery": "nextjs",
"suggestions": [
{
"keyword": "nextjs api routes",
"relevance": 1250,
"type": "QUERY",
"sourceType": "alphabet",
"group": "a",
"round": 1
},
{
"keyword": "nextjs authentication",
"relevance": 1200,
"type": "QUERY",
"sourceType": "alphabet",
"group": "a",
"round": 1
}
],
"groups": {
"a": [
{
"keyword": "nextjs api routes",
"relevance": 1250,
"type": "QUERY"
}
]
}
},
"meta": {
"strategy": "alphabet",
"country": "us",
"lang": "en",
"durationMs": 1824,
"totalKeywords": 178,
"rounds": 27,
"credits": 5,
"cache": "miss",
"partial": false
}
} 定价与额度消耗
根据所选扩展策略的复杂度和实际分发轮数扣除对应额度:
| 策略 | 分发子请求数 | 消耗积分 | 典型场景 |
|---|---|---|---|
| normal / direct | 1 round | 1 credit | 实时搜索框下拉补全 |
| questions | 10 to 15 rounds | 3 credits | FAQ 与博客内容选题 |
| prepositions | 10 to 15 rounds | 3 credits | 对比类(vs, with)搜索词 |
| intent | 10 to 15 rounds | 3 credits | 高转化商业意图词(best, buy) |
| alphabet | 27 rounds (A-Z) | 5 credits | 完整的 26 字母长尾词挖掘 |
| seo_matrix | Up to 40 rounds | 8 credits | 全套综合 SEO 矩阵扩展 |
| deep | Hierarchical | depth=1: 1 creditdepth=2: 4 creditsdepth=3: 8 credits | 多层级主题树探索 |
- 缓存命中免费:从查询缓存命中的相同请求消耗 0 积分。
- 失败不计费:因上游超时或不可用失败的请求绝不扣费,预留额度自动释放。
- 批量分发优惠:像
alphabet(5 积分)这样包含多轮查询的策略,相比发起 26 次独立搜索节省高达 80% 额度。 - 安全限额:具备 25 秒超时熔断、40 轮上限控制与客户端断开自动中止机制。
错误代码与状态
{
"success": false,
"requestId": "ac_01jm9x48...",
"error": {
"code": "INSUFFICIENT_CREDITS",
"message": "Insufficient credits for this request",
"retryable": false
}
} | HTTP 状态 | 错误代码 | 含义与处理建议 |
|---|---|---|
| 401 | UNAUTHORIZED | 缺少、无效或已注销的 API 密钥。请在 x-api-key 中传入有效密钥。 |
| 402 | INSUFFICIENT_CREDITS | 账户余额不足以支付当前请求策略所需的积分。请在控制台充值。 |
| 422 | INVALID_PARAM | 参数缺失或超出合法范围(如未知策略、depth > 3 等)。 |
| 429 | QUOTA_EXCEEDED | 超出速率限制。请根据 retryAfterMs 稍后重试。 |
| 500 | INTERNAL_ERROR | 服务器内部错误。已预留的额度将自动全额退还,不扣费。 |
常见问题
类似 alphabet 这样的多轮扩展策略如何扣除额度?
多轮扩展策略(如 alphabet 字母表拼缀)会在单次 API 调用中并发分发多组子请求,并享受打包优惠费率(如 26 个字母仅扣除 5 积分,而非 26 次独立搜索)。上游超时或不可用时会自动释放预留额度,不扣除积分。
可以将此接口直接用于前端搜索框的实时下拉联想吗?
可以。推荐使用 normal 策略进行即时自动补全(响应延迟约 200ms)。/v1/autocomplete 与 /v1/suggest 均同时支持 POST(JSON 请求体)与 GET(URL 查询参数)。