SeerMarTech API 文档

主题

Google Events 实时搜索高级版 ​

接口概述 ​

/v3/serp/google/events/live/advanced 用于实时获取 Google Events 搜索结果页数据，按指定和地区返回活动/演出/展会等事件结果。

该接口为实时请求接口，提交后直接返回解析结果。

注意：

  • Google Events SERP 支持英文语言环境；
  • 该接口返回桌面端结果；
  • 单次 Live SERP 调用只能 1 个任务；
  • 每分钟最多可发送 2000 次 API 调用。

请求地址

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

计费说明 ​

本接口按请求计费。

参考价约 ¥0.0320 / 次 扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

抓取深度：

  • 默认 depth=10
  • 每个最多 10 条结果的 SERP 按一次计费
  • 当 depth 大于 10 且搜索引擎返回 10 条结果时，可能产生额外扣费
  • 如果设置的 depth 高于返回结果数，差额会自动返还到账户余额

请求格式 ​

所有 POST 数据使用 UTF-8 编码的 JSON，并以数组形式提交：

json
[
 {
 "keyword": "concerts",
 "location_name": "Los Angeles,California,United States",
 "date_range": "today"
 }
]

请求参数 ​

主要参数 ​

字段名类型说明
keywordstring填。搜索，最长 700 个字符。所有 %## 会被解码，+ 会被解码为空格。如果确实需要 % 字符，请写为 %25；如果需要 + 字符，请写为 %2B。
location_codeinteger当未指定 location_name 或 location_coordinate 时填。搜索引擎地区代码。若使用该字段，则无需再传 location_name 或 location_coordinate。可通过 /v3/serp/google/events/locations 获取可用地区代码。示例：2840
language_codestring可选。搜索引擎语言代码。若使用该字段，则无需指定 language_name。默认语言通常对应所选地区的官方语言之一。可通过 /v3/serp/wp/languages 获取可用语言代码。示例：en
depthinteger可选。解析深度，即期望返回的 SERP 结果数量。默认值：10；最大值：700。

附加参数 ​

字段名类型说明
location_namestring当未指定 location_code 或 location_coordinate 时填。搜索引擎地区名。若使用该字段，则无需再传 location_code 或 location_coordinate。可通过 /v3/serp/google/events/locations 获取可用地区名称。示例：London,England,United Kingdom
language_namestring可选。搜索引擎语言名。若使用该字段，则无需指定 language_code。可通过 /v3/serp/wp/languages 获取可用语言名称。示例：English
osstring可选。设备操作系统。该接口支持桌面端结果。可选值：windows、macos。默认值：windows
tagstring可选。用户自定义任务标识，最大长度 255。可用于请求结果对账，响应中的 data 对象会原样返回该值。
max_crawl_pagesinteger可选。最多抓取的搜索结果页数，最大值：100。该参数与 depth合使用。
location_coordinatestring当未指定 location_name 或 location_code 时填。GPS 坐标，格式为 "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 数组。

顶层字段 ​

字段名类型说明
versionstringAPI 当前版本
status_codeinteger通用状态码，完整列表见 /v3/appendix/errors
status_messagestring通用状态信息，完整列表见 /v3/appendix/errors
timestring执行耗时，单位秒
costfloat请求总成本，单位 USD
tasks_countintegertasks 数组中的任务数量
tasks_errorinteger返回错误的任务数量
tasksarray任务结果数组

tasks[] 字段 ​

字段名类型说明
idstring本平台任务唯一标识，UUID 格式
status_codeinteger任务状态码，范围通常为 10000-60000，完整列表见 /v3/appendix/errors
status_messagestring任务状态信息
timestring任务执行耗时，单位秒
costfloat单任务成本，单位 USD
result_countintegerresult 数组中的数量
patharrayURL 路径
dataobject返回提交时的请求参数
resultarray结果数组

result[] 字段 ​

字段名类型说明
keywordstringPOST 中提交的。返回时 %## 会被解码，+ 会被解码为空格
typestring搜索引擎类型
se_domainstring搜索引擎域名
location_codeinteger地区代码
language_codestring语言代码；在该接口中该值为 null
check_urlstring可直接访问的搜索结果页链接
datetimestring结果抓取时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00
spellobject搜索引擎自动纠错信息
refinement_chipsobject搜索细分建议
item_typesarray当前 SERP 中出现的结果类型。该接口可能值为：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素的 XPath
itemsarray细分选项列表

refinement_chips.items[] ​

字段名类型说明
typestring素类型，固定为 refinement_chips_element
titlestring选项标题
urlstring带筛选参数的搜索 URL
domainstringSERP 中显示的域名
optionsarray进一步细分选项

refinement_chips.items[].options[] ​

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

SERP 结果项：event_item ​

items[] 中的活动结果类型为 event_item。

字段名类型说明
typestring素类型，固定为 event_item
rank_groupinteger同类型组排名
rank_absoluteinteger在整个 SERP 中的绝对排名
positionstringSERP 中的位置，可选：left、right
xpathstring素 XPath
titlestring活动标题
descriptionstring活动描述
urlstring链接
image_urlstring活动图片 URL
event_datesobject活动日期信息；如无则为 null
location_infoobject场馆/地点信息
information_and_ticketsarray附加信息与购票

event_dates 字段 ​

字段名类型说明
start_datetimestring活动开始时间。如果事件带有时区，则按 UTC 返回，格式：yyyy-mm-ddThh-mm-ss+00:00；如果无时区，则返回本地未指定时区时间，格式：yyyy-mm-ddThh-mm-ss
end_datetimestring活动结束时间。格式规则同 start_datetime
displayed_datesstringSERP 页面中展示的原始日期或日期区间文本

location_info 字段 ​

字段名类型说明
namestring活动场馆名称
addressstring活动场馆地址
urlstring指向 Google Maps 的地点链接
cidstringGoogle 定义的客户 ID，可用于本地商业数据接口
feature_idstringSERP素唯一标识

information_and_tickets[] 字段 ​

字段名类型说明
typestring素类型，固定为 information_and_tickets_element
titlestring信息或票务来源标题
descriptionstring描述信息
urlstring链接
domainstring来源域名

请求示例 ​

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"
}
data = [
 {
 "location_name": "Los Angeles,California,United States",
 "date_range": "today",
 "keyword": "concerts"
 }
]

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

TypeScript ​

typescript
import axios from "axios";

async function main {
 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);
}

main.catch(console.error);

响应示例 ​

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": [
 {
 "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": [
 {
 "se_results_count": 0,
 "items_count": 10,
 "items": [
 {
 "type": "event_item",
 "title": "USC Thornton Winds Concert",
 "description": "USC Thornton Winds Concert | Opera | Cast and Crew | Performances, schedule and tickets | View more information on Operabase",
 "url": "https://www.operabase.com/productions/usc-thornton-winds-concert-288717/en",
 "image_url": "https://api.seermartech.cn/cdn/i/11071155-1535-0139-0000-7ae0e07e250f: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": "Bovard Administration Building, 3551 Trousdale Pkwy, Los Angeles, CA",
 "url": "https://www.google.com/maps/place//data=!4m2!3m1!1s0x80c2c7e19c55535f:0x40cc3d456c923735?sa=X&ved=2ahUKEwiKhZKK-smJAxVIle4BHaz8M-UQqJACegQICRAA&hl=en&gl=US",
 "cid": "4669174282059921205",
 "feature_id": "0x80c2c7e19c55535f:0x40cc3d456c923735"
 },
 "information_and_tickets": []
 }
 ]
 }
 ]
 }
 ]
}

错误处理 ​

请基于返回的 status_code 和 status_message 设计错误处理逻辑，建议处理以下：

  • 请求参数缺失或格式错误
  • 地区、语言、日期范围不受支持 -额或频率限制触发
  • 搜索结果为空
  • 单个任务执行失败但 HTTP 请求成功

完整错误码列表参考接口：/v3/appendix/errors

使用说明补 ​

  • keyword 中的编码字符会在响应中按规则解码；
  • language_code 在该接口结果中通常为 null，即使请求时使用英文环境；
  • se_results_count 对此类结果通常返回 0，因为搜索引擎不会展示总结果数；
  • position 可用于判断结果位于页面左侧还是右侧区域；
  • location_info.cid 与 feature_id 可作为场馆实体标识，适合做地点聚合、评论或线下活动库构建。

实用场景 ​

  • 监控城市活动热度：按城市与日期范围抓取演出、展览、音乐会等事件结果，帮助团队快速发现本地热点活动主题。
  • 挖掘票务与活动落地页：提取 information_and_tickets、url 和 domain，识别主要票务平台与活动分发渠道，竞品流量分析。
  • 构建本地活动数据库：利用 title、event_dates、location_info 等字段沉淀结构化活动数据，用于本地生活、文或票务聚合产品。
  • 分析搜索结果展示规律：结合 rank_absolute、position、refinement_chips 观察不同下的活动展示结构，优化活动 SEO 与专题策划。
  • 场馆实体与口碑数据：基于 location_info.cid 和 feature_id 识别场馆，进一步连接评论、地图与本地商户数据，评估活动举办地影响力。

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

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