创建 Google 商家更新采集任务

POST /v3/business_data/google/my_business_updates/task_post

接口说明

该接口用于创建任务，采集指定商家实体在 Google 搜索结果中的最新更新。返回结果会受到所选地点与语言参数影响，因此同一商家在不同地区、不同语言下看到的更新可能不同。

请求方式：POST
接口地址：https://api.seermartech.cn/v3/business_data/google/my_business_updates/task_post

你可以通过任务提交后返回的唯一 id 获取结果；也可以在创建任务时传 postback_url 或 pingback_url，由本平台在任务完成后主动通知你的系统。

计费说明

创建任务时即会产生费用。

如需估算：

参考价约 ¥0.0360 / 次

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

请求规则

请求体使用 UTF-8 编码的 JSON
POST 请求体格式为JSON 数组：[{ ... }]
每分钟最多可提交 2000 次 API 调用
每次 POST 最多 100 个任务
如果单次请求中任务数 100，出部分将返回错误 40006

结果获取方式

任务提交成功后，可通过返回的任务 id 轮询获取结果。

如果在创建任务时指定了：

postback_url：任务完成后，本平台会向该地址发送 POST 请求，并以 gzip 压缩格式传输结果
pingback_url：任务完成后，本平台会向该地址发送 GET 通知

说明：

如果你的服务器在 10 秒未响应，连接会因时中断
该任务随后会 /v3/business_data/google/my_business_updates/tasks_ready/ 列表，供你后续拉取
回调失败时的错误码与错误信息取决于你的服务端

请求参数

字段名	类型	说明
`keyword`	string	填。用于指定本地商家名称。最长 700 字符。字段中的所有 `%##` 会被解码，字符 `+` 会被解码为空格。如需传递字面量 `%`，请写为 `%25`。该字段也可直接传 `cid`（Google 定义的商家唯一 ID）或 `place_id`（Google 地图中的商家标识）。示例：`cid:194604053573767737`、`place_id:GhIJQWDl0CIeQUARxks3icF8U8A`
`priority`	integer	可选。任务优级。`1` = 普通优级（默认）；`2` = 高优级。高优级任务会额外收费。
`location_name`	string	当未指定 `location_code` 或 `location_coordinate` 时填。搜索位置名。使用该字段时，无需再传 `location_code` 或 `location_coordinate`。可通过 `/v3/business_data/google/locations` 获取可用地点列表。示例：`London,England,United Kingdom`
`location_code`	integer	当未指定 `location_name` 或 `location_coordinate` 时填。搜索位置编码。使用该字段时，无需再传 `location_name` 或 `location_coordinate`。可通过 `/v3/business_data/google/locations` 获取。示例：`2840`
`location_coordinate`	string	当未指定 `location_name` 或 `location_code` 时填。GPS 坐标，格式为 `latitude,longitude,radius`。 `latitude` 与 `longitude` 最多 7 位小数，`radius` 最小值为 `199.9`。示例：`53.476225,-2.243572,200`
`language_name`	string	当未指定 `language_code` 时填。搜索语言名。使用该字段时，无需再传 `language_code`。可通过 `/v3/business_data/google/languages` 获取。示例：`English`
`language_code`	string	当未指定 `language_name` 时填。搜索语言代码。使用该字段时，无需再传 `language_name`。可通过 `/v3/business_data/google/languages` 获取。示例：`en`
`depth`	integer	可选。解析深度，即从搜索结果中提取的更新条数。建议按 10 的倍数设置，因为系统按连续 10 条进行处理。Google 最多返回 4490 条更新。默认值：`10`
`tag`	string	可选。自定义任务标识，最长 255 字符。便于你在业务系统中将请求与结果对应起来。提交后可在响应的 `data` 对象中看到该值。
`postback_url`	string	可选。任务完成后用于接收结果的回调地址。本平台会向该地址发送 POST 请求，并附带压缩结果。支持使用 `$id` 作为任务 ID 变量，`$tag` 作为经过 URL 编码的 tag 变量。示例：`http://your-server.com/postbackscript?id=$id`、`http://your-server.com/postbackscript?id=$id&tag=$tag`。注意：URL 中特殊字符会被编码，例如 `#` 会被编码为 `%23`
`pingback_url`	string	可选。任务完成通知地址。本平台会向该地址发送 GET 请求。支持使用 `$id` 作为任务 ID 变量，`$tag` 作为经过 URL 编码的 tag 变量。示例：`http://your-server.com/pingscript?id=$id`、`http://your-server.com/pingscript?id=$id&tag=$tag`。注意：URL 中特殊字符会被编码，例如 `#` 会被编码为 `%23`

响应结构

接口会返回 JSON 数据一个 tasks 数组，用于表示本次提交的任务状态。

顶层字段

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

`tasks[]` 字段

字段名	类型	说明
`id`	string	任务唯一标识，UUID 格式
`status_code`	integer	任务状态码，范围通常为 `10000-60000`
`status_message`	string	任务状态说明
`time`	string	当前任务处理耗时，单位秒
`cost`	float	当前任务费用，单位 USD
`result_count`	integer	`result` 数组中的数量
`path`	array	URL 路径
`data`	object	你在请求中提交的参数，会原样返回在该对象中
`result`	array \| null	结果数组。对于任务提交接口，此处通常为 `null`

请求示例

cURL

bash

curl --location --request POST "https://api.seermartech.cn/v3/business_data/google/my_business_updates/task_post" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "location_code": 1023191,
 "language_code": "en",
 "keyword": "RustyBrick, Inc."
 },
 {
 "location_name": "New York,New York,United States",
 "language_name": "English",
 "keyword": "RustyBrick, Inc.",
 "priority": 2,
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 }
]'

Python

python

import requests

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

data = [
 {
 "location_code": 1023191,
 "language_code": "en",
 "keyword": "RustyBrick, Inc."
 },
 {
 "location_name": "New York,New York,United States",
 "language_name": "English",
 "keyword": "RustyBrick, Inc.",
 "priority": 2,
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 }
]

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

TypeScript

typescript

import axios from "axios";

// 按 JSON 数组格式创建任务
const postArray = [
 {
 location_name: "New York,New York,United States",
 language_name: "English",
 keyword: "RustyBrick, Inc.",
 priority: 2,
 tag: "some_string_123",
 pingback_url: "https://your-server.com/pingscript?id=$id&tag=$tag"
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/business_data/google/my_business_updates/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": "0.1.20200909",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0981 sec.",
 "cost": 0.00225,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "business_data",
 "function": "my_business_updates",
 "se": "google",
 "language_code": "en",
 "location_name": "New York,New York,United States",
 "keyword": "RustyBrick, Inc.",
 "se_type": "business_updates",
 "device": "desktop",
 "os": "windows"
 },
 "result": null
 }
 ]
}

状态码与错误处理

顶层 status_code = 20000 表示请求成功
任务级别也会返回各自的 status_code 和 status_message
建议同时处理：
HTTP 状态码
顶层业务状态码
tasks[].status_code 任务状态码

常见注意事项： -过单次 100 个任务限制时，出部分返回 40006

回调地址不可达、时或拒绝连接时，任务不会立即丢失，而是会转 /v3/business_data/google/my_business_updates/tasks_ready/
如需稳定接收结果，建议建立任务重试、回调验签（如你方有实现）、时补拉等机制

使用建议

优使用 location_code 与 language_code

参数更稳定，便于程序化管理

商家标识尽量使用 cid 或 place_id

相比商家名称，唯一标识更适合重名和歧义

depth 建议按 10 的倍数设置

可更好匹平台处理方式，提高任务组织效率

批量提交时控制在每次 100 条

避触发 40006 错误

实用场景

监控门店动态更新：定期抓取品牌门店在搜索结果中的最新更新，及时发现营业信息、活动信息或变化。
对比不同地区商家展示差异：按不同 location_code 提交相同商家任务，分析区域化展示差异，为本地 SEO 优化提供依据。
追踪竞品商家运营：采集竞品门店更新频率与更新，评估本地搜索运营动作与活动节奏。
构建商家更新预警系统：结合 pingback_url 或 postback_url，在商家信息发生更新时自动触发通知，提高响应速度。
校验多语言本地化展示：按不同 language_code 拉取同一商家的更新结果，检查多语言是否正确展示，提升化或多区域运营质量。

创建 Google 商家更新采集任务 ​

接口说明 ​

计费说明 ​

请求规则 ​

结果获取方式 ​

请求参数 ​

响应结构 ​

顶层字段 ​

tasks[] 字段 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应示例 ​

状态码与错误处理 ​

使用建议 ​

实用场景 ​