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-Typeapplication/json请求正文为 JSON。
x-api-keyYOUR_API_KEY用于验证请求的 API Key。
bash
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。

JavaScript (Node.js)
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));
}
Python 3
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))

参数

字段类型必填默认值说明
qstring是—种子关键词。最大长度 300 字符。支持别名 query。
strategystring否normal扩展策略:normal、alphabet、questions、prepositions、intent、seo_matrix、deep。
glstring否us两位 ISO 国家代码。支持别名 country。
hlstring否en界面语言代码。支持别名 lang。
depthinteger否1递归深度(1 到 3)。当策略为 deep 时生效。
limitinteger否—最多返回的建议词数量(1 到 1000)。
timeoutinteger否25000全局执行超时毫秒数(100 到 30000)。
includeGroupsboolean否true为 true 时,在 data.groups 中返回分类关键词。
noCacheboolean否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 响应信封结构:

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 / direct1 round1 credit实时搜索框下拉补全
questions10 to 15 rounds3 creditsFAQ 与博客内容选题
prepositions10 to 15 rounds3 credits对比类(vs, with)搜索词
intent10 to 15 rounds3 credits高转化商业意图词(best, buy)
alphabet27 rounds (A-Z)5 credits完整的 26 字母长尾词挖掘
seo_matrixUp to 40 rounds8 credits全套综合 SEO 矩阵扩展
deepHierarchicaldepth=1: 1 credit
depth=2: 4 credits
depth=3: 8 credits
多层级主题树探索
  • 缓存命中免费:从查询缓存命中的相同请求消耗 0 积分。
  • 失败不计费:因上游超时或不可用失败的请求绝不扣费,预留额度自动释放。
  • 批量分发优惠:像 alphabet(5 积分)这样包含多轮查询的策略,相比发起 26 次独立搜索节省高达 80% 额度。
  • 安全限额:具备 25 秒超时熔断、40 轮上限控制与客户端断开自动中止机制。

错误代码与状态

JSON
{
  "success": false,
  "requestId": "ac_01jm9x48...",
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Insufficient credits for this request",
    "retryable": false
  }
}
HTTP 状态错误代码含义与处理建议
401UNAUTHORIZED缺少、无效或已注销的 API 密钥。请在 x-api-key 中传入有效密钥。
402INSUFFICIENT_CREDITS账户余额不足以支付当前请求策略所需的积分。请在控制台充值。
422INVALID_PARAM参数缺失或超出合法范围(如未知策略、depth > 3 等)。
429QUOTA_EXCEEDED超出速率限制。请根据 retryAfterMs 稍后重试。
500INTERNAL_ERROR服务器内部错误。已预留的额度将自动全额退还,不扣费。

常见问题

类似 alphabet 这样的多轮扩展策略如何扣除额度?

多轮扩展策略(如 alphabet 字母表拼缀)会在单次 API 调用中并发分发多组子请求,并享受打包优惠费率(如 26 个字母仅扣除 5 积分,而非 26 次独立搜索)。上游超时或不可用时会自动释放预留额度,不扣除积分。

可以将此接口直接用于前端搜索框的实时下拉联想吗?

可以。推荐使用 normal 策略进行即时自动补全(响应延迟约 200ms)。/v1/autocomplete 与 /v1/suggest 均同时支持 POST(JSON 请求体)与 GET(URL 查询参数)。