SeerMarTech API 文档

主题

获取 Google Local Finder SERP 高级结果 ​

接口概述 ​

GET /v3/serp/google/local_finder/task_get/advanced/$id

根据任务 ID 获取 Google Local Finder SERP 高级结果。任务提交成功后，可在 30 天重复获取结果，获取结果本身不额外计费。

认证方式 ​

请求需要使用 Bearer Token：

http
Authorization: Bearer smt_live_YOUR_KEY

计费说明 ​

本接口在提交任务时计费，获取任务结果不额外计费。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数 ​

接口通过 URL 路径传递任务 ID。

参数类型说明
idstring任务唯一标识，UUID 格式。任务提交后，可在 30 天使用该 ID 获取结果。

示例任务 ID：

text
02261816-2027-0066-0000-c27d02864073

请求示例 ​

curl ​

bash
TASK_ID="02261816-2027-0066-0000-c27d02864073"

curl --location --request GET \
  "https://api.seermartech.cn/v3/serp/google/local_finder/task_get/advanced/${TASK_ID}" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json"

TypeScript ​

typescript
import axios from "axios";

const taskId = "02231256-2604-0066-2000-57133b8fc54e";

axios
  .get(
    `https://api.seermartech.cn/v3/serp/google/local_finder/task_get/advanced/${taskId}`,
    {
      headers: {
        Authorization: "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
      },
    }
  )
  .then((response) => {
    // 处理任务结果
    console.log(response.data);
  })
  .catch((error) => {
    console.error("请求失败：", error.response?.data || error.message);
  });

Python ​

python
import requests

task_id = "02261816-2027-0066-0000-c27d02864073"
url = (
    "https://api.seermartech.cn/v3/serp/google/local_finder/"
    f"task_get/advanced/{task_id}"
)

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

if response.ok:
    result = response.json()
    print(result)
else:
    print(f"请求失败：{response.status_code} {response.text}")

响应结构 ​

接口返回 JSON 对象 tasks 为任务结果数组。

json
{
  "version": "0.1.20220819",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.0847 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "02261816-2027-0066-0000-c27d02864073",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.0847 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "serp",
        "google",
        "local_finder",
        "task_get",
        "advanced"
      ],
      "data": {
        "api": "serp",
        "function": "task_get",
        "se": "google",
        "se_type": "local_finder",
        "language_code": "en",
        "location_code": 2840,
        "keyword": "local nail services",
        "min_rating": 4.5,
        "time_filter": "monday",
        "device": "desktop",
        "os": "windows"
      },
      "result": [
        {
          "keyword": "local nail services",
          "type": "local_finder",
          "se_domain": "google.com",
          "location_code": 2840,
          "language_code": "en",
          "check_url": "https://www.google.com/search?q=local+nail+services",
          "datetime": "2019-11-15 12:57:46 +00:00",
          "item_types": [
            "local_pack"
          ],
          "se_results_count": 0,
          "items_count": 1,
          "items": [
            {
              "type": "local_pack",
              "rank_group": 1,
              "rank_absolute": 1,
              "position": "right",
              "xpath": "/html/body/div/div/div",
              "title": "Liam Nails",
              "description": "5+ years in business",
              "domain": "example.com",
              "phone": "+1 443-640-4298",
              "booking_url": "https://www.google.com/maps/reserve/appt",
              "url": "https://example.com/",
              "is_paid": false,
              "rating": {
                "rating_type": "Max5",
                "value": 4.5,
                "votes_count": 50,
                "rating_max": 5
              },
              "cid": "5302726516741959894",
              "rectangle": null
            }
          ]
        }
      ]
    }
  ]
}

顶层响应字段 ​

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

tasks 字段 ​

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

result 字段 ​

字段类型说明
keywordstringPOST 请求中提交的。返回时会对编码进行解码，+ 会被解码为空格。
typestringPOST 请求中指定的搜索类型。
se_domainstringPOST 请求中指定的搜索引擎域名。
location_codeintegerPOST 请求中指定的地域代码。
language_codestringPOST 请求中指定的语言代码。
check_urlstring搜索引擎结果页的直接 URL，可用于核验结果准确性。
datetimestring获取结果的日期和时间，使用 UTC 格式：yyyy-mm-dd hh-mm-ss +00:00。
spellobject搜索引擎自动纠错信息。
refinement_chipsobject搜索结果细化选项。
item_typesarraySERP 中的结果类型。当前可能 local_pack。
se_results_countintegerSERP 中结果总数。
items_countintegeritems 数组中返回的结果数量。
itemsarraySERP 中的结果。

spell ​

当搜索引擎对进行了自动纠错时返回。

字段类型说明
keywordstring自动纠错后的，结果对应此。
typestring自动纠错类型。可选值：did_you_mean、showing_results_for、no_results_found_for、including_results_for。

refinement_chips ​

字段类型说明
typestring素类型，固定为 refinement_chips。
xpathstring素在页面中的 XPath。
itemsarray当前细化选项中的项目列表。
optionsarray可用的搜索细化选项。

refinement_chips.items ​

字段类型说明
typestring素类型，固定为 refinement_chips_element。
titlestring细化项目标题。
urlstring含细化参数的搜索 URL。
domainstring结果所在域名。

refinement_chips.options ​

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

items 字段 ​

local_pack ​

local_pack 表示本地商家结果。

字段类型说明
typestring素类型，固定为 local_pack。
rank_groupinteger同类型结果中的组排名。不同类型之间的排名不会计此字段。
rank_absoluteinteger在整个 SERP 中的绝对排名。
positionstring结果在 SERP 中的对齐位置，可选值：left、right。
xpathstring结果在页面中的 XPath。
titlestringSERP 中展示的商家标题。
descriptionstringSERP 中展示的商家描述。
domainstringSERP 中展示的域名，可能为 null。
phonestring商家电话号码。
booking_urlstring预约或预订页面 URL。
urlstring商家页面 URL，可能为 null。
is_paidboolean是否为广告结果。true 表示广告，false 表示自然结果。
ratingobject商家评分信息。
cidstring搜索引擎定义的商家客户 ID，可用于调用 Google Reviews 接口获取完整评论列表。
rectangleobject结果摘要在 SERP 中的矩形区域坐标及像素尺寸。本类型结果通常为 null。

rating ​

字段类型说明
rating_typestring评分类型，可选值 Max5、Percents、CustomMax。
valuefloat评分值。
votes_countinteger评论或评分数量。
rating_maxinteger根据 rating_type 定义的最高评分值。

结果状态处理 ​

建议根据以下字段判断请求和任务是否成功：

  • 顶层 status_code：判断接口请求是否成功。
  • tasks[].status_code：判断单个任务是否成功。
  • tasks[].result：任务成功时通常结果数据。
  • tasks_error：统计本次响应中失败的任务数量。

当状态码表示错误或 result 为空时，应记录 status_code 和 status_message，并业务需要执行重试或异常告警。完整状态码和错误说明请参考本平台错误码文档。

沙箱调试 ​

如需查看该端点支持的完整 SERP 特征和扩展，可使用沙箱任务 ID：

text
https://sandbox.seermartech.cn/v3/serp/google/local_finder/task_get/advanced/00000000-0000-0000-0000-000000000000

沙箱响应会返回所有可用字段，但字段值为模拟数据。调用沙箱端点不会产生费用。

实用场景 ​

  • 监控本地商家排名：批量获取不同城市和下的 local_pack 排名，评估门店本地 SEO 表现。
  • 对比竞争商家信息：提取竞争商家的评分、评论数、电话、官网和预约链接，为竞品分析和商家拓展提供依据。
  • 分析本地搜索可见性：结合 rank_group、rank_absolute 和 item_types，统计品牌在本地搜索结果中的位置。
  • 核验 SERP 抓取准确性：使用 check_url 对搜索结果，定位、地域或语言造成的数据差异。
  • 发现本地搜索需求变化：分析 refinement_chips 中的细化词和搜索选项，扩展本地服务及选题。

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

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