Google Maps SERP 任务创建

POST /v3/serp/google/maps/task_post

使用 POST /v3/serp/google/maps/task_post 创建 Google Maps 搜索结果采集任务。本接口按指定、地区、语言和设备类型获取本地搜索结果，单个任务最多可解析 700 条结果。任务创建成功后，可通过任务 id 查询结果，也可以通过 pingback_url 或 postback_url 接收完成通知或结果回调。

请求地址：

text

POST https://api.seermartech.cn/v3/serp/google/maps/task_post

所有请求体使用 UTF-8 编码的 JSON 数组格式。每次请求最多 100 个任务； 100 个任务的部分将返回错误码 40006。平台限流以认证说明中的 30/60/120 次/分钟规则为准。

本接口在成功创建任务时计费。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数

主要参数

字段	类型	填	说明
`keyword`	string	是	搜索，最长 700 个字符。`%##` 会被解码，`+` 会被解析为空格。如需传递字面量 `%`，请使用 `%25`；如需传递字面量 `+`，请使用 `%2B`。
`location_code`	integer	条件填	搜索地区代码。未提供 `location_name` 和 `location_coordinate` 时填。使用该字段后，无需再传递另外两个地区字段。示例：`2840`。
`language_code`	string	条件填	搜索语言代码。未提供 `language_name` 时填。使用该字段后，无需传递 `language_name`。示例：`en`。
`depth`	integer	否	解析结果数量。默认值：`100`；最大值：`700`。每满 100 条搜索结果可能产生一次额外计费；以返回结果及响应头扣费信息为准。
`priority`	integer	否	任务优级。`1`：普通优级，默认值；`2`：高优级。高优级任务通常处理更快，可能产生额外费用。
`device`	string	否	设备类型，可选 `desktop` 或 `mobile`，默认 `desktop`。使用 `mobile` 时，每个搜索结果页最多返回 20 条结果。
`pingback_url`	string	否	任务完成通知地址。任务完成后，本平台会向该地址发送 GET 请求。支持 `$id`（任务 ID）和 `$tag`（URL 编码后的标签）占位符，例如：`https://your-server.com/ping?id=$id&tag=$tag`。URL 中的特殊字符会自动编码，例如 `#` 会编码为 `%23`。
`postback_url`	string	否	结果回调地址。任务完成后，本平台会将 gzip 压缩的结果通过 POST 请求发送至该地址。支持 `$id` 和 `$tag` 占位符。URL 中的特殊字符会自动编码。
`postback_data`	string	条件填	指定 `postback_url` 时填。当前可选值：`advanced`。

> 若回调服务器在 10 秒未响应，连接将因时中断；该任务将转任务就绪列表，可再通过任务 ID 获取结果。

可选参数

字段	类型	说明
`location_name`	string	搜索地区完整名称。未提供 `location_code` 和 `location_coordinate` 时填。示例：`London,England,United Kingdom`。
`language_name`	string	搜索语言完整名称。未提供 `language_code` 时填。示例：`English`。
`os`	string	操作系统类型。`device=desktop` 时可选 `windows`、`macos`，默认 `windows`；`device=mobile` 时可选 `android`、`ios`，默认 `android`。
`max_crawl_pages`	integer	最大抓取结果页数，最大值 `100`。该参数与 `depth`合控制抓取范围。
`url`	string	Google Maps 搜索直链。本平台将自动解析 URL 中的查询参数。该方式要求 URL 中准确的地区和语言信息，通常建议优使用 `keyword`、地区及语言字段。示例：`https://google.com/maps/search/pizza/@37.09024,-95.712891,4z`。
`location_coordinate`	string	地理坐标，格式为 `"latitude,longitude,zoom"`。未提供 `location_code` 和 `location_name` 时填。未指定缩放级别时默认使用 `17z`；经纬度最多 7 位小数；缩放级别范围为 `3z` 至 `21z`。示例：`52.6178549,-155.352142,20z`。
`se_domain`	string	搜索引擎域名。默认根据地区和语言自动选择；可手动指定，例如 `google.co.uk`。
`search_this_area`	boolean	是否显示当前地图展示区域的结果。默认值：`true`。设为 `false` 时该模式，结果可能展示区域以外的商家。
`search_places`	boolean	是否启用地点搜索模式，默认值：`true`。该模式适用于查询特定地点或品牌门店，例如“纽约 Apple Store”。对于带有明确本地意图的，建议设为 `false`，以降低结果偏离指定地区的可能性。后，如搜索区域无结果，`results` 数组将为空。
`tag`	string	自定义任务标识，最长 255 个字符。用于将任务与业务数据；返回结果的 `data` 对象中会保留该值。

`url` 参数限制

使用 url 时，下列搜索修饰符不受支持；即使在 URL 中，也会被自动移除：

text

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

请求示例

curl

bash

curl --location --request POST "https://api.seermartech.cn/v3/serp/google/maps/task_post" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "language_code": "en",
      "location_code": 2840,
      "keyword": "pizza",
      "device": "desktop",
      "depth": 100,
      "tag": "maps-pizza-us"
    }
  ]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/serp/google/maps/task_post"

headers = {
    "Authorization": "Bearer smt_live_YOUR_KEY",
    "Content-Type": "application/json",
}

# 请求体为 JSON 数组，即使创建一个任务
payload = [
    {
        "language_code": "en",
        "location_code": 2840,
        "keyword": "pizza",
        "priority": 1,
        "device": "desktop",
        "tag": "maps-pizza-us",
        "pingback_url": "https://your-server.com/ping?id=$id&tag=$tag",
    }
]

response = requests.post(url, headers=headers, json=payload, timeout=30)
response.raise_for_status()

# 实人民币扣费以该响应头为准
charge_cny = response.headers.get("X-SeerMarTech-Charge-CNY")
print("本次扣费（CNY）：", charge_cny)
print(response.json())

TypeScript

typescript

import axios from "axios";

const response = await axios.post(
  "https://api.seermartech.cn/v3/serp/google/maps/task_post",
  [
    {
      language_code: "en",
      location_code: 2840,
      keyword: "pizza",
      location_coordinate: "37.09024,-95.712891,4z",
      search_this_area: true,
      search_places: true,
      postback_data: "advanced",
      postback_url: "https://your-server.com/postback?id=$id&tag=$tag",
      tag: "maps-pizza-us",
    },
  ],
  {
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
  },
);

// 实人民币扣费以响应头为准
console.log("本次扣费（CNY）：", response.headers["x-seermartech-charge-cny"]);
console.log(response.data);

响应说明

接口返回 JSON 对象 tasks 数组对应本次提交的各个任务。任务创建成功后，单个任务通常返回状态码 20100 和任务唯一标识 id。

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	请求总体状态码。建议根据状态码实现错误处理和重试机制。
`status_message`	string	请求总体状态信息。
`time`	string	请求处理耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务总数。
`tasks_error`	integer	创建失败的任务数量。
`tasks`	array	任务结果数组。
`tasks[].id`	string	任务唯一 ID，使用 UUID 格式。用于后续查询任务结果或回调。
`tasks[].status_code`	integer	单个任务状态码。
`tasks[].status_message`	string	单个任务状态说明。
`tasks[].time`	string	单个任务处理耗时。
`tasks[].cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks[].result_count`	integer	`result` 数组中的数量。创建任务时通常为 `0`。
`tasks[].path`	array	请求路径信息。
`tasks[].data`	object	本次任务提交并经平台标准化后的参数。
`tasks[].result`	array 或 `null`	任务结果。创建任务阶段固定为 `null`；需在任务完成后通过结果接口获取，或通过回调接收。

响应示例

json

{
  "version": "3.20191128",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.2539 sec.",
  "cost": 0.1,
  "tasks_count": 2,
  "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": [
        "v3",
        "serp",
        "google",
        "maps",
        "task_post"
      ],
      "data": {
        "api": "serp",
        "function": "task_post",
        "se": "google",
        "se_type": "maps",
        "language_code": "en",
        "location_code": 2840,
        "keyword": "pizza",
        "device": "desktop",
        "os": "windows",
        "tag": "maps-pizza-us"
      },
      "result": null
    },
    {
      "id": "22241653-0696-0066-0000-fa25e0da658e",
      "status_code": 20100,
      "status_message": "Task Created.",
      "time": "0.0000 sec.",
      "cost": 0.05,
      "result_count": 0,
      "path": [
        "v3",
        "serp",
        "google",
        "maps",
        "task_post"
      ],
      "data": {
        "api": "serp",
        "function": "task_post",
        "se": "google",
        "se_type": "maps",
        "url": "https://google.com/maps/search/pizza/@37.09024,-95.712891,4z",
        "postback_data": "advanced",
        "postback_url": "https://your-server.com/postback?id=$id&tag=$tag",
        "device": "desktop",
        "os": "windows"
      },
      "result": null
    }
  ]
}

常见状态码

状态码	含义	处理建议
`20000`	请求成功。	检查 `tasks` 中每个任务的状态。
`20100`	任务创建成功。	保存任务 `id`，用于后续获取结果或匹回调。
`40006`	单次请求中的任务数量限制。	将任务拆分为每批最多 100 条后重新提交。

使用建议

优使用 keyword、location_code 和 language_code 提交任务，依赖复杂的 url 参数解析。
对明确地域意图的查询，例如“上海咖啡店”或“伦敦牙医”，可将 search_places 设为 false，提高结果与指定地区的一致性。
使用 tag 写业务 ID、批次号或客户标识，便于异步结果回传后的处理。 -置 postback_url 时，服务端应支持接收 gzip 压缩的 POST 请求，并在 10 秒返回成功响应。
对创建成功但未收到回调的任务，可使用任务 id 从任务就绪列表或对应结果接口拉取数据。

实用场景

监控本地门店排名：按城市、坐标和创建地图搜索任务，持续追踪直营网点或加盟门店在本地搜索结果中的可见度。
分析竞品覆盖范围：针对“附近餐”“”等本地意图抓取地图结果，识别竞品在不同商圈和城市的。
评估区域化投放机会：使用 location_coordinate 指定商圈、社区或服务半径，发现特定区域的高频商家与市场空白点。
校验多地区品牌检索表现：以统一在多个地区批量创建任务，对比品牌门店、评价信息和地图结果排名的地区差异。
构建异步本地搜索监测系统：通过 postback_url 接收任务完成结果，自动更新本地 SEO 看板、门店运营报表或预警规则。

Google Maps SERP 任务创建 ​

请求参数 ​

主要参数 ​

可选参数 ​

url 参数限制 ​

请求示例 ​

curl ​

Python ​

TypeScript ​

响应说明 ​

响应示例 ​

常见状态码 ​

使用建议 ​

实用场景 ​