SeerMarTech API 文档

主题

Google Maps 任务下发 ​

接口说明 ​

用于创建 Google Maps SERP 抓取任务。任务创建后，本接口会按指定的地点、语言、设备等条件抓取对应搜索结果。

接口支持返回最多前 100 条搜索结果；结果会受到所选位置与语言设置影响。任务优级支持两档：

  • 1：普通优级（默认）
  • 2：高优级

请求方式 ​

POST https://api.seermartech.cn/v3/serp/wp/v2/task_post

注意：参考文档标题为 Google Maps，但示例与路径中使用的是 /v3/serp/wp/v2/task_post。如需对接，请以容路径为准。

计费与调用限制 ​

  • 在成功创建任务时扣费
  • 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准
  • depth 每 100 条结果，若搜索引擎返回更多结果，可能产生额外费用
  • 高优级任务会额外收费
  • 参考价请结合响应中的 cost 字段核算

调用限制：

  • 每分钟最多可提交 2000 次 API 调用
  • 每次 POST 最多可 100 个任务
  • 若单次请求中任务数 100，出部分会返回错误 40006

请求体格式 ​

POST 请求体为 UTF-8 编码的 JSON 数组：

json
[
 {
 "language_code": "en",
 "location_code": 2840,
 "keyword": "albert einstein"
 }
]

结果获取方式 ​

任务创建完成后，可通过以下方式获取结果：

  • 使用返回的任务唯一标识 id 主动获取结果
  • 在创建任务时指定 pingback_url，任务完成后平台向该地址发送 GET 通知
  • 在创建任务时指定 postback_url，任务完成后平台向该地址发送结果的 POST 请求，数据为 gzip 压缩格式

注意事项：

  • 若接收回调的服务器在 10 秒未响应，连接会因时中断
  • 此类任务会转 /v3/serp/google/maps/tasks_ready/ 列表中拉取
  • pingback_url 和 postback_url 中可使用 $id 和 $tag 变量，平台回调时会自动替换为值
  • 回调 URL 中的特殊字符会被 URL 编码，例如 # 会编码为 %23

主要参数 ​

字段名类型说明
keywordstring填。搜索，最长 700 个字符。字段中的 %## 会被解码，+ 会被解码为空格。如需传字面量 %，请写为 %25；如需传字面量 +，请写为 %2B。
location_codeinteger当未提供 location_name 或 location_coordinate 时填。搜索引擎位置编码。使用该字段时，无需再传 location_name 或 location_coordinate。示例：2840
language_codestring当未提供 language_name 时填。搜索引擎语言编码。使用该字段时，无需再传 language_name。示例：en
depthinteger可选。抓取深度，即希望返回的结果数。默认 100，最大 700。每个最多 100 条结果的 SERP 单独计费；如果设置大于 100，且搜索引擎返回更多结果，可能产生额外费用。
priorityinteger可选。任务优级：1 = 普通优级，2 = 高优级。默认 1。高优级会产生额外费用。
devicestring可选。设备类型，可选：desktop、mobile。默认 desktop。注意： mobile 设备下，每个 SERP 返回 20 条结果。
pingback_urlstring可选。任务完成通知地址。平台会向该地址发起 GET 请求。可在 URL 中使用 $id 和 $tag 占位符。示例：http://your-server.com/pingscript?id=$id、http://your-server.com/pingscript?id=$id&tag=$tag
postback_urlstring可选。任务结果回传地址。任务完成后，平台会向该地址发送携带结果的 POST 请求，数据为 gzip 压缩格式。可使用 $id 和 $tag 占位符。
postback_datastring当指定 postback_url 时填。表示 postback 返回的数据类型。可选值：advanced

附加参数 ​

字段名类型说明
location_namestring当未提供 location_code 或 location_coordinate 时填。位置完整名称。使用该字段时，无需再传 location_code 或 location_coordinate。示例：London,England,United Kingdom
language_namestring当未提供 language_code 时填。语言完整名称。使用该字段时，无需再传 language_code。示例：English
osstring可选。设备操作系统。若 device=desktop，可选 windows、macos，默认 windows；若 device=mobile，可选 android、ios，默认 android。
max_crawl_pagesinteger可选。最多抓取的搜索结果页数，最大 100。该参数与 depth 互为补，用于控制抓取范围。
urlstring可选。直接传查询 URL，平台会自动解析参数。此方式对 URL 中语言与地区要求更严格，处理难度更高，通常不建议优使用。示例：https://google.com/maps/search/pizza/@37.09024,-95.712891,4z
location_coordinatestring当未提供 location_name 或 location_code 时填。地理坐标，格式为 "latitude,longitude,zoom"。若未指定 zoom，默认使用 17z。latitude 与 longitude 最多支持 7 位小数；zoom 最小 3z，最大 21z。示例：52.6178549,-155.352142,20z
se_domainstring可选。搜索引擎域名。平台通常会根据位置和语言自动选择合适域名，也可手动指定。示例：google.co.uk
search_this_areaboolean可选。是否显示当前地图区域的结果。可选 true、false，默认 true。若设为 false，结果可能当前显示区域之外的商家。
search_placesboolean可选。是否启用地点搜索模式。该模式适合查询特定地点实体，如 “Apple Store in New York”。默认 true。对于带本地意图的，该模式可能导致结果偏向地点；如需，可设为 false。注意： 若后当前搜索区域无结果，results 数组可能为空。
tagstring可选。用户自定义任务标识，最长 255 个字符。可用于结果匹，响应中会在 data 对象返回该值。

URL 参数补说明 ​

若使用 url 参数，下列搜索引擎高级操作符不受支持；即便出现在 URL 中，也会被自动移除：

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

响应结构 ​

接口返回 JSON 数据， tasks 数组，每个任务都会有独立状态。

顶层字段 ​

字段名类型说明
versionstringAPI 当前版本
status_codeinteger接口总体状态码
status_messagestring接口总体状态信息
timestring本次请求执行时间，单位秒
costfloat本次请求总费用，单位 USD
tasks_countintegertasks 数组中的任务总数
tasks_errorinteger返回错误的任务数
tasksarray任务数组

tasks 数组中的字段 ​

字段名类型说明
idstring任务唯一标识，UUID 格式
status_codeinteger任务状态码，范围通常为 10000-60000
status_messagestring任务状态说明
timestring任务执行时间，单位秒
costfloat该任务费用，单位 USD
result_countintegerresult 数组中的数量
patharrayURL 路径信息
dataobject回显本次 POST 时提交的参数
resultarray / null任务结果。创建任务时此字段通常为 null

建议在接时完整处理状态码与异常场景，确保任务提交、回调接收和结果轮询过程稳定可靠。

状态码与错误处理 ​

  • 顶层 status_code 表示整个请求是否成功
  • tasks[].status_code 表示单个任务的处理状态
  • 若单次请求任务数 100，出部分会返回 40006
  • 任务创建成功时，单个任务通常返回：
  • 20100：Task Created.

完整错误码体系请参考 /v3/appendix/errors。

请求示例 ​

cURL ​

bash
curl --location --request POST "https://api.seermartech.cn/v3/serp/wp/v2/task_post" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "language_code": "en",
 "location_code": 2840,
 "keyword": "albert einstein"
 },
 {
 "language_name": "English",
 "location_name": "United States",
 "keyword": "albert einstein",
 "priority": 2,
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 },
 {
 "url": "https://google.com/maps/search/pizza/@37.09024,-95.712891,4z",
 "postback_data": "advanced",
 "postback_url": "https://your-server.com/postbackscript"
 }
]'

Python ​

python
import requests

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

data = [
 {
 # 示例1：最基础的任务创建方式
 "language_code": "en",
 "location_code": 2840,
 "keyword": "albert einstein"
 },
 {
 # 示例2：带高级优级、标签与 pingback 回调
 "language_name": "English",
 "location_name": "United States",
 "keyword": "albert einstein",
 "priority": 2,
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 },
 {
 # 示例3：通过 URL 直接创建任务，并在完成后通过 postback 接收结果
 "url": "https://google.com/maps/search/pizza/@37.09024,-95.712891,4z",
 "postback_data": "advanced",
 "postback_url": "https://your-server.com/postbackscript"
 }
]

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

TypeScript ​

typescript
import axios from "axios";

const postArray = [
 {
 // 示例1：基础任务
 language_code: "en",
 location_code: 2840,
 keyword: "albert einstein"
 },
 {
 // 示例2：附带高优级和 pingback 通知
 language_name: "English",
 location_name: "United States",
 keyword: "albert einstein",
 priority: 2,
 tag: "some_string_123",
 pingback_url: "https://your-server.com/pingscript?id=$id&tag=$tag"
 },
 {
 // 示例3：通过地图搜索 URL 创建任务
 url: "https://google.com/maps/search/pizza/@37.09024,-95.712891,4z",
 postback_data: "advanced",
 postback_url: "https://your-server.com/postbackscript"
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/serp/wp/v2/task_post",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 },
 data: postArray
})
 .then((response) => {
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error);
 });

响应示例 ​

json
{
 "version": "3.20191128",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.2539 sec.",
 "cost": 0.1,
 "tasks_count": 3,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "11141653-0696-0066-0000-fa25e0da658e",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0000 sec.",
 "cost": 0.05,
 "result_count": 0,
 "path": [],
 "data": {
 "api": "serp",
 "function": "task_post",
 "se": "wp",
 "se_type": "v2",
 "language_code": "en",
 "location_code": 2840,
 "keyword": "albert einstein",
 "device": "desktop",
 "os": "windows"
 },
 "result": null
 },
 {
 "id": "11141653-0696-0066-0000-fa25e0da658e",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0000 sec.",
 "cost": 0.05,
 "result_count": 0,
 "path": [],
 "data": {
 "api": "serp",
 "function": "task_post",
 "se": "wp",
 "se_type": "v2",
 "language_name": "English",
 "location_name": "United States",
 "keyword": "albert einstein",
 "priority": 2,
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag",
 "tag": "some_string_123",
 "device": "desktop",
 "os": "windows"
 },
 "result": null
 },
 {
 "id": "11141653-0696-0066-0000-fa25e0da658e",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0000 sec.",
 "cost": 0.05,
 "result_count": 0,
 "path": [],
 "data": {
 "api": "serp",
 "function": "task_post",
 "se": "wp",
 "se_type": "v2",
 "url": "https://www.google.co.uk/search?q=albert%20einstein&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS",
 "postback_data": "advanced",
 "postback_url": "https://your-server.com/postbackscript",
 "device": "desktop",
 "os": "windows"
 }
 }
 ]
}

实用场景 ​

  • 批量监控本地商家排名：按城市、语言和批量创建地图搜索任务，持续跟踪品牌门店或客户商家在本地搜索中的位置变化。
  • 评估区域化 SEO 表现：通过 location_code 或 location_coordinate 指定不同区域，对比同一在不同城市或商圈的地图结果差异，制定本地化优化策略。
  • 采集移动端地图结果：指定 device=mobile，查看移动端地图 SERP 的返回，用于优化移动场景下的本地搜索表现。
  • 构建异步抓取流水线：结合 pingback_url 或 postback_url，将任务创建、完成通知和结果库自动串联，适合高频批量监控业务。
  • 验证指定地图搜索：通过 url 直接提交特定地图查询链接，复现真实用户搜索路径，便于排查某些或地点的结果异常。

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

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