SeerMarTech API 文档

主题

获取 Seznam 自然搜索常规结果（按任务 ID） ​

接口说明 ​

用于根据任务 ID 获取 Seznam 自然搜索（Organic）SERP 的常规结果。

请求方式： GET请求路径：

/v3/serp/seznam/organic/task_get/regular/$id

完整示例：

https://api.seermartech.cn/v3/serp/seznam/organic/task_get/regular/$id

计费说明 ​

该接口本身不会重复计费。在创建任务时扣费，任务结果在后续 30 天可查询。

如果异步任务有费用，请以任务提交时的扣费为准；扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

路径参数 ​

字段类型说明
idstring任务唯一标识，UUID 格式。可在任务创建后的 30 天 随时用于获取结果。

沙箱调试 ​

可使用以下沙箱地址查看该端点支持返回的字段结构，字段值为模拟数据，不会产生费用：

https://api.seermartech.cn/v3/serp/seznam/organic/task_get/regular/00000000-0000-0000-0000-000000000000

沙箱响应会本接口可返回的所有 Seznam Organic Regular 结果项及示例字段。

返回结构 ​

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

顶层字段 ​

字段类型说明
versionstring当前 API 版本号
status_codeinteger通用状态码，完整错误码请参考错误码文档
status_messagestring通用提示信息
timestring执行耗时，单位秒
costfloat本次请求涉及任务的总费用
tasks_countintegertasks 数组中的任务数量
tasks_errorintegertasks 数组中返回错误的任务数量
tasksarray任务结果列表

建议在接时对 status_code、status_message 以及任务级错误进行完整异常处理。

tasks[] 字段 ​

字段类型说明
idstring任务 ID，UUID 格式
status_codeinteger任务状态码，范围通常为 10000–60000
status_messagestring任务状态说明
timestring任务执行耗时，单位秒
costfloat当前任务费用
result_countintegerresult 数组中的数量
patharray请求路径
dataobject与创建任务时传参数一致的数据对象
resultarray获取结果列表

tasks[].result[] 字段 ​

字段类型说明
keywordstring创建任务时的；返回时会解码 %##，+ 会还原为空格
typestring创建任务时的搜索类型
se_domainstring创建任务时的搜索引擎域名
location_codeinteger创建任务时的位置编码
language_codestring创建任务时的语言编码
check_urlstring搜索结果直达链接，可用于人工核验结果准确性
datetimestring结果抓取时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00
spellobject搜索引擎自动纠错信息
refinement_chipsobject搜索细分建议，当前固定为 null
item_typesarray当前 SERP 中出现的结果类型集合
se_results_countintegerSERP 中的结果总量
pages_countinteger已抓取的结果页数量
items_countintegeritems 数组中的结果数量
itemsarray自然搜索结果列表

spell 字段 ​

当搜索引擎对进行了自动纠错时，会返回以下信息：

字段类型说明
keywordstring搜索引擎纠正后的
typestring纠错类型

spell.type 可选值：

  • did_you_mean
  • showing_results_for
  • no_results_found_for
  • including_results_for

item_types 说明 ​

item_types 表示该次 SERP 中出现过的结果类型，可能：

  • images
  • local_pack
  • organic
  • related_searches
  • top_stories
  • featured_snippet
  • video

注意：本接口返回 organic 类型的数据。 如果需要获取该 SERP 中的结果类型（ SERP feature、富结果等），请使用对应的 Advanced 端点。

items[] 自然结果字段 ​

items 数组中的每个均为一个 organic 搜索结果。

字段类型说明
typestring结果类型，固定为 organic
rank_groupinteger分组排名；只在相同 type 的结果排序
rank_absoluteinteger绝对排名；在 SERP素中的位置
pageinteger所在搜索结果页码
domainstring结果域名
titlestring结果标题
descriptionstring结果摘要
urlstring结果链接
breadcrumbstring面屑路径

调用方式 ​

通常流程如下：

  1. 通过任务创建接口提交 Seznam Organic 查询任务；
  2. 可通过 /v3/serp/seznam/organic/tasks_ready 获取已完成任务；
  3. 再使用本接口按任务 ID 获取结果。

请求示例 ​

cURL ​

bash
id="09171517-0696-0242-0000-a96bc1ad0bce"

curl --location --request GET "https://api.seermartech.cn/v3/serp/seznam/organic/task_get/regular/${id}" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json"

Python ​

python
import requests

task_id = "09171517-0696-0242-0000-a96bc1ad0bce"

url = f"https://api.seermartech.cn/v3/serp/seznam/organic/task_get/regular/{task_id}"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)
print(response.status_code)
print(response.json)

TypeScript ​

typescript
import axios from "axios";

const taskId = "02201650-1073-0066-2000-1d132bb28897";

axios({
 method: "get",
 url: `https://api.seermartech.cn/v3/serp/seznam/organic/task_get/regular/${taskId}`,
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json",
 },
})
 .then((response) => {
 // 输出返回结果
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error);
 });

查询已完成任务后批量获取结果 ​

如果你希望获取已完成任务列表，再批量查询每个任务的结果，可调用：

GET /v3/serp/seznam/organic/tasks_ready

随后对返回的任务 ID 或结果地址逐个请求本接口。

Python 示例 ​

python
import requests

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

# 第一步：获取已完成任务
ready_url = "https://api.seermartech.cn/v3/serp/seznam/organic/tasks_ready"
ready_resp = requests.get(ready_url, headers=headers).json

results = []

if ready_resp.get("status_code") == 20000:
 for task_group in ready_resp.get("tasks", []):
 for task_info in task_group.get("result", []) or []:
 task_id = task_info.get("id")
 if task_id:
 # 第二步：按任务 ID 获取结果
 task_url = f"https://api.seermartech.cn/v3/serp/seznam/organic/task_get/regular/{task_id}"
 task_resp = requests.get(task_url, headers=headers).json
 results.append(task_resp)

print(results)

响应示例 ​

json
{
 "version": "0.1.20220428",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.1045 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "serp",
 "function": "task_get",
 "se": "seznam",
 "se_type": "organic",
 "language_code": "cs",
 "location_code": 2203,
 "keyword": "cnn news",
 "tag": "some_string_123",
 "postback_url": "https://your-server.com/postbackscript.php",
 "postback_data": "html",
 "calculate_rectangles": true,
 "device": "desktop",
 "os": "windows"
 },
 "result": [
 {
 "se_results_count": 0,
 "pages_count": 1,
 "items_count": 10,
 "items": []
 }
 ]
 }
 ]
}

状态码与异常处理 ​

  • 顶层 status_code = 20000 表示请求成功；
  • 任务级 tasks[].status_code 用于判断单个任务是否成功；
  • 当 tasks[].status_code >= 40000、result 为空或 tasks_error > 0 时，建议按失败处理；
  • 结果查询支持任务创建后 30 天 使用。

注意事项 ​

  1. 本接口只返回 Seznam 自然结果的常规字段。
  2. 即使 item_types 中出现了图片、视频、精选摘要等类型，本接口也不会返回这些类型的详细数据。
  3. 若被搜索引擎自动修正，返回结果可能对应 spell.keyword。
  4. 可通过 check_url 对搜索引擎页面进行人工验证。
  5. 若需更丰富的 SERP 结构数据，请改用对应 Advanced 端点。

实用场景 ​

  • 查询自然排名：按任务 ID 拉取 Seznam 自然结果，定位目标域名在 SERP 中的位置，用于排名监控与日报生成。
  • 核验捷语市场搜索表现：结合 language_code、location_code 和 check_url，验证特定地区与语言下的真实搜索结果，提升 SEO 研判准确性。
  • 监控标题与摘要展现：提取 title、description、breadcrumb，分析页面在搜索结果中的展示方式，为 SEO 文案优化提供依据。
  • 识别纠错影响：利用 spell 字段判断搜索引擎是否改写用户查询，将纠错后的结果误判为原词排名。
  • 批量回收异步任务结果：通过 tasks_ready 获取完成任务，再统一调用本接口获取结果，适合搭建高并发 SERP 数据采集流程。

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

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