SeerMarTech API 文档

主题

获取 Google Local Finder 高级结果（按任务 ID） ​

接口说明 ​

通过任务 ID 获取已提交的 Google Local Finder SERP 高级结果。

注意：你只会在创建任务时产生费用；任务提交成功后，可在 30 天多次获取结果。 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求地址

GET https://api.seermartech.cn/v3/serp/google/local_finder/task_get/advanced/$id

计费说明 ​

本接口为结果读取接口，本身不重复收费。费用发生在对应任务创建时。

如果参考文档页提供了单价，应换算为人民币展示；但当前页面未给出明确单价，因此请以任务提交接口返回的 cost 字段为准。

路径参数 ​

字段类型说明
idstring任务唯一标识符，UUID 格式。在本平台系统唯一。任务创建后可在 30 天随时使用该 ID 获取结果。

沙箱调试 ​

你可以使用以下沙箱地址查看本接口支持的字段结构，返回为模拟数据，不产生费用：

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

沙箱响应会本接口可返回的 SERP素及字段，但字段值为示例数据。

响应结构 ​

接口返回 JSON 数据，顶层 tasks 数组。

顶层字段 ​

字段类型说明
versionstring当前 API 版本
status_codeinteger通用状态码
status_messagestring通用状态信息
timestring执行耗时，单位秒
costfloat本次请求总成本，单位 USD
tasks_countintegertasks 数组中的任务数量
tasks_errorintegertasks 数组中返回错误的任务数量
tasksarray任务结果数组

建议在接时实现完整的异常处理与状态码处理机制。

tasks[] 字段 ​

字段类型说明
idstring任务 ID，UUID 格式
status_codeinteger任务级状态码，取值通常在 10000-60000 之间
status_messagestring任务级状态信息
timestring任务执行耗时，单位秒
costfloat该任务成本，单位 USD
result_countintegerresult 数组中的结果数量
patharrayURL 路径
dataobject与创建任务时 POST 请求中传参数一致
resultarray结果数组

result[] 字段 ​

字段类型说明
keywordstring创建任务时传的。返回时会对 %## 形式进行解码，+ 会被还原为空格。
typestring创建任务时传的搜索引擎类型
se_domainstring创建任务时传的搜索引擎域名
location_codeinteger创建任务时传的位置编码
language_codestring创建任务时传的语言编码
check_urlstring搜索结果直达链接，可用于核验返回结果是否与页面一致
datetimestring结果获取时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00
spellobject搜索引擎自动纠错信息
refinement_chipsobject搜索细化标签
item_typesarray当前 SERP 中识别出的结果类型列表
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细化标签列表

refinement_chips.items[] ​

字段类型说明
typestring素类型，固定为 refinement_chips_element
titlestring标签标题
urlstring带细化参数的搜索链接
domainstringSERP 中展示的域名
optionsarray进一步细化选项

refinement_chips.items[].options[] ​

字段类型说明
typestring素类型，固定为 refinement_chips_option
titlestring选项标题
urlstring带细化参数的搜索链接
domainstringSERP 中展示的域名

item_types 可选值 ​

item_types含当前 SERP 中识别到的结果类型。当前页面示例中可能出现：

  • local_pack

Local Pack 结果字段说明 ​

items[] 中的类型为 local_pack 时，字段如下：

字段类型说明
typestring素类型，固定为 local_pack
rank_groupinteger分组排名。只在相同 type 的结果组计数。
rank_absoluteintegerSERP局绝对排名
positionstring素在页面中的布局位置，可选值：left、right
xpathstring素 XPath
titlestring本地结果标题
descriptionstringSERP 中展示的描述信息
domainstring展示域名
phonestring电话号码
booking_urlstring预约页面链接
urlstring落地页链接
is_paidboolean是否为广告
ratingobject评分信息
cidstring搜索引擎定义的本地商家唯一标识
rectangleobject结果在 SERP 页面中的矩形坐标与尺寸信息；该场景下通常为 null

rating 字段 ​

字段类型说明
rating_typestring评分类型，可能值：Max5、Percents、CustomMax
valuefloat评分值
votes_countinteger评论/反馈数量
rating_maxinteger当前 rating_type 对应的满分值

请求示例 ​

cURL ​

bash
# 按任务 ID 获取 Google Local Finder 高级结果
id="02261816-2027-0066-0000-c27d02864073"

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

Python ​

python
import requests

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

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

response = requests.get(url, headers=headers)
print(response.status_code)
print(response.json)

TypeScript ​

typescript
import axios from "axios";

// 按任务 ID 获取高级结果
const taskId = "02231256-2604-0066-2000-57133b8fc54e";

axios({
 method: "get",
 url: `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);
 });

响应示例 ​

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.0312 sec.",
 "cost": 0,
 "result_count": 1,
 "path": [
 "v3",
 "serp",
 "google",
 "local_finder",
 "task_get",
 "advanced",
 "02261816-2027-0066-0000-c27d02864073"
 ],
 "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": [
 {
 "se_results_count": 0,
 "items_count": 20,
 "items": [
 {
 "type": "local_pack",
 "rank_group": 1,
 "rank_absolute": 1,
 "position": "right",
 "xpath": "/body/div/div/div/div/div/div/div/div/div/div/div/div/div/div/div/div/div/div",
 "title": "Liam Nails",
 "description": "5+ years in business\nMon: 9AM–5PM · +1 443-640-4298\n“I’ve been to many nail places in my life and so far this one is the best.”",
 "domain": "kubiti.wordpress.com",
 "phone": "+1 443-640-4298",
 "booking_url": "https://www.google.com/maps/reserve/appt/place/...",
 "url": "https://kubiti.wordpress.com/nail-trends/?liam+nails",
 "is_paid": false,
 "rating": {
 "rating_type": "Max5",
 "value": 4.5,
 "votes_count": 50,
 "rating_max": 5
 },
 "cid": "5302726516741959894",
 "rectangle": null
 },
 {
 "type": "local_pack",
 "rank_group": 2,
 "rank_absolute": 2,
 "position": "right",
 "xpath": "/html/body/div/div/div/div/div/div/div/div/div/div/div/div/div/div/div/div/div/div",
 "title": "Elite Nails",
 "description": "10+ years in business · Bartlesville, OK, United States\nMon: 9AM–7PM · +1 918-333-9888\n“Best nail experience of all time!!!!”",
 "domain": "kubiti.wordpress.com",
 "phone": "+1 918-333-9888",
 "booking_url": "https://www.google.com/maps/reserve/appt/place/...",
 "url": "https://kubiti.wordpress.com/nail-trends/?elite+nails",
 "is_paid": false,
 "rating": {
 "rating_type": "Max5",
 "value": 4.7,
 "votes_count": 353,
 "rating_max": 5
 },
 "cid": "17867200233795892980",
 "rectangle": null
 },
 {
 "type": "local_pack",
 "rank_group": 3,
 "rank_absolute": 3,
 "position": "right",
 "xpath": "/html/body/div/div/div/div/div/div/div/div/div/div/div/div/div/div/div/div/div/div",
 "title": "Kim's Nails",
 "description": "10+ years in business · Bartlesville, OK, United States\nMon: 10AM–6PM · +1 918-331-9099\n“Thought it was a good place to get my nails done.”",
 "domain": null,
 "phone": "+1 918-331-9099",
 "booking_url": "https://www.google.com/maps/reserve/appt/place/...",
 "url": null,
 "is_paid": false,
 "rating": {
 "rating_type": "Max5",
 "value": 4.6,
 "votes_count": 150,
 "rating_max": 5
 },
 "cid": "4930805168864698620",
 "rectangle": null
 }
 ]
 }
 ]
 }
 ]
}

状态码与错误处理 ​

  • 顶层 status_code 表示整次请求的处理状态。
  • tasks[].status_code 表示单个任务的处理状态。
  • 建议优判断：
  1. HTTP 状态码是否为 200
  2. 顶层 status_code 是否为 20000
  3. tasks_error 是否为 0
  4. 各 tasks[].result 是否存在且非空

常见处理建议：

场景建议
任务 ID 不存在或已过期检查任务是否在 30 天有效期
返回成功但 result 为空确认任务是否已完成，时通过就绪任务接口轮询
tasks[].status_code 为错误码记录错误信息并重试或告警
数据字段缺失某些本地商家可能没有官网、电话或评分，需 null 值

使用建议 ​

  • 如果你是异步批量采集，建议通过任务就绪接口获取可读取任务，再按 ID 调用本接口取回结果。
  • check_url 可用于人工抽样核验结果。
  • cid 可作为本地商家实体标识，用于后续评论、门店画像或去重分析。
  • domain、url、phone 可能为空，库时请做好空值容。

实用场景 ​

  • 监控本地排名：按和地区抓取 Local Finder 排名，持续跟踪门店在本地搜索中的位置变化。
  • 分析竞品门店：提取竞品的标题、电话、官网、评分和评论量，快速建立区域竞对单。
  • 筛选高意向商机：通过 rating、votes_count 和 booking_url 识别活跃且可预约的本地商家，用于销售线索挖掘。
  • 评估本地 SEO 覆盖：结合 domain、url 与排名结果，判断品牌官网是否成功承接本地搜索流量。
  • 构建门店知识库：利用 cid、电话、官网和描述信息沉淀本地商家实体数据，支持后续评论分析与地图搜索研究。

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

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