SeerMarTech API 文档

主题

SERP 本地实时高级查询 ​

GET /v3/appendix/errors

本接口使用 POST 方法，路径为：

/v3/serp/wp/v2/live/advanced

本接口根据、搜索引擎、语言和地理位置，实时返回最多前 700 条搜索结果，并提供本地搜索结果（local_pack）等 SERP素。默认返回前 100 条结果。

计费与请求限制 ​

  • 本接口按请求计费。

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

  • 所有 POST 数据使用 UTF-8 编码的 JSON 格式。 平台限流以认证说明中的 30/60/120 次/分钟规则为准。

  • 每次请求最多 100 个任务。

  • 使用平台提供的 keyword、location_code 和 language_code 等系统标识符，可提升任务处理速度。

  • 当 keyword含以下高级搜索操作符时，单个任务的计费权重将乘以 5：

    allinanchor:、allintext:、allintitle:、allinurl:、define:、filetype:、id:、inanchor:、info:、intext:、intitle:、inurl:、link:、related:、site:

请求参数 ​

请求体是 JSON 数组：

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

任务参数 ​

参数类型填说明
urlstring否搜索查询的完整 URL。指定后，平台会从 URL 中解析字段。该方式处理难度较高，且 URL 中准确的语言和位置参数，通常不建议使用。示例：https://www.google.co.uk/search?q=%20rank%20tracker%20api&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS
keywordstring是查询，最长 700 个字符。所有 %## 编码会被解码，+ 会被解码为空格。如果中需要使用 %，请写成 %25。
location_namestring条件填搜索位置的完整名称。当未指定 location_code 或 location_coordinate 时填。使用该参数后，无需再传另外两个位置参数。示例：London,England,United Kingdom
location_codeinteger条件填搜索位置代码。当未指定 location_name 或 location_coordinate 时填。示例：2840
location_coordinatestring条件填GPS 坐标，格式为 纬度,经度,半径，例如 52.6178549,-155.352142,200。纬度和经度最多 7 位小数，半径最小值为 199.9。
language_namestring条件填搜索语言的完整名称。当未指定 language_code 时填。示例：English
language_codestring条件填搜索语言代码。当未指定 language_name 时填。示例：en
devicestring否设备类型，可选值：desktop、mobile。默认值：desktop。
osstring否操作系统。当 device 为 desktop 时，可选 windows、macos，默认值为 windows；当 device 为 mobile 时，可选 android、ios，默认值为 android。
targetstring否目标域名。指定后返回目标 URL 的 SERP素。支持使用 * 通符缩小匹范围。
se_domainstring否搜索引擎域名。平台会根据位置和语言自动选择合适的域名，也可以手动指定，例如 google.co.uk、google.com.au、google.de。
depthinteger否SERP 解析深度，即需要抓取的结果数量。默认值：100，最大值：700。如果指定深度返回结果数量，未使用部分将自动退还至账户余额。
search_paramstring否搜索查询的附加参数。可用于传递搜索引擎支持的查询参数。

target 匹示例 ​

值匹范围
*example.com*整个域名所有页面和子域名
example.com/example-page*URL 以指定字符串开头的页面
example.com网站首页，例如 https://example.com 或 https://www.example.com/
*example.com不限定子域名的页面，例如 https://en.example.com
example.com/example-page完匹指定 URL

获取位置和语言列表 ​

获取可用搜索位置：

/v3/serp/wp/locations

获取可用搜索语言：

/v3/serp/wp/languages

响应结构 ​

接口返回 JSON 数据任务处理状态和结果。

顶层响应字段 ​

字段类型说明
versionstring当前 API 版本
status_codeinteger顶层响应状态码
status_messagestring顶层提示信息
timestring请求执行耗时，单位为秒
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
tasks_countintegertasks 中的任务数量
tasks_errorinteger返回错误的任务数量
tasksobject/array任务结果集合。使用自定义 post_id 时，通常以 post_id 作为对象键

任务字段 ​

字段类型说明
idstring平台生成的任务唯一标识，UUID 格式
post_idstring请求中传的自定义任务标识
status_codeinteger任务状态码，通常在 10000 至 60000 范围
status_messagestring任务状态说明
timestring任务执行耗时
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
result_countintegerresult 数组中的结果数量
patharray请求处理路径
dataarray本次 API 调用中使用的参数信息
resultarraySERP 结果数组

完整状态码和错误信息请参考 /v3/appendix/errors。

SERP 结果字段 ​

字段类型说明
keywordstring请求中的。返回时会解码 %##，并将 + 解码为空格
typestring搜索引擎类型
se_domainstring搜索引擎域名
location_codeinteger搜索位置代码
language_codestring搜索语言代码
check_urlstring搜索引擎结果页的完整 URL，可用于核验结果准确性
datetimestring获取结果的日期和时间，格式为 年-月-日 时:分:秒 UTC偏移，例如 2019-11-15 12:57:46 +00:00
target_rankingsarray目标网站在 SERP 中的排名。当请求中指定 target 时返回
rank_absoluteinteger目标域名在所有 SERP素中的绝对排名
urlstring目标域名对应的 SERP URL
spellstring/null搜索引擎自动修正后的。如果搜索引擎对进行了修正，则返回修正后的
item_typesarraySERP 中的结果类型，例如 local_pack
se_results_countintegerSERP 中的结果总数
items_countintegeritems 数组中的结果数量
itemsarraySERP 中的结果

target_rankings 字段 ​

当请求参数中 target 时，target_rankings 会返回目标网站的排名信息。

字段类型说明
rank_absoluteinteger目标域名在 SERP 中的绝对排名
urlstring目标域名对应的结果 URL

items 中的本地结果字段 ​

当 items 中的类型为 local_pack 时，可返回以下字段：

字段类型说明
typestring素类型，固定为 local_pack
rank_groupinteger同类型结果中的组排名
rank_absoluteinteger在所有 SERP素中的绝对排名
positionstring素在 SERP 中的排列位置，可为 left 或 right
xpathstring该结果在页面中的 XPath
titlestringSERP 结果标题
descriptionstring结果描述
domainstring/null结果域名
phonestring/null电话号码
urlstring/nullURL
is_paidboolean是否为广告结果
ratingarray/null评分信息，基于评论数量和评分展示
rating_typestring评分类型，可为 Max5、Percents 或 CustomMax
valueinteger评分值
votes_countinteger评论或反馈数量
rating_maxinteger当前评分类型的最大值

请求示例 ​

curl ​

bash
curl --location --request POST \
  "https://api.seermartech.cn/v3/serp/wp/v2/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",
      "device": "desktop",
      "depth": 100
    }
  ]'

Python ​

python
import requests

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

headers = {
    "Authorization": "Bearer smt_live_YOUR_KEY",
    "Content-Type": "application/json",
}

payload = [
    {
        "language_code": "en",
        "location_code": 2840,
        "keyword": "albert einstein",
        "device": "desktop",
        "depth": 100,
    }
]

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

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        f"请求失败，状态码：{result.get('status_code')}，"
        f"信息：{result.get('status_message')}"
    )

TypeScript ​

typescript
const response = await fetch(
  "https://api.seermartech.cn/v3/serp/wp/v2/live/advanced",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify([
      {
        language_code: "en",
        location_code: 2840,
        keyword: "albert einstein",
        device: "desktop",
        depth: 100,
      },
    ]),
  }
);

const result = await response.json();

if (result.status_code === 20000) {
  console.log(result);
} else {
  console.error(
    `请求失败，状态码：${result.status_code}，信息：${result.status_message}`
  );
}

响应示例 ​

json
{
  "version": "3.20191128",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.3059 sec.",
  "cost": 0.05,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": {
    "post ID 1": {
      "id": "11151456-0696-0066-0000-002a5915da37",
      "post_id": "post ID 1",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.0952 sec.",
      "cost": 0.05,
      "result_count": 1,
      "path": [
        "v3",
        "serp",
        "wp",
        "v2",
        "live",
        "advanced"
      ],
      "data": [
        {
          "se": "wp",
          "se_type": "v2",
          "language_code": "en",
          "location_code": 2840,
          "keyword": "albert einstein"
        }
      ],
      "result": [
        {
          "keyword": "albert einstein",
          "type": "v2",
          "se_domain": "google.com",
          "location_code": 2840,
          "language_code": "en",
          "check_url": "https://www.google.com/search?q=albert+einstein",
          "datetime": "2019-11-15 12:57:46 +00:00",
          "target_rankings": [],
          "spell": null,
          "item_types": [
            "local_pack"
          ],
          "se_results_count": 85,
          "items_count": 1,
          "items": [
            {
              "type": "local_pack",
              "rank_group": 1,
              "rank_absolute": 1,
              "position": "left",
              "xpath": "/body/div/div/div/div/div/div/div/div/div",
              "title": "Cipro",
              "description": "Subway station Via Cipro",
              "domain": null,
              "phone": null,
              "url": null,
              "is_paid": false,
              "rating": null
            }
          ]
        }
      ]
    }
  }
}

实用场景 ​

  • 监控本地排名：按城市、语言和设备实时获取 SERP 及 local_pack 结果，评估门店或区域页面的本地搜索。
  • 核验多地区搜索结果：使用 location_code 或 GPS 坐标模拟不同地理位置，发现不同城市用户看到的结果差异。
  • 分析本地竞争对手：通过 target 精确筛选目标域名，统计在指定下的绝对排名和可见 URL。
  • 识别本地 SERP 版块：读取 item_types、items、评分和电话等字段，分析本地、广告和自然结果的展示结构。
  • 评估设备与系统差异：分别设置桌面端、移动端及对应操作系统，对比不同终端下的排名和 SERP 布局。

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

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