SeerMarTech API 文档

主题

地图搜索实时高级接口 ​

本接口使用 POST 方法，路径为：

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

用于实时获取指定、搜索引擎及地理位置下的地图搜索结果，最多返回前 100 条结果。所有请求体使用 UTF-8 编码的 JSON 数组格式。每次调用最多提交 1 个任务；平台限流以认证说明中的 30/60/120 次/分钟规则为准。

认证方式 ​

请求头需携带 Bearer Token：

http
Authorization: Bearer smt_live_YOUR_KEY
Content-Type: application/json

计费说明 ​

接口按请求计费。示例中单任务成本为 0.002 美，按参考汇率折算后约为 ¥0.0144 / 次。当 depth过 100 且搜索引擎返回 100 条结果时，可能产生额外费用。

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

请求参数 ​

###填及主要参数

参数类型说明
keywordstring填。搜索，最长 700 个字符。参数中的 %## 编码会被解码，字符 + 会被解码为空格。如果中需要使用 %，请写为 %25；如需使用 +，请写为 %2B。
location_codeinteger搜索位置代码。当未指定 location_name 或 location_coordinate 时填。使用该参数后，不应再同时指定另外两个位置参数。可通过 /v3/serp/google/locations 获取可用位置代码。例如：2840。
language_codestring搜索语言代码。当未指定 language_name 时填。使用该参数后，不应再同时指定 language_name。可通过 /v3/serp/google/languages 获取可用语言代码。例如：en。
depthinteger解析深度，即需要获取的结果数量。默认值为 100，最大值为 700。每个最多 100 条结果的 SERP 单独计费。
devicestring设备类型，可选值为 desktop、mobile，默认值为 desktop。使用 mobile 时，每个 SERP 最多返回 20 条结果。

位置与语言参数 ​

参数类型说明
location_namestring搜索位置的完整名称。当未指定 location_code 或 location_coordinate 时填。例如：London,England,United Kingdom。
language_namestring搜索语言的完整名称。当未指定 language_code 时填。例如：English。
location_coordinatestring地理坐标，格式为 纬度,经度,缩放级别。未指定缩放级别时默认使用 17z。纬度和经度最多支持 7 位小数，缩放级别范围为 3z 至 21z。例如：52.6178549,-155.352142,20z。

位置和语言列表可通过以下接口查询：

  • /v3/serp/google/locations
  • /v3/serp/google/languages

设备与抓取参数 ​

参数类型说明
osstring设备操作系统。device=desktop 时可选 windows、macos，默认值为 windows；device=mobile 时可选 android、ios，默认值为 android。
max_crawl_pagesinteger最多抓取的搜索结果页数，最大值为 100。该参数与 depth合使用。
tagstring用户自定义任务标识，最长 255 个字符。可用于请求与响应，指定的值会原样返回在响应的 data 对象中。
urlstring搜索请求的完整 URL。本平台会从 URL 中解析参数。该方式处理复杂度较高，且 URL 中准确的语言和位置信息，通常不建议使用。例如：https://google.com/maps/search/pizza/@37.09024,-95.712891,4z。

以下搜索运算符不受支持，若出现在 url 中会被自动移除：

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

地图搜索参数 ​

参数类型说明
se_domainstring搜索引擎域名。平台会根据位置和语言自动选择合适的域名，也可以手动指定，例如 google.co.uk、google.com.au、google.de。
search_this_areaboolean是否返回当前地图显示区域的结果。可选值为 true、false，默认值为 true。设置为 false 后将该模式，地图列表可能当前显示区域之外的结果。
search_placesboolean是否启用地点搜索模式。启用后可以查询指定地点中的商家或机构，例如纽约的 Apple Store。默认值为 true。对于本地搜索意图的，建议根据需求设置为 false，以返回与请求位置不一致的结果。后，如果搜索区域没有结果，results 数组将为空。

请求示例 ​

curl ​

bash
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",
      "depth": 100,
      "device": "desktop",
      "os": "windows"
    }
  ]'

Python ​

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",
}

# 每次请求最多提交一个任务
payload = [
    {
        "language_code": "en",
        "location_code": 2840,
        "keyword": "albert einstein",
        "depth": 100,
        "device": "desktop",
        "os": "windows",
    }
]

response = requests.post(url, headers=headers, json=payload)
result = response.json()

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        f"请求失败，错误码：{result.get('status_code')}，"
        f"错误信息：{result.get('status_message')}"
    )

TypeScript ​

typescript
import axios from "axios";

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

console.log(response.data);

响应结构 ​

接口返回 JSON 数据，顶层 tasks 数组。以下为主要字段说明。

顶层字段 ​

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

任务字段 ​

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

result 字段 ​

字段类型说明
keywordstring请求中的。返回时已对 %## 进行解码，字符 + 会被解码为空格。
typestring搜索引擎类型。
se_domainstring搜索引擎域名。
location_codeinteger搜索位置代码。
language_codestring搜索语言代码。
check_urlstring对应的搜索结果页面 URL，可用于核验返回结果。检查特定位置结果时，打开该 URL 后上下滚动，并点击“搜索此区域”。
datetimestring获取结果的时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00。例如：2019-11-15 12:57:46 +00:00。
spellobject搜索引擎自动纠错信息。
refinement_chipsobject搜索细化选项。
item_typesarray结果类型列表，可能 maps_search、maps_paid_item。
se_results_countintegerSERP 中的结果总数。
items_countintegeritems 数组中返回的结果数量。
itemsarray地图搜索结果列表。

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进一步的搜索细化选项。

items 中的字段：

字段类型说明
typestring固定为 refinement_chips_element。
titlestring细化项目标题。
urlstring携带细化参数的搜索 URL。
domainstringSERP 中的域名。

options 中的字段：

字段类型说明
typestring固定为 refinement_chips_option。
titlestring展示标题。
original_titlestring原始标题，即未经过搜索引擎翻译的标题。
urlstring携带细化参数的搜索 URL。
domainstringSERP 中的域名。

地图结果字段 ​

items 数组中的结果主要分为 maps_search 和 maps_paid_item 两种类型。

字段类型说明
typestring固定为 maps_search。
rank_groupinteger同类型结果中的组排名。不同类型之间不计该排名。
rank_absoluteinteger所有 SERP素中的绝对排名。
domainstring结果域名。
titlestring结果标题。
original_titlestring未经搜索引擎翻译的原始标题。
urlstring结果 URL。
contact_urlstring商家首选联系页面 URL。
contributor_urlstring用户或实体的本地向导资料页 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营业时间信息。
current_statusstring当前营业状态，例如 open、close。
feature_idstringSERP 中该的唯一标识。
cidstring地图平台定义的商家唯一 ID，可用于查询评论。
latitudefloat纬度。例如：51.584091。
longitudefloat经度。例如：-0.31365919999999997。
is_claimedboolean是否已认领该商家资料。
local_justificationsarray本地搜索展示理由。
is_directory_itemboolean是否为目录类条目。
price_levelstring价格等级，可选值为 inexpensive、moderate、expensive、very_expensive；无数据时为 null。
hotel_ratinginteger店星级，范围为 1 至 5；无数据时为 null。

maps_paid_item ​

付费地图结果以下字段：

字段类型说明
typestring固定为 maps_paid_item。
rank_groupinteger同类型结果中的组排名。
rank_absoluteinteger所有 SERP素中的绝对排名。
domainstring结果域名。
titlestring结果标题。
original_titlestring未经搜索引擎翻译的原始标题。
urlstring结果 URL。
contact_urlstring商家首选联系页面 URL。
ratingobject商家评分信息。
rating_distributionobject1 至 5 星评分数量分布。

rating 评分对象 ​

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

rating_distribution 评分分布对象 ​

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

address_info 地址对象 ​

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

work_hours 营业时间对象 ​

字段类型说明
timetableobject每周营业时间表。
sundayarray周日营业时间段。
mondayarray周一营业时间段。
tuesdayarray周二营业时间段。
wednesdayarray周三营业时间段。
thursdayarray周四营业时间段。
fridayarray周五营业时间段。
saturdayarray周营业时间段。
current_statusstring当前状态，表示营业或。

每天的营业时间数组可 open 和 close 对象：

json
{
  "open": {
    "hour": 9,
    "minute": 0
  },
  "close": {
    "hour": 18,
    "minute": 0
  }
}

：

字段类型说明
hourinteger24 小时制小时数。
minuteinteger分钟数。

local_justifications 本地展示理由 ​

字段类型说明
typestring理由类型，可选值为 user_review、website_mention、menu、other。
textstring用于解释该商家为何出现在当前查询结果中的文本摘要。

响应示例 ​

json
{
  "version": "0.1.20230705",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "4.0977 sec.",
  "cost": 0.0144,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "4.0977 sec.",
      "cost": 0.0144,
      "result_count": 1,
      "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": [
        {
          "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",
          "item_types": [
            "maps_search"
          ],
          "se_results_count": 3,
          "items_count": 3,
          "items": [
            {
              "type": "maps_search",
              "rank_group": 1,
              "rank_absolute": 1,
              "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,
              "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/example",
              "total_photos": 2501,
              "category": "Sculpture",
              "additional_categories": [],
              "category_ids": [],
              "work_hours": {
                "timetable": null,
                "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
            }
          ]
        }
      ]
    }
  ]
}

状态码与错误处理 ​

  • 20000：请求成功。
  • 任务级错误通过 tasks[].status_code 和 tasks[].status_message 返回。
  • 请求级错误通过顶层 status_code 和 status_message 返回。
  • 完整状态码列表请参考：/v3/appendix/errors

建议客户端同时检查顶层状态码、任务状态码以及 tasks_error，并针对网络时、参数错误、位置或语言不支持等实现重试和异常处理机制。

实用场景 ​

  • 监测本地排名：按城市、坐标和设备实时采集地图结果，评估门店在本地 SERP 中的位置。
  • 分析竞争商家表现：提取竞争商家的排名、评分、评价数量、类别和营业状态，支持本地 SEO 竞品对比。
  • 构建门店信息数据库：批量同步地址、电话、经纬度、营业时间、图片数量和地点 ID，完善企业门店数据资产。
  • 评估本地搜索优化效果：定期对比 rank_group、rank_absolute 和 se_results_count，量化本地 SEO 优化前后的变化。
  • 发现地图结果中的商业机会：结合 maps_paid_item、类别、价格等级和评分分布，识别广告竞争激烈或潜在客户集中的区域。

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

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