地图搜索实时高级结果

POST /v3/serp/wp/maps/live/advanced

接口说明

该接口用于实时获取指定关键词、搜索引擎地区与语言下的地图搜索结果，支持返回最多前 100 条结果；在更高抓取深度下，最多可获取 700 条结果。

• 接口路径：/v3/serp/wp/maps/live/advanced
• 请求方式：POST
• 请求地址：https://api.seermartech.cn/v3/serp/wp/maps/live/advanced

本接口为实时接口，请求后直接返回解析结果，不需要轮询任务状态。

计费说明

每次请求都会产生扣费。

• 默认按单次请求计费
• 当 depth过 100，且目标搜索引擎返回 100 条结果时，可能产生额外费用
• 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准

根据示例响应，单次请求参考价约为 ¥0.0320 / 次。

请求限制

• 所有 POST 数据使用 UTF-8 编码的 JSON
• 请求体为 JSON 数组：[{ ... }]
• 每分钟最多可发起 2000 次 API 调用
• 每次 Live SERP 请求支持 1 个任务

---

请求参数

主要参数

字段名	类型	填	说明
keyword	string	是	搜索，最长 700 个字符。%## 会被解码，+ 会被解码为空格。如需传 %，请写为 %25；如需传 +，请写为 %2B。
location_code	integer	条件填	搜索地区编码。当未提供 location_name 或 location_coordinate 时填。若使用该字段，则无需再传 location_name 或 location_coordinate。可通过 /v3/serp/google/locations 获取可用地区编码。示例：2840
language_code	string	条件填	搜索语言编码。当未提供 language_name 时填。若使用该字段，则无需再传 language_name。可通过 /v3/serp/google/languages 获取可用语言编码。示例：en
depth	integer	否	解析深度，即返回结果数量。默认值：100，最大值：700。
device	string	否	设备类型，可选：desktop、mobile。默认值：desktop。注意： 当 device=mobile 时，每个 SERP 返回 20 条结果。

附加参数

字段名	类型	填	说明
location_name	string	条件填	搜索地区完整名称。当未提供 location_code 或 location_coordinate 时填。若使用该字段，则无需再传 location_code 或 location_coordinate。可通过 /v3/serp/google/locations 获取可用地区名称。示例：London,England,United Kingdom
language_name	string	条件填	搜索语言完整名称。当未提供 language_code 时填。若使用该字段，则无需再传 language_code。可通过 /v3/serp/google/languages 获取可用语言名称。示例：English
os	string	否	设备操作系统。若 device=desktop，可选 windows、macos，默认 windows；若 device=mobile，可选 android、ios，默认 android。
tag	string	否	自定义任务标识，最长 255 字符。可用于请求与结果的对应，响应中的 data 对象会原样返回该值。
max_crawl_pages	integer	否	最大抓取结果页数，最大值：100。该参数与 depth 决定抓取范围。
url	string	否	可直接传搜索 URL，由本接口自动解析为对应参数。通常不推荐使用，因为该方式对 URL 中的地区和语言要求更严格，处理复杂度也更高。示例：https://google.com/maps/search/pizza/@37.09024,-95.712891,4z
location_coordinate	string	条件填	GPS 坐标，格式为 "latitude,longitude,zoom"。当未提供 location_name 或 location_code 时填。若省略 zoom，默认使用 17z。纬度、经度最多 7 位小数；zoom 最小 3z，最大 21z。示例：52.6178549,-155.352142,20z
se_domain	string	否	搜索引擎域名。系统通常会按地区和语言自动选择，也可手动指定。示例：google.co.uk、google.com.au、google.de。
search_this_area	boolean	否	是否启用“在此区域搜索”模式。可选：true、false，默认 true。若设为 false，地图结果可能出当前显示区域。
search_places	boolean	否	是否启用地点搜索模式。默认 true。该模式适合搜索明确地点实体（例如某城市中的某品牌门店），但在部分本地意图场景下可能干扰地区判断。若需此类影响，可设为 false。注意： 若后在指定区域未找到结果，results 数组可能为空。

url 参数不支持的搜索操作符

若在 url 中以下搜索操作符，系统会自动忽略：

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

---

请求示例

cURL

curl --location --request POST "https://api.seermartech.cn/v3/serp/wp/maps/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"
 }
]'

Python

import requests

url = "https://api.seermartech.cn/v3/serp/wp/maps/live/advanced"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
data = [
 {
 "language_code": "en",
 "location_code": 2840,
 "keyword": "albert einstein"
 }
]

response = requests.post(url, headers=headers, json=data)
print(response.json)

TypeScript

import axios from "axios";

async function main {
 const response = await axios.post(
 "https://api.seermartech.cn/v3/serp/wp/maps/live/advanced",
 [
 {
 language_code: "en",
 location_code: 2840,
 keyword: "albert einstein"
 }
 ],
 {
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 }
 }
 );

 console.log(response.data);
}

main.catch(console.error);

---

响应结构

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

顶层字段

字段名	类型	说明
version	string	当前 API 版本
status_code	integer	通用状态码，完整错误码参考 /v3/appendix/errors
status_message	string	通用状态信息，完整列表参考 /v3/appendix/errors
time	string	执行耗时，单位秒
cost	float	本次请求总成本，单位 USD
tasks_count	integer	tasks 数组中的任务数量
tasks_error	integer	返回错误的任务数量
tasks	array	任务结果数组

tasks[] 字段

字段名	类型	说明
id	string	任务唯一标识，UUID 格式
status_code	integer	任务状态码，范围通常为 10000-60000，完整错误码参考 /v3/appendix/errors
status_message	string	任务状态说明
time	string	任务执行耗时
cost	float	任务成本，单位 USD
result_count	integer	result 数组中的数量
path	array	URL 路径
data	object	原样回传请求中的任务参数
result	array	结果数组

result[] 字段

字段名	类型	说明
keyword	string	请求中的；返回时 %## 已解码，+ 会被转为空格
type	string	请求中的搜索引擎类型
se_domain	string	请求中的搜索引擎域名
location_code	integer	请求中的地区编码
language_code	string	请求中的语言编码
check_url	string	搜索结果直达地址，可用于人工核验结果。若核验地区结果，建议打开链接后上下滚动，再点击“Search this area”进行验证。
datetime	string	结果获取时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00
spell	object	搜索引擎自动纠错信息
refinement_chips	object	搜索细化标签信息
item_types	array	当前 SERP 中出现的结果类型，可能值：maps_search、maps_paid_item
se_results_count	integer	SERP 总结果数
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	进一步细化选项

refinement_chips.items[].options[]

字段名	类型	说明
type	string	固定为 refinement_chips_option
title	string	选项标题
original_title	string	原始标题，未被搜索引擎翻译
url	string	带细化参数的搜索 URL
domain	string	SERP 中的域名

---

items[] 结果类型说明

1）自然地图结果 maps_search

字段名	类型	说明
type	string	固定为 maps_search
rank_group	integer	同类型结果中的组排名
rank_absolute	integer	整个 SERP 中的绝对排名
domain	string	结果对应域名
title	string	结果标题
original_title	string	原始标题，未被搜索引擎翻译
url	string	结果链接
contact_url	string	优联系页面链接
contributor_url	string	用户或实体的 Local Guides 资料页链接（如有）
book_online_url	string	“在线预订”按钮对应链接
rating	object	评分信息
rating_distribution	object	1 星到 5 星评分分布
snippet	string	摘要，通常地址及商家简介
address	string	地址文本
address_info	object	地址结构化信息
place_id	string	地点唯一标识
phone	string	电话号码
main_image	string	商家主页主图链接
total_photos	integer	图片总数
category	string	主分类
additional_categories	array	附加分类
category_ids	array	通用分类 ID，不随国家变化
work_hours	object	营业时间信息
feature_id	string	SERP 中该的唯一标识
cid	string	平台定义的本地商户唯一 ID
latitude	float	纬度
longitude	float	经度
is_claimed	boolean	是否已认领商家所有权
local_justifications	array	本地展示理由文本
is_directory_item	boolean	是否为目录类结果
price_level	string	价格水平，可选：inexpensive、moderate、expensive、very_expensive；无数据时为 null
hotel_rating	integer	店星级，范围 1–5；无数据时为 null

rating 评分对象

字段名	类型	说明
rating_type	string	评分类型，可见值：Max5、Percents、CustomMax
value	integer/float	评分值
votes_count	integer	评价数量
rating_max	integer	当前评分类型的最大值

rating_distribution 评分分布对象

字段名	类型	说明
1	integer	1 星评价数
2	integer	2 星评价数
3	integer	3 星评价数
4	integer	4 星评价数
5	integer	5 星评价数

address_info 地址对象

字段名	类型	说明
borough	string	行政区 / 区域
address	string	街道地址
city	string	城市
zip	string	邮编
region	string	区域 / 州 / DMA 区
country_code	string	国家 ISO 编码

work_hours 营业时间对象

字段名	类型	说明
timetable	object	每周营业时间表
current_status	string	当前营业状态，如 open、close

timetable 下可能以下字段：sunday、monday、tuesday、wednesday、thursday、friday、saturday。 各字段通常为数组，：

字段名	类型	说明
open	object	开始营业时间
close	object	结束营业时间

open / close 对象结构：

字段名	类型	说明
hour	integer	24 小时制小时
minute	integer	分钟

local_justifications[] 本地展示理由

字段名	类型	说明
type	string	理由类型，可选：user_review、website_mention、menu、other
text	string	展示理由文本片段

2）本地搜索广告结果 maps_paid_item

字段名	类型	说明
type	string	固定为 maps_paid_item
rank_group	integer	同类型结果中的组排名
rank_absolute	integer	整个 SERP 中的绝对排名
domain	string	结果对应域名
title	string	结果标题
original_title	string	原始标题，未被搜索引擎翻译
url	string	结果链接
contact_url	string	优联系页面链接
rating	object	评分信息
rating_distribution	object	评分分布

---

响应示例

{
 "version": "0.1.20230705",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "4.0977 sec.",
 "cost": 0.002,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "serp",
 "function": "live",
 "se": "google",
 "se_type": "maps",
 "language_code": "en",
 "location_code": 2840,
 "keyword": "albert einstein",
 "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.nasonline.org",
 "title": "Albert Einstein Memorial",
 "original_title": null,
 "url": "http://www.nasonline.org/about-nas/visiting-nas/nas-building/the-einstein-memorial.html",
 "contact_url": null,
 "contributor_url": null,
 "book_online_url": null,
 "rating": {
 "rating_type": "Max5",
 "value": 4.7,
 "votes_count": 1283,
 "rating_max": null
 },
 "rating_distribution": {
 "1": 4,
 "2": 8,
 "3": 51,
 "4": 194,
 "5": 1026
 },
 "snippet": "2101 Constitution Ave. NW, Washington, DC 20418",
 "address": "2101 Constitution Ave. NW, Washington, DC 20418",
 "address_info": {
 "borough": "Northwest Washington",
 "address": "2101 Constitution Ave. NW",
 "city": "Washington",
 "zip": "20418",
 "region": "District of Columbia",
 "country_code": "US"
 },
 "place_id": "ChIJJZaaKqm3t4kRbBG17Vcv8Rg",
 "phone": null,
 "main_image": "https://lh5.googleusercontent.com/p/AF1QipPyOiGml7eII8LgiYGtPh4wzI7g8GP3fZ9Hzsy8=w408-h306-k-no",
 "total_photos": 2501,
 "category": "Sculpture",
 "additional_categories": [],
 "category_ids": [],
 "work_hours": {
 "timetable": {
 "sunday": [],
 "monday": [],
 "tuesday": [],
 "wednesday": [],
 "thursday": [],
 "friday": [],
 "saturday": []
 },
 "current_status": "open"
 },
 "feature_id": "0x89b7b7a92a9a9625:0x18f12f57edb5116c",
 "cid": "1797269780994265452",
 "latitude": 38.8924028,
 "longitude": -77.0484139,
 "is_claimed": false,
 "local_justifications": null,
 "is_directory_item": false,
 "price_level": null,
 "hotel_rating": null
 },
 {
 "type": "maps_search",
 "rank_group": 3,
 "rank_absolute": 3,
 "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
 }
 ]
 }
 ]
 }
 ]
}

---

错误处理

• 顶层 status_code 表示整个请求的执行状态
• tasks[].status_code 表示单个任务的执行状态
• 建议同时检查：
• HTTP 状态码
• 顶层 status_code
• 任务级 tasks[].status_code

常见排查点：

1. 缺少 keyword
2. 未提供 location_code / location_name / location_coordinate 中的任一项
3. 未提供 language_code 或 language_name
4. location_coordinate 格式不符合 "latitude,longitude,zoom"
5. device 与 os 组合不匹
6. depth 或 max_crawl_pages出范围

完整错误码与说明请参考容路径：/v3/appendix/errors

实用场景

• 监控本地商家地图排名：按城市、语言和设备定期抓取的地图结果，跟踪自家门店或客户商户在本地搜索中的排名变化。
• 分析竞品门店覆盖：抓取某类服务词下的地图结果，识别竞品的门店分布、评分、评论量和营业状态，为区域扩张提供依据。
• 校验商户资料完整性：利用返回的地址、电话、主图、分类、营业时间等字段，批量检查商户信息是否完整，提升地图与转化率。
• 识别高意图本地流量机会：通过 local_justifications、评分分布和分类信息，筛选更容易触发地图展示的，优化本地 SEO 策略。
• 区分自然结果与地图广告：同时获取 maps_search 与 maps_paid_item，评估某下广告占位对自然地图的挤压程度。