Google 本地实时 SERP HTML

GET /v3/appendix/errors

本接口通过 POST /v3/serp/wp/v2/live/html 获取指定、搜索位置、语言和设备条件下的实时搜索结果原始 HTML 页面。该接口为容路径；每次请求支持提交 1 个任务。

text

POST https://api.seermartech.cn/v3/serp/wp/v2/live/html

请求体使用 UTF-8 编码的 JSON 数组格式。平台限流以认证说明中的 30/60/120 次/分钟规则为准。

计费说明

每次请求都会计费。depth过 10 或设置较高的 max_crawl_pages 时，如抓取到更多搜索结果页，可能产生额外费用。

启用 load_async_ai_overview: true 时，参考价约 ¥0.0140 / 次；若结果中不存在异步 AI 概览，或返回的 asynchronous_ai_overview 为 false，该附加费用将退回账户余额。

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

请求参数

参数	类型	填	说明
`url`	string	否	搜索查询的完整直达 URL。平台会自动解析的查询条件。该方式处理复杂，且在 URL 中准确指定语言和位置，通常建议优使用 `keyword`、位置和语言参数。示例：`https://www.google.co.uk/search?q=%20rank%20tracker%20api&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS`。
`keyword`	string	是	搜索，最长 700 个字符。请求中的 `%##` 会被解码，`+` 会被解析为空格。如需要字面量 `%`，请使用 `%25`；需要字面量 `+`，请使用 `%2B`。若 `allinanchor:`、`allintext:`、`allintitle:`、`allinurl:`、`define:`、`filetype:`、`id:`、`inanchor:`、`info:`、`intext:`、`intitle:`、`inurl:`、`link:`、`related:`、`site:` 等搜索运算符，任务费用将按 5 倍计算。 `cache:` 的查询不受支持，将返回参数校验错误。
`location_name`	string	条件填	搜索位置称。当未提供 `location_code` 或 `location_coordinate` 时填。使用该字段时无需同时传另外两种位置参数。可通过 `GET /v3/serp/wp/locations` 获取可用位置列表。示例：`London,England,United Kingdom`。
`location_code`	integer	条件填	搜索位置编码。当未提供 `location_name` 或 `location_coordinate` 时填。使用该字段时无需同时传另外两种位置参数。可通过 `GET /v3/serp/wp/locations` 获取位置编码。示例：`2840`。
`location_coordinate`	string	条件填	GPS 坐标。当未提供 `location_name` 或 `location_code` 时填。格式为 `latitude,longitude,radius`。纬度与经度最多保留 7 位小数；`radius` 取值范围为 199.9 至 199999，单位为毫米。示例：`53.476225,-2.243572,200`。
`language_name`	string	条件填	搜索语言称。当未提供 `language_code` 时填。使用后无需传 `language_code`。可通过 `GET /v3/serp/wp/languages` 获取语言列表。示例：`English`。
`language_code`	string	条件填	搜索语言代码。当未提供 `language_name` 时填。使用后无需传 `language_name`。可通过 `GET /v3/serp/wp/languages` 获取语言代码。示例：`en`。
`device`	string	否	设备类型：`desktop` 或 `mobile`。默认值：`desktop`。
`os`	string	否	设备操作系统。当 `device` 为 `desktop` 时，可选 `windows`、`macos`，默认 `windows`；当 `device` 为 `mobile` 时，可选 `android`、`ios`，默认 `android`。
`se_domain`	string	否	搜索引擎域名。平台会基于位置和语言自动选择合适域名，也可手动指定，例如 `google.co.uk`、`google.com.au`、`google.de`。
`depth`	integer	否	SERP 解析深度，即期望返回的结果数量。默认值为 `10`，最大值为 `200`。每 10 条结果通常对应一个计费单位；当搜索引擎返回 10 条结果时，可能产生额外费用。
`max_crawl_pages`	integer	否	最大抓取结果页数，最大值为 `100`。每抓取一个结果页都会计费，每页通常 10 条自然搜索结果。该参数与 `depth`合使用，用于控制总抓取范围。
`search_param`	string	否	附加搜索参数，用于传递搜索引擎支持的额外查询设置。
`load_async_ai_overview`	boolean	否	是否加载异步出现的 AI 概览。设为 `true` 时，即使 AI 概览异步加载，也会尝试获取对应 `ai_overview`素；设为 `false` 时返回缓存中可获取的 AI 概览。默认值：`false`。
`expand_ai_overview`	boolean	否	是否展开 AI 概览。设为 `true` 时展开 `ai_overview` 项。默认值：`false`。
`tag`	string	否	自定义任务标识，最长 255 个字符。可用于将请求与响应结果；响应的 `data` 对象中会原样返回该值。

请求示例

curl

bash

curl --location --request POST "https://api.seermartech.cn/v3/serp/wp/v2/live/html" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "language_code": "en",
      "location_code": 2840,
      "keyword": "albert einstein",
      "device": "desktop",
      "os": "windows",
      "depth": 10,
      "tag": "local-pack-html-demo"
    }
  ]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/serp/wp/v2/live/html"

# 实时 HTML 接口每次支持一个任务，POST 请求体为 JSON 数组
payload = [
    {
        "language_code": "en",
        "location_code": 2840,
        "keyword": "albert einstein",
        "device": "desktop",
        "os": "windows",
        "depth": 10,
        "tag": "local-pack-html-demo"
    }
]

response = requests.post(
    url,
    headers={
        "Authorization": "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json"
    },
    json=payload,
    timeout=60
)

response.raise_for_status()
result = response.json()

if result["status_code"] == 20000:
    print(result)
else:
    print(f'请求失败：{result["status_code"]} - {result["status_message"]}')

TypeScript

typescript

import axios from "axios";

// 实时 HTML 接口每次支持一个任务
const response = await axios.post(
  "https://api.seermartech.cn/v3/serp/wp/v2/live/html",
  [
    {
      language_code: "en",
      location_code: 2840,
      keyword: "albert einstein",
      device: "desktop",
      os: "windows",
      depth: 10,
      tag: "local-pack-html-demo"
    }
  ],
  {
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json"
    }
  }
);

const result = response.data;

if (result.status_code === 20000) {
  console.log(result);
} else {
  console.error(`请求失败：${result.status_code} - ${result.status_message}`);
}

响应字段

响应为 JSON 对象 tasks 数组本次提交的任务及结果。

顶层字段

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	局状态码。建议为各类异常和错误状态建立处理机制。错误码参考 `/v3/appendix/errors`。
`status_message`	string	局状态信息。
`time`	string	请求总执行时间，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务数量。
`tasks_error`	integer	返回错误的任务数量。
`tasks`	array	任务结果数组。

`tasks` 任务字段

字段	类型	说明
`id`	string	任务唯一标识，采用 UUID 格式。
`status_code`	integer	任务状态码，取值通常在 `10000` 至 `60000` 范围。错误码参考 `/v3/appendix/errors`。
`status_message`	string	任务状态信息。
`time`	string	任务执行时间，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`result_count`	integer	`result` 数组中的结果对象数量。
`path`	array	本次请求的 URL 路径信息。
`data`	object	回显请求中提交的任务参数 `tag`。
`result`	array	搜索结果数组。

`result` 结果字段

字段	类型	说明
`keyword`	string	实执行的。中的 `%##` 会被解码，`+` 会被解析为空格。
`type`	string	请求中的搜索引擎类型。
`se_domain`	string	实使用的搜索引擎域名。
`location_code`	integer	实使用的位置编码。
`language_code`	string	实使用的语言代码。
`datetime`	string	获取结果的 UTC 时间，格式为 `yyyy-mm-dd hh:mm:ss +00:00`。
`items_count`	integer	`items` 数组中返回的数量。
`items`	array	SERP 中识别出的搜索结果。
`page`	integer	返回的 HTML 页面序号。
`date`	string	HTML 页面抓取时间，UTC 格式。
`html`	string	搜索结果页的原始 HTML。

响应示例

json

{
  "version": "0.1.20200130",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "7.7543 sec.",
  "cost": 0.003,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "7.7543 sec.",
      "cost": 0.003,
      "result_count": 1,
      "path": [
        "v3",
        "serp",
        "wp",
        "v2",
        "live",
        "html"
      ],
      "data": {
        "api": "serp",
        "function": "live",
        "se": "wp",
        "se_type": "v2",
        "language_code": "en",
        "location_code": 2840,
        "keyword": "albert einstein",
        "tag": "local-pack-html-demo",
        "device": "desktop",
        "os": "windows"
      },
      "result": [
        {
          "keyword": "albert einstein",
          "type": "organic",
          "se_domain": "google.com",
          "location_code": 2840,
          "language_code": "en",
          "datetime": "2019-11-15 12:57:46 +00:00",
          "items_count": 0,
          "items": [],
          "page": 1,
          "date": "2019-11-15 12:57:46 +00:00",
          "html": "<!doctype html><html>...</html>"
        }
      ]
    }
  ]
}

错误处理

请同时检查顶层 status_code 与每个任务对象中的 status_code：

顶层状态码用于判断整个请求是否成功受理。
任务状态码用于判断单个任务是否成功执行。
当 tasks_error 大于 0 时，应遍历 tasks，读取失败任务的 status_code 和 status_message。
完整错误码说明请参考 /v3/appendix/errors。

实用场景

抓取本地搜索页面 HTML：保存指定城市、语言和设备下的原始搜索页面，用于审计本地搜索结果展示变化。
提取本地商家模块：从 HTML 中解析地图、本地商家卡片、联系方式和评价等，建设本地商家监测库。
监控品牌本地：按城市和移动端/桌面端定期查询品牌词，评估本地中的可见性与竞争对手覆盖。
验证搜索页面改版影响：对比不同日期采集的原始 HTML，识别搜索结果布局、富媒体或 AI 概览的结构变化。
构建自定义 SERP 解析器：获取未经预处理的页面，以适特定字段、页面模块或历史数据采集规则。

Google 本地实时 SERP HTML ​

计费说明 ​

请求参数 ​

请求示例 ​

curl ​

Python ​

TypeScript ​

响应字段 ​

顶层字段 ​

tasks 任务字段 ​

result 结果字段 ​

响应示例 ​

错误处理 ​

实用场景 ​