设置 Google Events SERP 任务

POST /v3/serp/google/events/task_post

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

/v3/serp/google/events/task_post

用于根据指定和地理位置创建 Google Events SERP 任务，获取 Google 活动搜索结果。Google Events SERP API 支持英语。

任务支持两种执行优级：

1：普通优级，默认值
2：高优级，执行速度更快，但费用更高

请求说明

请求体使用 UTF-8 编码的 JSON 格式。
请求体是 JSON 数组，每个数组代表一个任务。
单次请求最多提交 100 个任务。平台限流以认证说明中的 30/60/120 次/分钟规则为准。
单次请求 100 个任务时，出部分将返回错误码 40006。
创建任务后，可通过返回的任务 id 查询结果。
也可以通过 pingback_url 或 postback_url 接收任务完成通知或结果。

如果回调服务器在 10 秒未响应，连接将因时中止，任务会转“已就绪任务”列表。错误码和错误信息取决于回调服务器。

计费说明

创建任务时即产生费用。深度 10 时，如果搜索引擎返回 10 条结果，可能产生额外费用；如果返回结果数少于指定的 depth，差额将自动退还到账户余额。

高优级任务会额外计费。

参考价示例：

普通任务：参考价约 ¥0.0108 / 次
10 条结果的 SERP：参考价约 ¥0.0324 / 页

以上价格为示例换算值，扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数

主要参数

字段	类型	说明
`keyword`	string	填。要查询的，最多 700 个字符。所有 `%##` 编码会被解码，字符 `+` 会被解码为空格。如果中需要使用 `%`，请写为 `%25`；需要使用 `+`，请写为 `%2B`。
`location_code`	integer	搜索引擎位置代码。当未指定 `location_name` 或 `location_coordinate` 时填。使用此字段后，无需再指定 `location_name` 或 `location_coordinate`。可通过 `/v3/serp/google/events/locations` 获取可用位置代码。例如：`2840`。
`language_code`	string	搜索引擎语言代码，可选。使用此字段后，无需再指定 `language_name`。默认使用指定位置对应的官方本地语言。可通过 `/v3/serp/wp/languages` 获取可用语言代码。例如：`en`。
`depth`	integer	SERP 解析深度，即最多获取的结果数量。默认值为 `10`，最大值为 `700`。
`priority`	integer	任务优级。`1` 表示普通优级，默认值；`2` 表示高优级。
`pingback_url`	string	任务完成通知地址。任务完成后，本平台会向该地址发送 GET 请求。URL 中可使用 `$id` 和 `$tag` 占位符，本平台发送请求前会替换为任务 ID 和经过 URL 编码的标签值。例如：`https://your-server.com/pingscript?id=$id&tag=$tag`。特殊字符会进行 URL 编码，例如 `#` 会编码为 `%23`。
`postback_url`	string	任务结果接收地址。任务完成后，本平台会向该地址发送 POST 请求，并以 gzip 格式压缩结果。URL 中可使用 `$id` 和 `$tag` 占位符。例如：`https://your-server.com/postbackscript?id=$id&tag=$tag`。
`postback_data`	string	使用 `postback_url` 时填。指定发送到服务器的数据类型。目前支持：`advanced`。

附加参数

字段	类型	说明
`location_name`	string	搜索引擎位置的完整名称。当未指定 `location_code` 或 `location_coordinate` 时填。使用此字段后，无需再指定另外两个位置字段。例如：`London,England,United Kingdom`。
`language_name`	string	搜索引擎语言的完整名称，可选。使用此字段后，无需再指定 `language_code`。例如：`English`。
`os`	string	设备操作系统。此接口提供桌面端结果。可选值：`windows`、`macos`。默认值：`windows`。
`tag`	string	用户自定义任务标识，最多 255 个字符。可用于识别任务并与结果进行匹。提交的值会出现在响应的 `data` 对象中。
`max_crawl_pages`	integer	最多抓取的搜索结果页数，最大值为 `100`。该参数与 `depth`合使用。
`location_coordinate`	string	位置 GPS 坐标。未指定 `location_name` 或 `location_code` 时填。格式为 `"纬度,经度,半径"`，例如：`53.476225,-2.243572,200`。纬度和经度最多支持 7 位小数；半径最小值为 `199.9` 米，最大值为 `199999` 米。返回数据对应于坐标所属国家。
`date_range`	string	活动日期范围。未指定时返回所有活动。可选值：`today`、`tomorrow`、`week`、`weekend`、`next_week`、`month`、`next_month`。
`se_domain`	string	搜索引擎域名。平台会根据位置自动选择域名，也可以手动指定，例如：`google.co.uk`、`google.com.au`、`google.de`。

> location_code、location_name 和 location_coordinate 三至少指定一个，且通常只需指定一个。
> language_code 与 language_name 二选一即可。

请求示例

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",
      "date_range": "month",
      "depth": 10
    }
  ]'

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 数组
post_data = [
    {
        "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"
        ),
    },
    {
        "keyword": "albert einstein",
        "location_code": 2840,
        "language_code": "en",
        "postback_data": "advanced",
        "postback_url": "https://your-server.com/postbackscript",
    },
]

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

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

TypeScript

typescript

import axios from "axios";

const postData = [
  {
    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",
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/serp/google/events/task_post",
    postData,
    {
      headers: {
        Authorization: "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
      },
    }
  )
  .then((response) => {
    // 处理任务创建结果
    console.log(response.data);
  })
  .catch((error) => {
    console.error("请求失败：", error.response?.data || error.message);
  });

响应说明

接口返回 JSON 数据 tasks 数组每个已提交任务的信息。

顶层响应字段

字段	类型	说明
`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` 数组中返回错误的任务数量。
`tasks`	array	任务信息数组。

任务字段

字段	类型	说明
`id`	string	任务唯一标识，UUID 格式。可用于后续获取任务结果。
`status_code`	integer	任务状态码，通常在 `10000` 至 `60000` 范围。
`status_message`	string	任务状态说明。
`time`	string	任务执行耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`result_count`	integer	`result` 数组中的数量。任务创建接口通常为 `0`。
`path`	array	任务结果路径。
`data`	object	创建任务时提交的参数及平台补的任务信息。
`result`	array \| null	任务结果数组。任务创建成功后通常为 `null`，需要通过任务结果接口或回调获取最终数据。

响应示例

json

{
  "version": "0.1.20200129",
  "status_code": 20000,
  "status_message": "请求成功。",
  "time": "0.0818 sec.",
  "cost": 0.0324,
  "tasks_count": 3,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01291721-1535-0066-0000-2e7a8bf7302c",
      "status_code": 20100,
      "status_message": "任务已创建。",
      "time": "0.0050 sec.",
      "cost": 0.0108,
      "result_count": 0,
      "path": [],
      "data": {
        "api": "serp",
        "function": "task_post",
        "se": "google",
        "se_type": "events",
        "language_code": "en",
        "location_code": 2840,
        "keyword": "albert einstein",
        "device": "desktop",
        "os": "windows"
      },
      "result": null
    },
    {
      "id": "01291721-1535-0066-0000-ed3110168d43",
      "status_code": 20100,
      "status_message": "任务已创建。",
      "time": "0.0040 sec.",
      "cost": 0.0108,
      "result_count": 0,
      "path": [],
      "data": {
        "api": "serp",
        "function": "task_post",
        "se": "google",
        "se_type": "events",
        "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": "01291721-1535-0066-0000-ed3110168d43",
      "status_code": 20100,
      "status_message": "任务已创建。",
      "time": "0.0040 sec.",
      "cost": 0.0108,
      "result_count": 0,
      "path": [],
      "data": {
        "api": "serp",
        "function": "task_post",
        "se": "google",
        "se_type": "events",
        "keyword": "albert einstein",
        "location_code": 2840,
        "language_code": "en",
        "postback_data": "advanced",
        "postback_url": "https://your-server.com/postbackscript",
        "device": "desktop",
        "os": "windows"
      },
      "result": null
    }
  ]
}

错误处理

请根据顶层 status_code、status_message 以及每个任务的 status_code、status_message 分别处理请求级和任务级错误。

常见：

单次提交任务数 100：出限制的任务返回 40006。 -填参数缺失：任务创建失败。
位置或语言参数组合冲突：任务创建失败。
回调服务器未在 10 秒响应：回调连接时，任务转已就绪任务列表。

完整错误码和状态说明请参考错误码文档。

实用场景

监控指定城市的活动搜索结果：按、位置和日期范围批量采集活动信息，支持本地 SEO 和活动推广策略制定。
分析节假日或周末活动：使用 date_range 对比不同时间窗口的活动结果，评估季节性搜索需求和布局机会。
批量追踪竞争对手活动排名：为多个品牌、场馆或活动创建 SERP 任务，发现竞争对手在 Google Events 中的变化。
构建活动数据回调流程： postback_url 或 pingback_url，在任务完成后自动触发数据库、报表更新和告警。
比较不同地区的活动供给：通过位置代码、位置名称或 GPS 坐标采集多个区域的活动结果，为区域市场拓展和本地化 SEO 提供依据。

设置 Google Events SERP 任务 ​

请求说明 ​

计费说明 ​

请求参数 ​

主要参数 ​

附加参数 ​

请求示例 ​

curl ​

Python ​

TypeScript ​

响应说明 ​

顶层响应字段 ​

任务字段 ​

响应示例 ​

错误处理 ​

实用场景 ​