SeerMarTech API 文档

主题

获取 WordPress V2 SERP 高级结果（按任务 ID） ​

接口说明 ​

通过任务 ID 获取已创建任务的高级 SERP 结果。

请求方式： GET请求地址： https://api.seermartech.cn/v3/serp/wp/v2/task_get/advanced/$id

$id 为任务唯一标识符（UUID）。

计费说明 ​

本接口不会因重复获取结果而重复计费。费用在创建任务时扣除；任务结果在生成后的 30 天可反复拉取。

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

路径参数 ​

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

返回结构说明 ​

接口返回 JSON 数据，顶层 tasks 数组，用于承载任务及结果信息。

顶层字段 ​

字段类型说明
versionstring当前 API 版本。
status_codeinteger通用状态码。建议对异常或错误状态建立完整处理机制。
status_messagestring通用状态信息。
timestring执行耗时，单位秒。
costfloat本次请求总成本，单位 USD。对于结果获取接口通常为 0。
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对应搜索结果的直达检查链接，可用于人工核验结果准确性。若需验证地理位置结果，打开链接后建议上下滚动页面并点击“Search this area”。
datetimestring结果抓取时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00。
spellobject搜索引擎自动纠错信息。若搜索引擎对进行了纠错，这里会返回纠错后的词及类型。
item_typesarray当前 SERP 中出现的结果类型列表。可能值：maps_search、maps_paid_item。
se_results_countintegerSERP 总结果数。
items_countintegeritems 数组中返回的数量。
itemsarraySERP 结果列表。
refinement_chipsobject搜索细化选项。

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带细化参数的搜索 URL。
domainstringSERP 中对应域名。
optionsarray更进一步的细化选项。

refinement_chips.items[].options[] 字段 ​

字段类型说明
typestring素类型，固定为 refinement_chips_option。
titlestring选项标题。
urlstring带细化参数的搜索 URL。
domainstringSERP 中对应域名。

items[] 结果类型说明 ​

本接口主要返回两类地图 SERP素：

  • maps_search：地图自然结果
  • maps_paid_item：本地搜索广告结果
字段类型说明
typestring固定为 maps_search。
rank_groupinteger分组排名；只在相同 type 的结果排序。
rank_absoluteintegerSERP 中的绝对排名。
domainstring结果中的域名。
titlestring结果标题。
original_titlestring原始标题，未经过搜索引擎翻译。
urlstring结果对应 URL。
contact_urlstring优联系页面 URL。
contributor_urlstring用户或实体的 Local Guides 资料页 URL（如有）。
book_online_urlstring“在线预订”按钮对应 URL，可跳转至预订或下单页面。
ratingobject评分信息。
rating_distributionobject1 星到 5 星的评分分布。
snippetstring摘要信息，通常地址等本地商家信息。
addressstring地址完整文本。
address_infoobject地址拆解信息。
place_idstring地点唯一标识。
phonestring电话号码。
main_imagestring商家资料中的主图 URL。
total_photosinteger商家资料中的图片总数。
categorystring主要商家类别。
additional_categoriesarray附加商家类别。
category_idsarray局类别 ID，不随国家变化。
work_hoursobject营业时间信息。
feature_idstring该 SERP素的唯一标识。
cidstring搜索引擎定义的本地商家客户端 ID。
latitudefloat地图纬度坐标。
longitudefloat地图经度坐标。
is_claimedboolean是否已被商家认领。
local_justificationsarray本地展示理由文本。
is_directory_itemboolean是否为目录型结果。
price_levelstring价格等级，可为 inexpensive、moderate、expensive、very_expensive，无信息时为 null。
hotel_ratinginteger店星级，范围 1-5；无信息时为 null。

rating 字段 ​

字段类型说明
rating_typestring评分类型，可能值：Max5、Percents、CustomMax。
valueinteger / float评分值。
votes_countinteger评价数量。
rating_maxinteger当前 rating_type 的最大值。

rating_distribution 字段 ​

字段类型说明
1integer1 星评价数。
2integer2 星评价数。
3integer3 星评价数。
4integer4 星评价数。
5integer5 星评价数。

address_info 字段 ​

字段类型说明
boroughstring所属行政区或区域。
addressstring街道地址。
citystring城市名称。
zipstring邮编。
regionstring所属区域。
country_codestring国家 ISO 编码。

work_hours 字段 ​

字段类型说明
timetableobject每周营业时间表。
current_statusstring当前营业状态，如 open 或 close。

timetable 字段 ​

timetable 按星期返回营业时间，以下字段：

  • sunday
  • monday
  • tuesday
  • wednesday
  • thursday
  • friday
  • saturday

每个字段通常为数组，数组：

字段类型说明
openobject开门时间。
closeobject门时间。

open / close 的结构如下：

字段类型说明
hourinteger小时，24 小时制。
minuteinteger分钟。

local_justifications 字段 ​

字段类型说明
typestring展示理由类型。可能值：user_review、website_mention、menu、other。
textstring展示理由文本。

本地搜索广告结果：maps_paid_item ​

字段类型说明
typestring固定为 maps_paid_item。
rank_groupinteger分组排名；只在相同 type 的结果排序。
rank_absoluteintegerSERP 中的绝对排名。
domainstring结果中的域名。
titlestring结果标题。
original_titlestring原始标题，未经过搜索引擎翻译。
urlstring结果对应 URL。
contact_urlstring优联系页面 URL。
ratingobject评分信息。
rating_distributionobject1 星到 5 星的评分分布。

rating、rating_distribution 结构与 maps_search 相同。

沙箱调试 ​

如需查看该高级结果端点支持的字段结构，可调用沙箱地址获取带有模拟数据的完整响应。沙箱调用不计费。

https://sandbox.本平台.com/v3/serp/google/maps/task_get/advanced/00000000-0000-0000-0000-000000000000

注意：/v3/... 路径为容路径，保持不变。

请求示例 ​

cURL ​

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

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

Python ​

python
import requests

task_id = "02231256-2604-0066-2000-57133b8fc54e"

url = f"https://api.seermartech.cn/v3/serp/wp/v2/task_get/advanced/{task_id}"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)
result = response.json

print(result)

TypeScript ​

typescript
import axios from "axios";

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

axios({
 method: "get",
 url: `https://api.seermartech.cn/v3/serp/wp/v2/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);
 });

响应示例 ​

json
{
 "version": "0.1.20230705",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0493 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "serp",
 "function": "task_get",
 "se": "google",
 "se_type": "maps",
 "language_code": "en",
 "keyword": "albert einstein",
 "location_code": 2840,
 "depth": 3,
 "device": "desktop",
 "os": "windows"
 },
 "result": [
 {
 "se_results_count": 0,
 "items_count": 3,
 "items": [
 {
 "work_hours": {
 "timetable": null,
 "current_status": "close"
 },
 "feature_id": "0x87b20589791fed49:0xaba52f97ba9e3b6a",
 "cid": "12368344280360434538",
 "latitude": 35.5064351,
 "longitude": -97.6317255,
 "is_claimed": false,
 "local_justifications": null,
 "is_directory_item": false,
 "price_level": null,
 "hotel_rating": null
 },
 {
 "type": "maps_search",
 "rank_group": 2,
 "rank_absolute": 2,
 "domain": "www.alberteinsteingroup.com",
 "title": "The Albert Einstein Group, Inc.",
 "original_title": null,
 "url": "http://www.alberteinsteingroup.com/",
 "contact_url": null,
 "contributor_url": null,
 "book_online_url": null,
 "rating": {
 "rating_type": "Max5",
 "value": 4,
 "votes_count": 4,
 "rating_max": null
 },
 "rating_distribution": {
 "1": 1,
 "2": 0,
 "3": 0,
 "4": 0,
 "5": 3
 },
 "snippet": "8710 Converse Business Cir, Converse, TX 78109",
 "address": "8710 Converse Business Cir, Converse, TX 78109",
 "address_info": {
 "borough": "Northeast Side",
 "address": "8710 Converse Business Cir",
 "city": "Converse",
 "zip": "78109",
 "region": "Texas",
 "country_code": "US"
 },
 "place_id": "ChIJ5QKOJR6KXIYRm3-tvYC0RuE",
 "phone": "+1833-463-3325",
 "main_image": "https://lh5.googleusercontent.com/p/AF1QipMwYCFGMituQ_CohAgfNF6pQPNjt-b-FR96b7xc=w416-h240-k-no",
 "total_photos": 18,
 "category": "Business to business service",
 "additional_categories": null,
 "category_ids": [],
 "work_hours": {
 "timetable": {
 "sunday": null,
 "monday": [],
 "tuesday": [],
 "wednesday": [],
 "thursday": [],
 "friday": [],
 "saturday": []
 },
 "current_status": "close"
 },
 "feature_id": "0x865c8a1e258e02e5:0xe146b480bdad7f9b",
 "cid": "16232860371934609307",
 "latitude": 29.515755199999997,
 "longitude": -98.3017169,
 "is_claimed": true,
 "local_justifications": null,
 "is_directory_item": false,
 "price_level": null,
 "hotel_rating": null
 },
 {
 "type": "maps_search",
 "rank_group": 3,
 "rank_absolute": 3,
 "domain": null,
 "title": "Albert Einstein Statue",
 "original_title": null,
 "url": null,
 "contact_url": null,
 "contributor_url": null,
 "book_online_url": null,
 "rating": {
 "rating_type": "Max5",
 "value": 4.7,
 "votes_count": 14,
 "rating_max": null
 },
 "rating_distribution": {
 "1": 0,
 "2": 0,
 "3": 1,
 "4": 2,
 "5": 11
 },
 "snippet": "172 Gore Creek Dr, Vail, CO 81657",
 "address": "172 Gore Creek Dr, Vail, CO 81657",
 "address_info": {
 "borough": null,
 "address": "172 Gore Creek Dr",
 "city": "Vail",
 "zip": "81657",
 "region": "Colorado",
 "country_code": "US"
 },
 "place_id": "ChIJy2EyO2xwaocRcwmC0WGy9jM",
 "phone": null,
 "main_image": "https://lh5.googleusercontent.com/p/AF1QipPzOIua4GVc8oLCTCNT6nkDZr369gpxVFPnkcOC=w408-h306-k-no",
 "total_photos": 10,
 "category": "Sculpture",
 "additional_categories": [],
 "category_ids": [],
 "work_hours": {
 "timetable": {
 "sunday": [],
 "monday": [],
 "tuesday": [],
 "wednesday": [],
 "thursday": [],
 "friday": [],
 "saturday": []
 },
 "current_status": "open"
 },
 "feature_id": "0x876a706c3b3261cb:0x33f6b261d1820973",
 "cid": "3744376273401678195",
 "latitude": 39.64065,
 "longitude": -106.37506669999999,
 "is_claimed": false,
 "local_justifications": null,
 "is_directory_item": false,
 "price_level": null,
 "hotel_rating": null
 }
 ]
 }
 ]
 }
 ]
}

错误处理建议 ​

  • 检查顶层 status_code 与 status_message
  • 再检查 tasks[].status_code
  • 若 tasks[].result 为空，通常表示任务尚未完成、任务不存在，或任务已过可查询期限
  • 建议结合 /v3/serp/wp/v2/tasks_ready 获取已完成任务，再逐个调用本接口获取结果

使用方式 ​

常见流程如下：

  1. 提交 SERP 任务
  2. 调用 /v3/serp/wp/v2/tasks_ready 获取已完成任务列表
  3. 使用返回的任务 ID 或 endpoint_advanced 调用 /v3/serp/wp/v2/task_get/advanced/$id 获取高级结果

实用场景 ​

  • 拉取本地商家榜单：获取地图搜索中的自然结果与广告结果，用于监控某下的本地商家格局。
  • 分析竞品门店信息：提取地址、电话、分类、营业时间、图片数、评分和评论分布，帮助销售或运营团队建立竞品档案。
  • 监控地图排名变化：按固定和位置周期性抓取 rank_group、rank_absolute，评估本地 SEO 优化效果。
  • 识别广告与自然结果占比：区分 maps_paid_item 与 maps_search，分析 SERP 中付费流量挤压，投放决策。
  • 构建门店数据地图：结合 place_id、cid、经纬度、分类与营业状态，生成本地商家分布数据，用于选址、覆盖率分析或区域运营。

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

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