按任务 ID 获取 WP V2 地图 SERP 高级结果

使用 GET /v3/serp/wp/v2/task_get/advanced/{id} 获取已创建地图 SERP 任务的高级结果 {id} 为任务 UUID。任务结果自创建起保留 30 天，可在有效期重复查询；费用在提交任务时产生。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

text

GET https://api.seermartech.cn/v3/serp/wp/v2/task_get/advanced/{id}

> 注意：wp/v2 是容 API 路径的一部分，调用时原样保留。

请求参数

参数	类型	填	说明
`id`	string	是	任务唯一标识符，采用 UUID 格式。任务创建后 30 天可用于查询结果。

请求示例

curl

bash

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

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

Python

python

import requests

task_id = "02261816-2027-0066-0000-c27d02864073"

response = requests.get(
    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",
    },
    timeout=30,
)

response.raise_for_status()
data = response.json()

# 顶层状态码为 20000 表示请求成功
if data["status_code"] == 20000:
    task = data["tasks"][0]
    if task["status_code"] < 40000 and task.get("result"):
        print(task["result"])
    else:
        print(f"任务错误：{task['status_code']} - {task['status_message']}")
else:
    print(f"请求错误：{data['status_code']} - {data['status_message']}")

TypeScript

typescript

import axios from "axios";

const taskId = "02261816-2027-0066-0000-c27d02864073";

async function getTaskResult() {
  const response = await axios.get(
    `https://api.seermartech.cn/v3/serp/wp/v2/task_get/advanced/${taskId}`,
    {
      headers: {
        Authorization: "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
      },
    },
  );

  const data = response.data;

  if (data.status_code !== 20000) {
    throw new Error(`请求失败：${data.status_code} - ${data.status_message}`);
  }

  const task = data.tasks?.[0];

  if (!task || task.status_code >= 40000 || !task.result) {
    throw new Error(
      `任务未成功返回结果：${task?.status_code} - ${task?.status_message}`,
    );
  }

  console.log(task.result);
}

getTaskResult().catch(console.error);

获取已完成任务后再查询

如未保存任务 ID，可调用以下接口获取已完成任务列表：

text

GET /v3/serp/wp/v2/tasks_ready

在返回结果中读取任务的 endpoint_advanced，然后请求该地址；也可直接使用任务的 id 拼接为：

text

/v3/serp/wp/v2/task_get/advanced/{id}

沙箱测试

可使用沙箱接口查看本端点支持的字段。沙箱返回模拟数据，不产生费用。

text

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

响应结构

接口返回 JSON 对象，顶层 tasks 数组。每个任务对象对应一次结果查询。

json

{
  "version": "0.1.20230705",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.0493 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "02261816-2027-0066-0000-c27d02864073",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.0321 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "serp",
        "wp",
        "v2",
        "task_get",
        "advanced",
        "02261816-2027-0066-0000-c27d02864073"
      ],
      "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": [
        {
          "keyword": "albert einstein",
          "type": "maps",
          "se_domain": "google.com",
          "location_code": 2840,
          "language_code": "en",
          "check_url": "https://www.google.com/maps/search/albert+einstein/",
          "datetime": "2019-11-15 12:57:46 +00:00",
          "spell": null,
          "refinement_chips": null,
          "item_types": [
            "maps_search"
          ],
          "se_results_count": 0,
          "items_count": 1,
          "items": [
            {
              "type": "maps_search",
              "rank_group": 1,
              "rank_absolute": 1,
              "domain": "www.example.com",
              "title": "示例本地商家",
              "original_title": null,
              "url": "https://www.example.com/",
              "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": "示例地址",
              "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": "+1-833-463-3325",
              "main_image": "https://lh5.googleusercontent.com/example",
              "total_photos": 10,
              "category": "Business service",
              "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.3750667,
              "is_claimed": false,
              "local_justifications": null,
              "is_directory_item": false,
              "price_level": null,
              "hotel_rating": null
            }
          ]
        }
      ]
    }
  ]
}

顶层响应字段

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	局响应状态码。`20000` 表示成功。
`status_message`	string	局状态说明。
`time`	string	请求执行耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务数量。
`tasks_error`	integer	返回错误的任务数量。
`tasks`	array	任务结果数组。

任务对象字段

字段	类型	说明
`id`	string	任务 UUID。
`status_code`	integer	任务状态码，通常范围为 `10000`–`60000`。
`status_message`	string	任务状态说明。
`time`	string	任务执行耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`result_count`	integer	`result` 数组中的结果对象数量。
`path`	array	本次请求对应的 API 路径。
`data`	object	创建任务时提交的原始参数。
`result`	array	地图 SERP 结果数组。

> 建议同时处理 HTTP 状态码、顶层 status_code 和任务级 status_code。当任务状态码大于或等于 40000 时，应按错误处理。

结果对象字段

字段	类型	说明
`keyword`	string	查询。编码后的 `%##` 会被解码，`+` 会转换为空格。
`type`	string	搜索引擎结果类型。
`se_domain`	string	搜索引擎域名。
`location_code`	integer	创建任务时使用的地区代码。
`language_code`	string	创建任务时使用的语言代码。
`check_url`	string	搜索结果直达链接，可用于核验结果。检查地区化地图结果时，请在页面上下移动后点击“在此区域搜索”。
`datetime`	string	获取结果的 UTC 时间，格式为 `yyyy-mm-dd hh:mm:ss +00:00`。
`spell`	object / null	搜索引擎自动纠错信息。
`refinement_chips`	object / null	搜索结果页中的搜索细化标签。
`item_types`	array	SERP 中发现的结果类型，可 `maps_search`、`maps_paid_item`。
`se_results_count`	integer	搜索结果总数。
`items_count`	integer	`items` 数组返回的结果数量。
`items`	array	地图搜索结果或地图广告结果。

`spell` 自动纠错字段

当搜索引擎对进行了纠错时，接口会返回该对象。

字段	类型	说明
`keyword`	string	自动纠错后的，结果基于该返回。
`type`	string	纠错类型：`did_you_mean`、`showing_results_for`、`no_results_found_for`、`including_results_for`。

`refinement_chips` 搜索细化标签字段

字段	类型	说明
`type`	string	固定为 `refinement_chips`。
`xpath`	string	素的 XPath。
`items`	array	细化标签列表。

refinement_chips.items 中的每一项：

字段	类型	说明
`type`	string	固定为 `refinement_chips_element`。
`title`	string	标签标题。
`url`	string	带细化条件的搜索 URL。
`domain`	string	SERP 中的域名。
`options`	array	更进一步的细化选项。

options 中每一项：

字段	类型	说明
`type`	string	固定为 `refinement_chips_option`。
`title`	string	选项标题。
`url`	string	带细化条件的搜索 URL。
`domain`	string	SERP 中的域名。

地图自然结果：`maps_search`

items 中 type 为 maps_search 的对象表示地图自然搜索结果。

字段	类型	说明
`type`	string	固定为 `maps_search`。
`rank_group`	integer	同类型结果中的排名。不同类型结果不会计该排名。
`rank_absolute`	integer	所有 SERP素中的绝对排名。
`domain`	string / null	商家网站域名。
`title`	string	商家或地点名称。
`original_title`	string / null	未经搜索引擎翻译的原始标题。
`url`	string / null	商家 URL。
`contact_url`	string / null	首选联系页面 URL。
`contributor_url`	string / null	本地向导用户或实体主页 URL（如有）。
`book_online_url`	string / null	“在线预订”按钮跳转地址。
`rating`	object / null	评分信息。
`rating_distribution`	object / null	1 至 5 星评价数量分布。
`snippet`	string / null	结果摘要，通常含地址或本地商家描述。
`address`	string / null	商家完整地址。
`address_info`	object / null	结构化地址信息。
`place_id`	string / null	地点唯一标识符。
`phone`	string / null	商家联系电话。
`main_image`	string / null	商家主页主图 URL。
`total_photos`	integer / null	商家资料中的图片总数。
`category`	string / null	主营业类别。
`additional_categories`	array / null	补营业类别。
`category_ids`	array / null	不随国家变化的通用类别 ID。
`work_hours`	object / null	营业时间与当前营业状态。
`feature_id`	string	SERP素唯一标识符。
`cid`	string	本地商家的客户端 ID，可用于评价数据查询。
`latitude`	float	商家在地图中的纬度。
`longitude`	float	商家在地图中的经度。
`is_claimed`	boolean	是否已被商家认领。
`local_justifications`	array / null	本地结果展示原因摘要。
`is_directory_item`	boolean	是否为目录类商家或聚合目录。
`price_level`	string / null	价格水平：`inexpensive`、`moderate`、`expensive`、`very_expensive`。
`hotel_rating`	integer / null	店星级，范围为 1–5；非或无数据时为 `null`。

`rating` 评分字段

字段	类型	说明
`rating_type`	string	评分类型：`Max5`、`Percents`、`CustomMax`。
`value`	number	当前评分值。
`votes_count`	integer	评价数量。
`rating_max`	number / null	当前评分类型的最大值。

`rating_distribution` 评分分布字段

字段	类型	说明
`1`	integer	一星评价数量。
`2`	integer	二星评价数量。
`3`	integer	三星评价数量。
`4`	integer	四星评价数量。
`5`	integer	五星评价数量。

`address_info` 地址字段

字段	类型	说明
`borough`	string / null	所属行政区、城区或街区。
`address`	string / null	街道地址。
`city`	string / null	城市名称。
`zip`	string / null	邮政编码。
`region`	string / null	所属地区。
`country_code`	string / null	ISO 国家代码。

`work_hours` 营业时间字段

字段	类型	说明
`timetable`	object / null	每周营业时间表。
`current_status`	string	当前营业状态，例如 `open` 或 `close`。

work_hours.timetable 可 sunday、monday、tuesday、wednesday、thursday、friday、saturday。每一天均为时段数组，每个时段：

字段	类型	说明
`open.hour`	integer	开始营业小时，24 小时制。
`open.minute`	integer	开始营业分钟。
`close.hour`	integer	结束营业小时，24 小时制。
`close.minute`	integer	结束营业分钟。

`local_justifications` 本地展示原因字段

该数组说明商家为何会针对当前展示。

字段	类型	说明
`type`	string	原因类型：`user_review`、`website_mention`、`menu`、`other`。
`text`	string	对应的文本摘要。

地图广告结果：`maps_paid_item`

items 中 type 为 maps_paid_item 的对象表示地图付费推广结果。

字段	类型	说明
`type`	string	固定为 `maps_paid_item`。
`rank_group`	integer	同类型广告结果中的排名。
`rank_absolute`	integer	所有 SERP素中的绝对排名。
`domain`	string / null	商家网站域名。
`title`	string	商家或地点名称。
`original_title`	string / null	未翻译的原始标题。
`url`	string / null	商家 URL。
`contact_url`	string / null	首选联系页面 URL。
`rating`	object / null	评分信息，字段结构见 `maps_search.rating`。
`rating_distribution`	object / null	评分分布，字段结构见 `maps_search.rating_distribution`。

状态码处理建议

20000：请求成功。
小于 40000 的任务状态码通常表示任务可处理或已成功完成。
大于或等于 40000 的任务状态码表示任务级错误，应记录 status_code 与 status_message 后执行重试、告警或降级处理。
若 result 为空，可能表示任务尚未完成、任务已失效，或当前查询条件下未返回数据。

实用场景

监控本地排名：按城市、语言和设备查询地图结果，持续追踪门店在本地搜索中的自然排名与变化。
识别本地竞品：提取地图结果中的商家名称、类别、评分、评价量和地址，构建区域竞品单并比较竞争强度。
优化门店资料完整度：检查电话、营业时间、图片数量、商家认领状态及类别信息，定位影响本地转化的资料缺口。
分析本地广告占位：通过 maps_paid_item 识别地图搜索中的付费推广结果，评估自然结果与广告位之间的竞争。
挖掘评价与口碑信号：结合评分分布、评价数量和 local_justifications，发现用户点并制定门店口碑优化策略。

按任务 ID 获取 WP V2 地图 SERP 高级结果 ​

请求参数 ​

请求示例 ​

curl ​

Python ​

TypeScript ​

获取已完成任务后再查询 ​

沙箱测试 ​

响应结构 ​

顶层响应字段 ​

任务对象字段 ​

结果对象字段 ​

spell 自动纠错字段 ​

refinement_chips 搜索细化标签字段 ​

地图自然结果：maps_search ​

rating 评分字段 ​

rating_distribution 评分分布字段 ​

address_info 地址字段 ​

work_hours 营业时间字段 ​

local_justifications 本地展示原因字段 ​

地图广告结果：maps_paid_item ​

状态码处理建议 ​

实用场景 ​

按任务 ID 获取 WP V2 地图 SERP 高级结果

请求参数

请求示例

curl

Python

TypeScript

获取已完成任务后再查询

沙箱测试

响应结构

顶层响应字段

任务对象字段

结果对象字段

`spell` 自动纠错字段

`refinement_chips` 搜索细化标签字段

地图自然结果：`maps_search`

`rating` 评分字段

`rating_distribution` 评分分布字段

`address_info` 地址字段

`work_hours` 营业时间字段

`local_justifications` 本地展示原因字段

地图广告结果：`maps_paid_item`

状态码处理建议

实用场景