SERP 可用端点列表

接口说明

GET /v3/serp/endpoints

该接口用于获取当前可用于创建 SERP API 任务的端点列表。调用成功后，响应中会返回一个 tasks 数组本次请求的任务信息，以及 result 中的可用端点单。

计费说明： 调用本接口不收费。扣费以响应头 X-SeerMarTech-Charge-CNY 为准；该接口通常返回 0。

请求地址

https://api.seermartech.cn/v3/serp/endpoints

请求方式

GET

认证方式

请在请求头中使用 Bearer Token：

Authorization: Bearer smt_live_YOUR_KEY
Content-Type: application/json

响应结构

接口返回 JSON 编码数据，顶层任务执行状态及结果信息。

顶层字段

字段名	类型	说明
version	string	API 当前版本号
status_code	integer	接口整体状态码
status_message	string	接口整体状态信息
time	string	执行耗时，单位为秒
cost	float	本次请求总费用，单位 USD；本接口通常为 0
tasks_count	integer	tasks 数组中的任务数量
tasks_error	integer	tasks 数组中返回错误的任务数量
tasks	array	任务结果数组

状态码与通用消息说明可参考 /v3/appendix/errors。

tasks[] 字段

字段名	类型	说明
id	string	任务唯一标识，UUID 格式
post_id	string	你在系统中定义的自定义任务标识；如未传，可能由系统分
status_code	integer	任务级状态码，范围通常为 10000-60000
status_message	string	任务级状态信息
time	string	该任务执行耗时，单位为秒
cost	float	该任务费用，单位 USD
result_count	integer	result 数组中的数量
path	array	当前请求的 URL 路径拆分结果
data	array / object	本次 API 调用中使用的数据参数
result	array	可用于创建 SERP 任务的端点列表

请求示例

cURL

curl --location --request GET "https://api.seermartech.cn/v3/serp/endpoints" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json"

Python

import requests

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

response = requests.get(url, headers=headers)
result = response.json

# 可按整体状态码判断是否成功
if result.get("status_code") == 20000:
 print(result)
else:
 print(f'error. Code: {result.get("status_code")} Message: {result.get("status_message")}')

TypeScript

import axios from "axios";

axios({
 method: "get",
 url: "https://api.seermartech.cn/v3/serp/endpoints",
 headers: {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 }
}).then(function (response) {
 // 响应数据
 console.log(response.data);
}).catch(function (error) {
 console.log(error);
});

响应示例

{
 "version": "3.20191128",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.1118 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "serp",
 "function": "map"
 },
 "result": []
 }
 ]
}

说明：示例中的响应片段存在格式截断，这里按标准 JSON 结构整理展示。返回以接口响应为准。

返回结果说明

result 数组中会列出当前可用于创建 SERP API 任务的端点。你可以调用本接口动态获取可用能力，再根据返回的端点路径选择的任务创建接口。

这在以下场景有用：

• 需要自动发现平台 API 当前支持的 SERP 数据源
• 需要在多地区、多搜索引擎或多类型 SERP 之间动态切换
• 需要在系统初始化时同步可用端点，写死路径

错误处理

当请求或任务执行失败时，可重点检查以下字段：

字段名	说明
status_code	接口整体状态码
status_message	接口整体错误或提示信息
tasks_error	出错任务数
tasks[].status_code	单个任务状态码
tasks[].status_message	单个任务错误信息

常见排查方向：

• Bearer Token 是否正确
• 请求地址是否为 /v3/serp/endpoints
• 请求头中是否 Authorization 与 Content-Type
• 账号是否备对应 API 访问权限

完整错误码可参考 /v3/appendix/errors。

实用场景

• 发现可用 SERP 端点：在程序启动或定时任务中拉取可用端点列表，自动同步平台能力，减少人工维护路径。
• 校验任务投递目标：在创建 SERP 采集任务前检查目标端点是否存在，降低因路径失效导致的请求失败率。
• 构建动态产品页：将返回的端点列表展示到运营后台，便于产品或运营人员按能力开采集方案。
• 适多引擎采集策略：基于可用端点结果动态选择不同搜索引擎或 SERP 类型，提高采集系统容性。
• 监控平台能力变更：定期比对端点列表变化，及时发现新增、调整或下线的 SERP 能力，接口升级与回归测试。