SeerMarTech API 文档

主题

Google 自动补高级实时接口 ​

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

接口说明 ​

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

Google 自动补可根据用户当前，返回搜索框中的推荐词。本接口支持指定、标位置、搜索语言、地区和搜索客户端，并返回对应的自动补建议及信息。

所有 POST 数据使用 UTF-8 编码的 JSON 格式提交，请求体为 JSON 数组。每次 Live SERP 平台限流以认证说明中的 30/60/120 次/分钟规则为准。

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

请求参数 ​

###填及主要参数

参数类型说明
keywordstring填。 要查询的，最多 700 个字符。请求中的 %## 编码会被解码，字符 + 会被解码为空格。<br><br>如需在中使用 %，请编码为 %25；如需使用 +，请编码为 %2B。
location_codeinteger搜索引擎地区代码。如果未指定 location_name，则提供此参数。可通过 GET /v3/serp/google/locations 获取可用地区及代码。示例：2840。
language_codestring搜索引擎语言代码。如果未指定 language_name，则提供此参数。提供此参数后，无需再提供 language_name。可通过 GET /v3/serp/google/languages 获取可用语言及代码。示例：en。
cursor_pointerinteger搜索框中的标位置，可选。表示标在中的水平位置。修改标位置后，同一可能返回不同的自动补建议。最小值为 0，默认值为所提供的最后一个字符位置。

cursor_pointer 示例：

搜索框状态参数值
|which query are s0
which query is s|16
which que|ry is s9

参数 ​

参数类型说明
location_namestring搜索引擎地区的完整名称。如果未指定 location_code，则提供此参数。提供此参数后，无需再提供 location_code。可通过 GET /v3/serp/google/autocomplete/locations 获取可用地区名称。示例：London,England,United Kingdom。
language_namestring搜索引擎语言的完整名称。如果未指定 language_code，则提供此参数。提供此参数后，无需再提供 language_code。可通过 GET /v3/serp/google/languages 获取可用语言名称。示例：English。
clientstring自动补使用的搜索客户端。不同客户端可能返回不同的建议结果。
tagstring用户自定义任务标识，可选，最多 255 个字符。可用于识别任务并将请求与响应匹。提交的值会原样返回在响应任务的 data 对象中。

client 支持以下取值：

值说明
chrome在 Chrome 浏览器中打开 Google 搜索时使用
chrome-omni在 Chrome 地址栏中使用
gws-wiz在 Google 搜索首页使用
gws-wiz-serp在 Google 搜索结果页使用
safari在 Safari 浏览器中打开 Google 搜索时使用
firefox在 Firefox 浏览器中打开 Google 搜索时使用
psy-ab可用于在 Chrome 浏览器中打开 Google 搜索时的场景
toolbar返回 XML 格式结果
youtube返回 JSONP 格式结果
gws-wiz-local用于 Google 本地搜索
img用于 Google 图片搜索
products-cc用于 Google 购物搜索

请求示例 ​

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",
}

# 每次请求只能提交一个任务
payload = [
    {
        "language_code": "en",
        "location_code": 2840,
        "keyword": "albert einstein",
        "cursor_pointer": 6,
        "client": "gws-wiz-serp",
    }
]

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

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        "请求失败：代码=%s，消息=%s"
        % (result.get("status_code"), result.get("status_message"))
    )

TypeScript ​

typescript
import axios from "axios";

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);

响应结构 ​

接口返回 JSON 数据，主体 tasks 数组。

顶层字段 ​

字段类型说明
versionstring当前接口版本
status_codeinteger通用状态码。完整状态码列表请参考错误码文档。
status_messagestring通用提示信息
timestring请求执行耗时，单位为秒
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
tasks_countintegertasks 数组中的任务总数
tasks_errorintegertasks 数组中返回错误的任务数
tasksarray任务结果数组

任务字段 ​

字段类型说明
idstring任务唯一标识，UUID 格式
status_codeinteger任务状态码，取值范围为 10000 至 60000
status_messagestring任务状态说明
timestring任务执行耗时，单位为秒
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
result_countintegerresult 数组中的数量
patharray请求路径
dataobject请求中提交的参数
resultarray自动补结果数组

result 字段 ​

字段类型说明
keywordstring请求中提交的。返回时会解码 %## 编码，字符 + 会被解码为空格。
typestring请求中指定的搜索引擎类型
se_domainstring请求中指定的搜索引擎域名
location_codeinteger搜索地区代码
language_codestring搜索语言代码
check_urlstring搜索结果直接 URL，可用于核验返回结果的准确性
datetimestring获取结果的日期和时间，使用 UTC 格式：yyyy-mm-dd hh-mm-ss +00:00。示例：2019-11-15 12:57:46 +00:00
spellobject搜索引擎自动纠错信息。如果搜索引擎对进行了纠正，将返回纠正后的及纠错类型；未发生纠错时通常为 null。
refinement_chipsobject搜索细化选项
item_typesarray搜索结果类型列表。此接口通常 autocomplete。
se_results_countinteger搜索结果总数
items_countintegeritems 数组中返回的结果数量
itemsarray自动补建议结果数组

refinement_chips 字段 ​

字段类型说明
typestring素类型，固定为 refinement_chips
xpathstring素的 XPath
itemsarray搜索细化数组

refinement_chips.items 字段 ​

字段类型说明
typestring素类型，固定为 refinement_chips_element
titlestring素标题
urlstring含细化参数的搜索 URL
domainstring搜索结果中的域名
optionsarray进一步的搜索细化选项

refinement_chips.items.options 字段 ​

字段类型说明
typestring素类型，固定为 refinement_chips_option
titlestring选项标题
urlstring含细化参数的搜索 URL
domainstring搜索结果中的域名

items 字段 ​

字段类型说明
typestring素类型，固定为 autocomplete
rank_groupinteger组排名。表示相同 type素中的位置，不同类型之间不计该排名。
rank_absoluteinteger绝对排名，表示在搜索结果中的位置。
relevanceinteger推荐词与目标的性，取值范围为 500 至 2000。数值越高，性越强。在 client 为 chrome 或 chrome-omni 时提供。
suggestionstringGoogle 自动补推荐词
suggestion_typestringGoogle 自动补推荐词类型。在 client 为 chrome 或 chrome-omni 时提供。
search_query_urlstring与自动补推荐词对应的搜索结果 URL
thumbnail_urlstring推荐词缩略图 URL。在 client 为 gws-wiz 或 gws-wiz-serp 时提供。
highlightedarray搜索框中高亮显示的自动补列表。在 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": [
    {
      "id": "07081531-2806-0217-0000-9d8c7f6a5b4e",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "1.8423 sec.",
      "cost": 0.002,
      "result_count": 1,
      "path": [
        "v3",
        "serp",
        "google",
        "autocomplete",
        "live",
        "advanced"
      ],
      "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": [
        {
          "keyword": "albert einstein",
          "type": "autocomplete",
          "se_domain": "google.com",
          "location_code": 2840,
          "language_code": "en",
          "check_url": "https://www.google.com/search?q=albert+einstein",
          "datetime": "2024-05-14 12:57:46 +00:00",
          "spell": null,
          "refinement_chips": null,
          "item_types": [
            "autocomplete"
          ],
          "se_results_count": 0,
          "items_count": 3,
          "items": [
            {
              "type": "autocomplete",
              "rank_group": 1,
              "rank_absolute": 1,
              "relevance": null,
              "suggestion": "albert einstein biography",
              "suggestion_type": null,
              "search_query_url": "https://www.google.com/search?q=albert+einstein+biography",
              "thumbnail_url": null,
              "highlighted": null
            },
            {
              "type": "autocomplete",
              "rank_group": 2,
              "rank_absolute": 2,
              "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": 3,
              "rank_absolute": 3,
              "relevance": null,
              "suggestion": "albert einstein quotes",
              "suggestion_type": null,
              "search_query_url": "https://www.google.com/search?q=albert+einstein+quotes",
              "thumbnail_url": null,
              "highlighted": null
            }
          ]
        }
      ]
    }
  ]
}

状态码与异常处理 ​

请根据顶层 status_code 和任务级 status_code 判断请求是否成功。通常 20000 表示请求成功，状态码表示参数错误、任务执行异常或服务异常。

建议客户端同时处理以下：

  • 顶层请求成功，但 tasks_error 大于 0；
  • 单个任务的 status_code 非 20000；
  • result 为空或 result_count 为 0；
  • 请求时、网络连接失败或返回不是合法 JSON；
  • 自动补结果因搜索客户端、地区、语言或标位置不同而发生变化。

实用场景 ​

  • 挖掘搜索联想词：批量获取目标的自动补建议，扩展 SEO选题和长尾库。
  • 比较标位置差异：在同一的不同字符位置请求建议，识别用户过程中的多阶段搜索意图。
  • 分析地区与语言偏好：按国家、城市和语言对比自动补结果，为本地 SEO 和化规划提供依据。
  • 评估搜索客户端差异：比较 Chrome、Safari、搜索结果页等客户端返回的建议，优化不同下的覆盖。
  • 发现主题：提取自动补中的人物、产品、问题和场景词，搭建集群与链接结构。

统一入口：官网 · LLM API · 控制台

© 2026 SeerMarTech · GEO · SEO 营销数据 API