创建 Google Autocomplete 任务

GET /v3/serp/google/autocomplete/task_post

本接口用于创建 Google Autocomplete 采集任务。Autocomplete 是搜索联想功能，用户在搜索框中时，系统会返回补建议。本接口可返回指定在特定语言、地区、客户端以及标位置下可见的联想建议数据。

接口地址：

POST https://api.seermartech.cn/v3/serp/google/autocomplete/task_post

计费说明

本接口按“创建任务”计费，不按结果获取重复扣费。

如参考单价为 USD 计费，则可按以下方式估算人民币价格：

参考价约 ¥0.0096 / 次

扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求说明

请求方法：POST
请求体格式：JSON 数组 [{ ... }]
编码：UTF-8
单次 POST 最多可提交 100 个任务
每分钟最多可发起 2000 次 API 调用
如果单次请求 100 个任务，出部分会返回错误 40006

任务创建后，你可以通过返回的唯一任务 ID 获取结果；也可以在创建任务时指定 postback_url 或 pingback_url，由本平台在任务完成后主动通知你的系统。

注意：
若你的回调服务器在 10 秒未响应，连接会因时中止；
该任务会被转移到 /v3/serp/google/autocomplete/tasks_ready/ 列表中，供后续轮询获取；
回调失败时的错误码和错误信息取决于你的服务器。

主参数

字段名	类型	说明
`keyword`	string	填。查询，最长 700 个字符。所有 `%##` 会被解码，字符 `+` 会被解码为空格。若本身需要 `%`，请写为 `%25`；若需要 `+`，请写为 `%2B`。
`location_code`	integer	搜索地区编码。若未传 `location_name`，则此字段为填。可通过 `/v3/serp/google/locations` 查询可用地区编码。示例：`2840`
`language_code`	string	搜索语言编码。若未传 `language_name`，则此字段为填。传该字段时，无需再传 `language_name`。可通过 `/v3/serp/google/languages` 查询可用语言编码。示例：`en`
`cursor_pointer`	integer	搜索框中的标水平位置，可选。修改该值时，同一个种子词可能返回不同的联想结果。最小值：`0`。默认值：`keyword` 最后一个字符之后的位置。示例：`which query are s` 中，`"cursor_pointer": 0` 表示 `
`priority`	integer	任务优级，可选。可选值：`1` = 普通优级（默认），`2` = 高优级。高优级任务会产生额外费用。扣费以响应头 `X-SeerMarTech-Charge-CNY` 为准。
`pingback_url`	string	任务完成通知地址，可选。任务完成后，本平台会向该地址发送 GET 请求。你可以在 URL 中使用 `$id` 作为任务 ID 变量，使用 `$tag` 作为 URL 编码后的标签变量。示例：`http://your-server.com/pingscript?id=$id`、`http://your-server.com/pingscript?id=$id&tag=$tag`。注意：`pingback_url` 中的特殊字符会被 URL 编码，例如 `#` 会被编码为 `%23`。
`postback_url`	string	结果推送地址，可选。任务完成后，本平台会将结果以 gzip 压缩的 POST 请求发送到该地址。可使用 `$id` 和 `$tag` 变量。示例：`http://your-server.com/postbackscript?id=$id`、`http://your-server.com/postbackscript?id=$id&tag=$tag`。注意：特殊字符会被 URL 编码。
`postback_data`	string	若指定了 `postback_url`，则此字段填。表示推送给你服务器的数据类型。当前可选值：`advanced`

附加参数

字段名	类型	说明
`client`	string	联想结果所基于的搜索客户端，可选。不同客户端下返回的联想建议可能不同。可选值：`chrome`、`chrome-omni`、`gws-wiz`、`gws-wiz-serp`、`safari`、`firefox`、`psy-ab`、`toolbar`、`youtube`、`gws-wiz-local`、`img`、`products-cc`
`location_name`	string	搜索地区完整名称。若未传 `location_code`，则此字段为填。传该字段时，无需再传 `location_code`。可通过 `/v3/serp/google/autocomplete/locations` 查询。示例：`London,England,United Kingdom`
`language_name`	string	搜索语言完整名称。若未传 `language_code`，则此字段为填。传该字段时，无需再传 `language_code`。可通过 `/v3/serp/google/languages` 查询。示例：`English`
`tag`	string	自定义任务标识，可选，最长 255 个字符。可用于在结果中你的业务 ID；该值会出现在响应的 `data` 对象中。

结果获取方式

创建任务成功后，接口返回任务数据，结果此时通常尚未生成，因此 result 字段一般为 null。

你可以通过以下方式获取最终结果：

使用返回的任务 id 获取结果；
在创建任务时 pingback_url，任务完成后接收通知；
在创建任务时 postback_url，任务完成后直接接收压缩结果。

响应字段说明

顶层响应字段

字段名	类型	说明
`version`	string	当前 API 版本
`status_code`	integer	通用状态码。完整错误码请参考 `/v3/appendix/errors`
`status_message`	string	通用状态信息
`time`	string	执行耗时，单位秒
`cost`	float	本次请求总费用，单位通常为平台 USD
`tasks_count`	integer	`tasks` 数组中的任务数量
`tasks_error`	integer	`tasks` 数组中执行报错的任务数量
`tasks`	array	任务数组

tasks[] 字段

字段名	类型	说明
`id`	string	任务唯一标识，UUID 格式
`status_code`	integer	任务状态码，范围通常为 `10000`–`60000`
`status_message`	string	任务状态信息
`time`	string	任务执行耗时，单位秒
`cost`	float	该任务费用，单位通常为平台 USD
`result_count`	integer	`result` 数组中的数量
`path`	array	接口路径
`data`	object	你在请求中提交的参数回显
`result`	array \| null	结果数组。创建任务时通常为 `null`

请求示例

cURL

bash

curl --location --request POST 'https://api.seermartech.cn/v3/serp/google/autocomplete/task_post' \
--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
 },
 {
 "language_name": "English",
 "location_name": "United States",
 "keyword": "albert einstein",
 "cursor_pointer": 6,
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 }
]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/serp/google/autocomplete/task_post"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

payload = [
 {
 # 示例 1：最简任务
 "language_code": "en",
 "location_code": 2840,
 "keyword": "albert einstein",
 "cursor_pointer": 6
 },
 {
 # 示例 2：附带自定义标签和回调地址
 "language_name": "English",
 "location_name": "United States",
 "keyword": "albert einstein",
 "cursor_pointer": 6,
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 }
]

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

TypeScript

typescript

import axios from "axios";

const payload = [
 {
 // 示例 1：最简任务
 language_code: "en",
 location_code: 2840,
 keyword: "albert einstein",
 cursor_pointer: 6
 },
 {
 // 示例 2：附带标签和回调地址
 language_name: "English",
 location_name: "United States",
 keyword: "albert einstein",
 cursor_pointer: 6,
 tag: "some_string_123",
 pingback_url: "https://your-server.com/pingscript?id=$id&tag=$tag"
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/serp/google/autocomplete/task_post",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 },
 data: payload
})
 .then((response) => {
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error.response?.data || error.message);
 });

请求体示例

json

[
 {
 "language_code": "en",
 "location_code": 2840,
 "keyword": "albert einstein",
 "cursor_pointer": 6
 }
]

响应示例

json

{
 "version": "0.1.20231117",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0639 sec.",
 "cost": 0.0006,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0210 sec.",
 "cost": 0.0006,
 "result_count": 0,
 "path": [
 "v3",
 "serp",
 "google",
 "autocomplete",
 "task_post"
 ],
 "data": {
 "api": "serp",
 "function": "task_post",
 "se": "google",
 "se_type": "autocomplete",
 "language_code": "en",
 "location_code": 2840,
 "keyword": "albert einstein",
 "cursor_pointer": 6,
 "device": "desktop",
 "os": "windows"
 },
 "result": null
 }
 ]
}

状态码与异常处理

20000：请求成功
20100：任务创建成功
40006：单次 POST 请求中的任务数出上限（ 100 个）

建议在接时对以下做好处理：

顶层请求成功但部分任务失败；
回调地址时或不可达；
任务创建成功但结果需异步轮询；
按 status_code 和 status_message 实现统一异常处理。

完整错误码可参考 /v3/appendix/errors。

使用建议

优使用 location_code + language_code，可减少名称匹歧义；
若要模拟不同阶段的联想建议，请重点使用 cursor_pointer；
若业务需要自动接收结果，建议 postback_url 并处理 gzip；
批量提交时，建议每次不 100 个任务。

实用场景

挖掘长尾词：基于核心种子词批量创建联想任务，获取用户真实路径，扩展选题和 SEO 词库。
比较不同位置的联想变化：调整 cursor_pointer，识别同一在不同阶段的补差异，用于优化标题结构和问题型布局。
分析地区化搜索意图：按不同 location_code 创建任务，观察各地区联想词差异，支持本地化 SEO 与区域市场策略。
监控品牌联想：针对品牌词、产品词持续创建任务，追踪自动补中的短语变化，品牌声量与舆观察。
验证不同搜索客户端的建议差异：使用 client 对比 Chrome、Safari、图片搜索、购物搜索等场景下的联想词，用于多流量布局。

创建 Google Autocomplete 任务 ​

计费说明 ​

请求说明 ​

主参数 ​

附加参数 ​

结果获取方式 ​

响应字段说明 ​

顶层响应字段 ​

tasks[] 字段 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

请求体示例 ​

响应示例 ​

状态码与异常处理 ​

使用建议 ​

实用场景 ​