SeerMarTech API 文档

主题

Google Events SERP 任务创建 ​

GET /v3/serp/google/events/task_post

接口说明 ​

该接口用于提交 Google Events 搜索结果抓取任务，按指定和地区返回 Google Events SERP 数据。

  • 接口路径：POST /v3/serp/google/events/task_post
  • 支持英文搜索语言
  • 支持两种任务优级：
  • 1：普通优级（默认）
  • 2：高优级

你可以在任务创建成功后，使用返回的任务 id 获取结果；也可以在创建任务时设置 pingback_url 或 postback_url，由本平台在任务完成后主动通知或推送结果。

请求地址 ​

https://api.seermartech.cn/v3/serp/google/events/task_post

计费与调用限制 ​

  • 在成功创建任务时扣费
  • 参考价约 ¥0.0240 / 次
  • 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准
  • 每分钟最多可提交 2000 次 API 调用
  • 每次 POST 最多 100 个任务 -过 100 个任务时，出部分会返回错误 40006

###深度计费

参数 depth 表示抓取结果数量：

  • 默认值：10
  • 最大值：700
  • 账户通常按每个最多 10 条结果的 SERP计费
  • 当 depth > 10 且搜索引擎返回 10 条结果时，可能产生额外扣费
  • 若设置的 depth 大于返回结果数，差额会自动退回到账户余额
  • 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准

###回调

如果设置了 pingback_url 或 postback_url：

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

注意：

  • 你的服务器若在 10 秒未响应，连接会因时被中止
  • 对应任务会转 Tasks Ready 列表，后续可自行获取结果
  • 实错误码和错误信息取决于你的服务器

请求体格式 ​

所有 POST 数据使用 UTF-8 编码的 JSON，且请求体为 JSON 数组：

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

主要参数 ​

字段名类型说明
keywordstring填。搜索，最长 700 个字符。%## 会被解码，+ 会被解码为空格。如需保留 %，请写为 %25；如需保留 +，请写为 %2B。
location_codeinteger搜索引擎地区代码。当未指定 location_name 或 location_coordinate 时填。如果使用该字段，则无需再传 location_name 或 location_coordinate。地区列表可通过 https://api.seermartech.cn/v3/serp/google/events/locations 获取。示例：2840
language_codestring搜索引擎语言代码，可选。使用该字段时无需指定 language_name。默认使用目标地区的官方语言之一。该接口支持英文，常用值：en。语言列表可通过 https://api.seermartech.cn/v3/serp/wp/languages 获取。
depthinteger抓取深度，可选。表示需要解析的结果数量。默认 10，最大 700。 10 可能引发额外扣费。
priorityinteger任务优级，可选。1 = 普通优级；2 = 高优级。高优级会产生额外费用。
pingback_urlstring任务完成通知地址，可选。完成后会向该地址发送 GET 请求。支持使用 $id 和 $tag 变量，例如：http://your-server.com/pingscript?id=$id&tag=$tag。特殊字符会进行 URL 编码，例如 # 会被编码为 %23。
postback_urlstring结果推送地址，可选。任务完成后会向该地址发送 gzip 压缩的 POST 结果。支持使用 $id 和 $tag 变量。特殊字符同样会进行 URL 编码。
postback_datastring当设置 postback_url 时填。表示推送给你服务器的数据类型。可用值：advanced

附加参数 ​

字段名类型说明
location_namestring搜索引擎地区名。当未指定 location_code 或 location_coordinate 时填。使用该字段时无需再传 location_code 或 location_coordinate。示例：London,England,United Kingdom
language_namestring搜索引擎语言名称，可选。使用该字段时无需指定 language_code。示例：English
osstring设备操作系统，可选。该接口返回桌面端结果。可选值：windows、macos。默认：windows
tagstring自定义任务标识，可选，最长 255 个字符。可用于结果回传时与业务数据，返回值会出现在响应的 data 对象中。
max_crawl_pagesinteger最大抓取页数，可选。最大值：100。该参数与 depth合使用，用于控制抓取分页范围。
location_coordinatestring地理坐标，可作为地区参数使用。当未指定 location_name 或 location_code 时填。格式：latitude,longitude,radius。数据会按坐标所在国家返回。latitude 和 longitude 最多支持 7 位小数；radius 最小 199.9（毫米），最大 199999（毫米）。示例：53.476225,-2.243572,200
date_rangestring事件时间范围，可选。不传则返回事件。可选值：today、tomorrow、week、weekend、next_week、month、next_month
se_domainstring搜索引擎域名，可选。系统会根据地区自动选择域名，你也可以手动指定，例如：google.co.uk、google.com.au、google.de

响应说明 ​

接口返回 JSON 数据， tasks 数组，每个任务对应一个创建结果。

顶层字段 ​

字段名类型说明
versionstring当前 API 版本
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回显你提交的请求参数
resultarray创建任务接口中该值通常为 null

建议在生产环境中完整处理状态码与异常分支。

请求示例 ​

curl ​

bash
curl --location --request POST "https://api.seermartech.cn/v3/serp/google/events/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://www.google.co.uk/search?q=albert%20einstein&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS",
 "postback_data": "html",
 "postback_url": "https://your-server.com/postbackscript"
 }
]'

Python ​

python
import requests

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

# 请求体为 JSON 数组
payload = [
 {
 "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://www.google.co.uk/search?q=albert%20einstein&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS",
 "postback_data": "html",
 "postback_url": "https://your-server.com/postbackscript"
 }
]

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

TypeScript ​

typescript
import axios from "axios";

const postArray = [
 {
 language_code: "en",
 location_code: 2840,
 keyword: "albert einstein"
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/serp/google/events/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.20200129",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0818 sec.",
 "cost": 0.0045,
 "tasks_count": 3,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "01291721-1535-0066-0000-0a3dc84376f1",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0060 sec.",
 "cost": 0.0015,
 "result_count": 0,
 "path": [
 "v3",
 "serp",
 "google",
 "events",
 "task_post"
 ],
 "data": {
 "api": "serp",
 "function": "task_post",
 "se": "wp",
 "se_type": "v2",
 "language_code": "en",
 "location_code": 2840,
 "keyword": "albert enstein",
 "device": "desktop",
 "os": "windows"
 },
 "result": null
 },
 {
 "id": "01291721-1535-0066-0000-2e7a8bf7302c",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0050 sec.",
 "cost": 0.0015,
 "result_count": 0,
 "path": [
 "v3",
 "serp",
 "google",
 "events",
 "task_post"
 ],
 "data": {
 "api": "serp",
 "function": "task_post",
 "se": "wp",
 "se_type": "v2",
 "language_name": "English",
 "location_name": "United States",
 "keyword": "albert enstein",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag",
 "tag": "some_string_123",
 "device": "desktop",
 "os": "windows"
 },
 "result": null
 },
 {
 "id": "01291721-1535-0066-0000-ed3110168d43",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0040 sec.",
 "cost": 0.0015,
 "result_count": 0,
 "path": [
 "v3",
 "serp",
 "google",
 "events",
 "task_post"
 ],
 "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": "html",
 "postback_url": "https://your-server.com/postbackscript",
 "device": "desktop",
 "os": "windows"
 },
 "result": null
 }
 ]
}

常见状态与错误处理 ​

通用状态码 ​

状态码说明
20000请求成功
20100任务已创建
40006单次 POST 中任务数 100

更多错误码可参考 /v3/appendix/errors。

使用建议 ​

  1. 需要通过地区名称、地区代码或地理坐标三之一指定搜索地区。
  2. 该接口支持英文查询，建议明确传 language_code: "en"。
  3. 如需更快返回结果，可使用 priority: 2，但会提高单任务成本。
  4. 若你有异步处理链路，推荐使用 postback_url 或 pingback_url，减少轮询开销。
  5. depth 与 max_crawl_pages 应结合使用，无效抓取和不扣费。

实用场景 ​

  • 监控活动类搜索结果：按持续抓取 Google Events 结果，跟踪品牌活动、线下展会或热点事件的变化。
  • 分析地区活动热度：针对不同国家、城市或坐标区域提交同一，比较活动搜索结果差异，本地化运营。
  • 筛选时间窗口的事件：结合 date_range 获取今天、本周、下周或下月活动，用于活动营销排期和策划。
  • 构建事件 SERP 预警机制：通过 pingback_url 或 postback_url 异步接收任务结果，实现新活动出现后的自动通知。
  • 验证多地区 SEO 可见性：指定不同 se_domain、地区和语言参数，检查事件型在不同市场中的搜索呈现。

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

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