SeerMarTech API 文档

主题

Google Events SERP 实时高级接口 ​

POST /v3/serp/google/events/live/advanced

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

POST https://api.seermartech.cn/v3/serp/google/events/live/advanced

Google Events SERP 实时高级接口可根据指定和地理位置，实时获取 Google Events 搜索结果。当前接口支持英语语言环境。

每次请求只能提交 1 个任务。平台限流以认证说明中的 30/60/120 次/分钟规则为准。所有 POST 数据使用 UTF-8 编码的 JSON 格式，并将任务参数放 JSON 数组中。

计费说明 ​

接口按请求计费，depth 大于 10 时，如果搜索引擎返回 10 条结果，可能产生额外费用。

  • 每个最多 10 条结果的 SERP 页面单独计费。
  • 如果 depth 高于响应中的结果数量，未使用部分的费用会自动退还到账户余额。
  • 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数 ​

主要参数 ​

参数类型填说明
keywordstring是搜索，最多 700 个字符。参数中的 %## 编码会被解码，字符 + 会被解码为空格。如果中需要使用百分号 %，请编码为 %25；如果需要使用加号 +，请编码为 %2B。
location_codeinteger条件填搜索引擎地理位置代码。如果未指定 location_name 或 location_coordinate，则填写此参数。填写后无需再填写另外两个位置参数。可通过 https://api.seermartech.cn/v3/serp/google/events/locations 获取可用位置代码。例如：2840。
language_codestring否搜索引擎语言代码。填写后无需再填写 language_name。默认使用指定位置对应的官方本地语言。可通过 https://api.seermartech.cn/v3/serp/wp/languages 获取可用语言代码。例如：en。
depthinteger否SERP 解析深度，即需要获取的结果数量。默认值为 10，最大值为 200。
location_namestring条件填搜索引擎地理位置的完整名称。如果未指定 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条件填地理位置 GPS 坐标，格式为 纬度,经度,半径。如果未指定 location_name 或 location_code，则填写此参数。填写后无需再填写另外两个位置参数。数据将坐标所属国家返回。纬度和经度最多支持 7 位小数；半径最小值为 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。

> location_code、location_name 和 location_coordinate 三至少指定一个，且不能同时指定多个。

请求示例 ​

cURL ​

bash
curl --location --request POST \
  "https://api.seermartech.cn/v3/serp/google/events/live/advanced" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "location_name": "Los Angeles,California,United States",
      "date_range": "today",
      "keyword": "concerts"
    }
  ]'

Python ​

python
import requests

url = "https://api.seermartech.cn/v3/serp/google/events/live/advanced"

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

# 每次请求只能提交一个任务
payload = [
    {
        "location_name": "Los Angeles,California,United States",
        "date_range": "today",
        "keyword": "concerts",
    }
]

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

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

TypeScript ​

typescript
import axios from "axios";

const response = await axios.post(
  "https://api.seermartech.cn/v3/serp/google/events/live/advanced",
  [
    {
      location_name: "Los Angeles,California,United States",
      date_range: "today",
      keyword: "concerts",
    },
  ],
  {
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
  }
);

// 处理响应数据
console.log(response.data);

响应结构 ​

接口返回 JSON 数据，顶层 tasks 数组。

顶层字段 ​

字段类型说明
versionstring当前 API 版本。
status_codeinteger通用状态码。成功通常为 20000。
status_messagestring通用状态说明。
timestring请求执行耗时，单位为秒。
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
tasks_countintegertasks 数组中的任务总数。
tasks_errorintegertasks 数组中返回错误的任务数。
tasksarray任务结果数组。

tasks 字段 ​

字段类型说明
idstring平台中的任务唯一标识，UUID 格式。
status_codeinteger任务状态码，通常在 10000 至 60000 范围。
status_messagestring任务状态说明。
timestring任务执行耗时，单位为秒。
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
result_countintegerresult 数组中的数量。
patharray请求 URL 路径。
dataobject创建任务时提交的参数。
resultarraySERP 结果数组。

result 基础字段 ​

字段类型说明
keywordstring请求中的。返回时会对 %## 进行解码，字符 + 会被解码为空格。
typestring请求中的搜索引擎类型。
se_domainstring请求中使用的搜索引擎域名。
location_codeinteger地理位置代码。
language_codestring / null语言代码。Google Events SERP 当前场景下可能返回 null。
check_urlstring搜索引擎结果页的直接 URL。
datetimestring获取结果的时间，UTC 格式为 yyyy-mm-dd hh-mm-ss +00:00。例如：2019-11-15 12:57:46 +00:00。
spellobject搜索引擎自动纠错信息。
refinement_chipsobject搜索细化选项。
item_typesarraySERP 中发现的结果类型。当前可能 event_item。
se_results_countintegerSERP 中的结果总数。本接口通常返回 0，因为搜索引擎不会提供总结果数。
items_countintegeritems 数组中返回的结果数量。
itemsarraySERP 结果项数组。

spell 字段 ​

当搜索引擎对进行自动纠错并使用纠正后的返回结果时，将提供此对象。

字段类型说明
keywordstring自动纠正后的，结果将基于该提供。
typestring自动纠错类型。可选值：did_you_mean、showing_results_for、no_results_found_for、including_results_for。

refinement_chips 字段 ​

字段类型说明
typestring素类型，固定为 refinement_chips。
xpathstring素在 SERP 中的 XPath。
itemsarray搜索细化项数组。
optionsarray进一步的搜索细化选项。

items 中的字段：

字段类型说明
typestring素类型，固定为 refinement_chips_element。
titlestring素标题。
urlstring带细化参数的搜索 URL。
domainstringSERP 中的域名。

options 中的字段：

字段类型说明
typestring素类型，固定为 refinement_chips_option。
titlestring选项标题。
urlstring带细化参数的搜索 URL。
domainstringSERP 中的域名。

event_item 活动结果字段 ​

items 数组中的活动结果类型为 event_item，字段如下：

字段类型说明
typestring素类型，固定为 event_item。
rank_groupinteger分组排名。在类型相同的组计算；不同类型之间的位置不会计此字段。
rank_absoluteintegerSERP 中的绝对排名，即所有中的位置。
positionstring素在 SERP 中的对齐位置。可选值：left、right。
xpathstring素在 SERP 中的 XPath。
titlestring搜索结果标题。
descriptionstring搜索结果描述。
urlstring活动页 URL。
image_urlstring活动结果中的图片 URL。
event_datesobject / null活动举办日期和时间。如果没有日期信息，则为 null。
location_infoobject活动场地信息。
feature_idstringSERP素的唯一标识。
information_and_ticketsarray信息和购票选项。

event_dates 字段 ​

字段类型说明
start_datetimestring活动开始日期和时间。如果活动时区，使用 UTC 格式：yyyy-mm-ddThh-mm-ss+00:00；如果未指定时区，则返回未标明时区的本地时间，格式为 yyyy-mm-ddThh-mm-ss。
end_datetimestring / null活动结束日期和时间，格式规则与 start_datetime 相同。
displayed_datesstringSERP 页面中展示的日期或日期范围。

示例：

text
2024-11-07T16:00:00
2024-11-07T22:00:00+00:00

location_info 字段 ​

字段类型说明
namestring活动场地名称。
addressstring活动场地地址。
urlstring活动场地在地图服务中的 URL。
cidstring地点标识。可结合 Google Reviews 接口获取评论列表。
feature_idstringSERP 中该地点的唯一标识。

information_and_tickets 字段 ​

字段类型说明
typestring素类型，固定为 information_and_tickets_element。
titlestring信息或购票选项标题。
descriptionstring信息或购票选项描述。
urlstring信息或购票 URL。
domainstringSERP 中的域名。

响应示例 ​

json
{
  "version": "0.1.20241101",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "17.1653 sec.",
  "cost": 0.002,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "17.1653 sec.",
      "cost": 0.002,
      "result_count": 1,
      "data": {
        "api": "serp",
        "function": "live",
        "se": "google",
        "se_type": "events",
        "language_code": "en",
        "location_name": "Los Angeles,California,United States",
        "keyword": "concerts",
        "device": "desktop",
        "os": "windows",
        "date_range": "today"
      },
      "result": [
        {
          "keyword": "concerts",
          "type": "events",
          "se_domain": "google.com",
          "location_code": 2840,
          "language_code": null,
          "check_url": "https://www.google.com/search?q=concerts",
          "datetime": "2024-11-07 12:57:46 +00:00",
          "spell": null,
          "refinement_chips": null,
          "item_types": [
            "event_item"
          ],
          "se_results_count": 0,
          "items_count": 1,
          "items": [
            {
              "type": "event_item",
              "rank_group": 1,
              "rank_absolute": 1,
              "position": "right",
              "xpath": "/html/body/div/div/div/div/div/div/div/ul/li",
              "title": "USC Thornton Winds Concert",
              "description": "USC Thornton Winds Concert | Performances, schedule and tickets",
              "url": "https://www.example.com/event",
              "image_url": "https://api.seermartech.cn/cdn/i/example:0",
              "event_dates": {
                "start_datetime": "2024-11-07T16:00:00",
                "end_datetime": null,
                "displayed_dates": "Thu, Nov 7, 4 PM"
              },
              "location_info": {
                "name": "Bovard Auditorium",
                "address": "Los Angeles, CA",
                "url": "https://www.google.com/maps/",
                "cid": "4669174282059921205",
                "feature_id": "0x80c2c7e19c55535f:0x40cc3d456c923735"
              },
              "feature_id": "0x80c2c7e19c55535f:0x40cc3d456c923735",
              "information_and_tickets": []
            }
          ]
        }
      ]
    }
  ]
}

状态码与异常处理 ​

请根据顶层 status_code 和任务级 tasks[].status_code 判断请求及任务是否成功。建议在业务系统中同时处理以下：

  • HTTP 请求失败；
  • 顶层 status_code 非 20000；
  • tasks_error 大于 0；
  • 单个任务的 status_code 非 20000；
  • result 为空或活动字段缺失。

完整错误码列表请参考：

/v3/appendix/errors

实用场景 ​

  • 监控本地活动搜索结果：按城市、和日期范围抓取活动 SERP，评估活动类页面在目标地区的。
  • 发现活动选题：提取活动标题、描述、时间和场地信息，为、票务或本地生活网站生成选题。
  • 分析竞品活动覆盖：对比不同城市和下的活动结果来源，识别竞争网站的排名位置和流量。
  • 构建活动聚合数据：整合活动、举办地点、日期和购票链接，搭建面向用户的活动日历或推荐页面。
  • 跟踪活动搜索趋势：定期执行相同和位置查询，比较活动结果数量、排名及来源变化，本地 SEO 策略调整。

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

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