Google 自动补实时查询（高级版）

接口说明

该接口用于实时获取 Google 搜索自动补建议。你可以基于一个种子，获取：

Google 返回的自动补建议列表 -标在搜索框中的位置对建议结果的影响
不同搜索客户端下的补结果差异

接口路径：

POST /v3/serp/google/autocomplete/live/advanced

请求地址：

https://api.seermartech.cn/v3/serp/google/autocomplete/live/advanced

计费说明

该接口按请求计费，每次请求都会扣费。

参考价约 ¥0.0320 / 次 扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

使用限制

所有 POST 数据使用 JSON（UTF-8 编码）
请求体为 JSON 数组格式：[{ ... }]
实时 SERP 接口单次请求支持 1 个任务
最高支持 2000 次 API 调用/分钟

请求参数

主要参数

字段名	类型	填	说明
`keyword`	string	是	目标，最长 700 个字符。字段中的 `%##` 会被解码，字符 `+` 会被解码为空格。如果本身需要 `%`，请写为 `%25`；如果需要 `+`，请写为 `%2B`。
`location_code`	integer	否*	搜索地域代码。当未传 `location_name` 时填。例如：`2840`。可通过 `/v3/serp/google/locations` 查询可用地域。
`language_code`	string	否*	搜索语言代码。当未传 `language_name` 时填。例如：`en`。可通过 `/v3/serp/google/languages` 查询可用语言。
`cursor_pointer`	integer	否	搜索框标的水平位置。调整标位置后，同一个可能返回不同的自动补建议。最小值为 `0`。默认值为最后一个字符的位置。

location_code 与 location_name 二选一；language_code 与 language_name 二选一。

`cursor_pointer` 示例

搜索框	`cursor_pointer`
`\|which query are s`	`0`
`which query is s\|`	`16`
`which que\|ry is s`	`9`

附加参数

字段名	类型	填	说明
`location_name`	string	否*	搜索地域完整名称。当未传 `location_code` 时填。例如：`London,England,United Kingdom`。可通过 `/v3/serp/google/autocomplete/locations` 查询。
`language_name`	string	否*	搜索语言完整名称。当未传 `language_code` 时填。例如：`English`。可通过 `/v3/serp/google/languages` 查询。
`client`	string	否	自动补所属的搜索客户端。不同客户端返回的建议可能不同。
`tag`	string	否	自定义任务标识，最长 `255` 字符。可用于结果回传时进行任务匹，响应中的 `data` 对象会原样返回该值。

`client` 可选值

值	说明
`chrome`	Google Chrome 中的搜索
`chrome-omni`	Chrome 地址栏中的搜索建议
`gws-wiz`	Google 首页搜索框
`gws-wiz-serp`	Google 搜索结果页中的搜索框
`safari`	Safari 浏览器中的搜索
`firefox`	Firefox 浏览器中的搜索
`psy-ab`	某些 Chrome 场景下使用
`toolbar`	返回 XML
`youtube`	返回 JSONP
`gws-wiz-local`	Google 本地搜索
`img`	Google 图片搜索
`products-cc`	Google Shopping 搜索

请求示例

cURL

bash

curl --location --request POST "https://api.seermartech.cn/v3/serp/google/autocomplete/live/advanced" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "language_code": "en",
 "location_code": 2840,
 "keyword": "albert einstein",
 "cursor_pointer": 6,
 "client": "gws-wiz-serp"
 }
]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/serp/google/autocomplete/live/advanced"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
data = [
 {
 "language_code": "en",
 "location_code": 2840,
 "keyword": "albert einstein",
 "cursor_pointer": 6,
 "client": "gws-wiz-serp"
 }
]

response = requests.post(url, json=data, headers=headers)
print(response.json)

TypeScript

typescript

import axios from "axios";

async function main {
 const response = await axios.post(
 "https://api.seermartech.cn/v3/serp/google/autocomplete/live/advanced",
 [
 {
 language_code: "en",
 location_code: 2840,
 keyword: "albert einstein",
 cursor_pointer: 6,
 client: "gws-wiz-serp"
 }
 ],
 {
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 }
 }
 );

 console.log(response.data);
}

main.catch(console.error);

响应结构

接口返回 JSON 数据，顶层 tasks 数组。

顶层字段

字段名	类型	说明
`version`	string	当前 API 版本
`status_code`	integer	通用状态码
`status_message`	string	通用状态信息
`time`	string	执行耗时，单位秒
`cost`	float	总任务成本，单位 USD
`tasks_count`	integer	`tasks` 数组中的任务数量
`tasks_error`	integer	返回错误的任务数量
`tasks`	array	任务结果数组

完整错误码和状态说明请参考 /v3/appendix/errors。建议在接时做好异常状态处理。

`tasks[]` 字段

字段名	类型	说明
`id`	string	任务唯一标识，UUID 格式
`status_code`	integer	任务状态码，范围通常为 `10000–60000`
`status_message`	string	任务状态信息
`time`	string	任务执行耗时
`cost`	float	该任务成本，单位 USD
`result_count`	integer	`result` 数组数量
`path`	array	URL 路径
`data`	object	请求中提交的参数，会在此回传
`result`	array	结果数组

`result[]` 字段

字段名	类型	说明
`keyword`	string	请求中的，返回时 `%##` 会被解码，`+` 会被解码为空格
`type`	string	搜索引擎类型
`se_domain`	string	搜索引擎域名
`location_code`	integer	请求中的地域代码
`language_code`	string	请求中的语言代码
`check_url`	string	可直接打开验证结果的搜索 URL
`datetime`	string	结果抓取时间，UTC 格式：`yyyy-mm-dd hh-mm-ss +00:00`
`spell`	object	搜索引擎自动纠错信息；若无纠错则可能为 `null`
`refinement_chips`	object	搜索细化建议
`item_types`	array	结果中的类型
`se_results_count`	integer	SERP 结果总数
`items_count`	integer	`items` 数组中的结果数量
`items`	array	自动补建议明细

`refinement_chips` 结构

字段名	类型	说明
`type`	string	固定为 `refinement_chips`
`xpath`	string	素的 XPath
`items`	array	细化项列表

`refinement_chips.items[]`

字段名	类型	说明
`type`	string	固定为 `refinement_chips_element`
`title`	string	细化项标题
`url`	string	带细化参数的搜索 URL
`domain`	string	SERP 中显示的域名
`options`	array	进一步细化选项

`refinement_chips.items[].options[]`

字段名	类型	说明
`type`	string	固定为 `refinement_chips_option`
`title`	string	选项标题
`url`	string	带细化参数的搜索 URL
`domain`	string	SERP 中显示的域名

`items[]` 字段说明

item_types 目前可能：

autocomplete

自动补结果对象

字段名	类型	说明
`type`	string	固定为 `autocomplete`
`rank_group`	integer	同类型的分组排名
`rank_absolute`	integer	所有 SERP素中的绝对排名
`relevance`	integer	建议词与目标的性，范围 `500–2000`，值越高性越强。在 `client=chrome` 或 `chrome-omni` 时可用。
`suggestion`	string	自动补建议词
`suggestion_type`	string	建议词类型。在 `client=chrome` 或 `chrome-omni` 时可用。
`search_query_url`	string	对应建议词的搜索结果地址
`thumbnail_url`	string	建议词缩略图地址。在 `client=gws-wiz` 或 `gws-wiz-serp` 时可用。
`highlighted`	array	搜索框中被高亮的片段。在 `client=gws-wiz`、`psy-ab`、`gws-wiz-local` 时可用。

响应示例

json

{
 "version": "0.1.20240514",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "2.0961 sec.",
 "cost": 0.002,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "serp",
 "function": "live",
 "se": "google",
 "se_type": "autocomplete",
 "language_code": "en",
 "location_code": 2840,
 "keyword": "albert einstein",
 "client": "gws-wiz-serp",
 "device": "desktop",
 "os": "windows"
 },
 "result": [
 {
 "se_results_count": 0,
 "items_count": 10,
 "items": [
 {
 "type": "autocomplete",
 "rank_group": 4,
 "rank_absolute": 4,
 "relevance": null,
 "suggestion": "albert einstein death",
 "suggestion_type": null,
 "search_query_url": "https://www.google.com/search?q=albert+einstein+death",
 "thumbnail_url": null,
 "highlighted": null
 },
 {
 "type": "autocomplete",
 "rank_group": 5,
 "rank_absolute": 5,
 "relevance": null,
 "suggestion": "albert einstein quotes",
 "suggestion_type": null,
 "search_query_url": "https://www.google.com/search?q=albert+einstein+quotes",
 "thumbnail_url": "http://t0.gstatic.com/images?q=tbn:ANd9GcRnmMaYbKfIi4s248o1yaRqUZUCsaoJxjiS4BA_s2d8h-WKhBkVbPU98CW-Xw&s=10",
 "highlighted": null
 },
 {
 "type": "autocomplete",
 "rank_group": 6,
 "rank_absolute": 6,
 "relevance": null,
 "suggestion": "albert einstein news",
 "suggestion_type": null,
 "search_query_url": "https://www.google.com/search?q=albert+einstein+news",
 "thumbnail_url": null,
 "highlighted": null
 },
 {
 "type": "autocomplete",
 "rank_group": 7,
 "rank_absolute": 7,
 "relevance": null,
 "suggestion": "albert einstein wife",
 "suggestion_type": null,
 "search_query_url": "https://www.google.com/search?q=albert+einstein+wife",
 "thumbnail_url": null,
 "highlighted": null
 },
 {
 "type": "autocomplete",
 "rank_group": 8,
 "rank_absolute": 8,
 "relevance": null,
 "suggestion": "albert einstein brain",
 "suggestion_type": null,
 "search_query_url": "https://www.google.com/search?q=albert+einstein+brain",
 "thumbnail_url": null,
 "highlighted": null
 },
 {
 "type": "autocomplete",
 "rank_group": 9,
 "rank_absolute": 9,
 "relevance": null,
 "suggestion": "albert einstein inventions",
 "suggestion_type": null,
 "search_query_url": "https://www.google.com/search?q=albert+einstein+inventions",
 "thumbnail_url": null,
 "highlighted": null
 },
 {
 "type": "autocomplete",
 "rank_group": 10,
 "rank_absolute": 10,
 "relevance": null,
 "suggestion": "albert einstein hospital",
 "suggestion_type": null,
 "search_query_url": "https://www.google.com/search?q=albert+einstein+hospital",
 "thumbnail_url": null,
 "highlighted": null
 }
 ]
 }
 ]
 }
 ]
}

状态码与错误处理

顶层 status_code 表示整个请求的执行状态
tasks[].status_code 表示任务状态
建议同时检查：
顶层 status_code == 20000
tasks_error == 0
每个任务的 status_code 是否成功
详细错误码请参考 /v3/appendix/errors

实用场景

挖掘长尾：基于核心词批量获取自动补建议，快速扩展选题和 SEO 词库。
比较不同搜索场景的补差异：切换 client 参数，分析首页、结果页、地址栏等场景下的用户搜索意图差异。
研究过程中的意图变化：通过调整 cursor_pointer，观察用户在不同位置可能触发的补建议，用于优化联想词策略。
监控品牌与人物搜索联想：抓取品牌词、人名词的自动补结果，识别舆风险、热点话题和高频词。
生成结构与 FAQ 主题：将自动补建议转化为文章标题、问答页和专题页规划，提高自然搜索覆盖率。

Google 自动补实时查询（高级版） ​

接口说明 ​

计费说明 ​

使用限制 ​

请求参数 ​

主要参数 ​

cursor_pointer 示例 ​

附加参数 ​

client 可选值 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应结构 ​

顶层字段 ​

tasks[] 字段 ​

result[] 字段 ​

refinement_chips 结构 ​

refinement_chips.items[] ​

refinement_chips.items[].options[] ​

items[] 字段说明 ​

自动补结果对象 ​

响应示例 ​

状态码与错误处理 ​

实用场景 ​