获取 Seznam 自然搜索高级结果（按任务 ID）

接口说明

通过任务 ID 获取 Seznam 自然搜索（Organic）SERP 的高级结果。

请求方式

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

说明：

• $id：任务唯一标识，UUID 格式
• 任务结果在任务创建后的 30 天 可随时重复获取

计费说明

本接口本身不会重复扣费。在创建任务时计费，任务创建后 30 天获取结果。

由于平台按任务下发时计费，获取结果接口通常返回 cost: 0。 扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

路径参数

字段	类型	说明
id	string	任务 ID，UUID 格式。在本平台系统中唯一，可在 30 天用于查询该任务结果。

沙箱调试

可以使用以下沙箱地址查看本端点支持的所有 SERP素与字段结构，返回值为模拟数据，不计费：

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

适合用于：

• 提前适 items 中不同 type 的解析逻辑
• 验证字段结构是否覆盖 organic、local_pack、images、video、shopping、featured_snippet 等结果类型
• 联调前端展示或数据库映射

返回结果结构

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

顶层字段

字段	类型	说明
version	string	当前 API 版本
status_code	integer	整体状态码
status_message	string	整体状态信息
time	string	请求执行耗时，单位秒
cost	float	本次请求成本，单位 USD；业务请以该字段为准
tasks_count	integer	tasks 数组中的任务数
tasks_error	integer	返回错误的任务数
tasks	array	任务结果数组

建议在接时做好异常状态与错误码处理。

tasks[] 字段

字段	类型	说明
id	string	任务 ID，UUID 格式
status_code	integer	任务状态码，范围通常在 10000-60000
status_message	string	任务状态信息
time	string	任务执行耗时
cost	float	任务成本，单位 USD
result_count	integer	result 数组数
path	array	请求路径
data	object	与创建任务时一致的请求参数
result	array	结果数组

result[] 通用字段

字段	类型	说明
keyword	string	查询。返回时会对 %## 编码做解码，+ 会被还原为空格
type	string	创建任务时指定的搜索类型
se_domain	string	创建任务时指定的搜索引擎域名
location_code	integer	地区编码
language_code	string	语言编码
check_url	string	搜索结果直达链接，可用于人工校验结果准确性
datetime	string	抓取结果时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00
spell	object	搜索引擎自动纠错信息
refinement_chips	object	搜索细分标签；该端点中通常为 null
item_types	array	当前 SERP 中出现的结果类型
se_results_count	integer	SERP 结果总数
pages_count	integer	抓取到的结果页数
items_count	integer	items 数组中的数
items	array	SERP 中解析出的结果项

spell 字段说明

字段	类型	说明
keyword	string	搜索引擎纠正后的
type	string	自动纠错类型

spell.type 可能值：

• did_you_mean
• showing_results_for
• no_results_found_for
• including_results_for

item_types 可能值

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

---

SERP素字段说明

不同 items[].type 对应的字段不同。以下为主要类型说明。

1）organic 自然结果

字段	类型	说明
type	string	固定为 organic
rank_group	integer	同类型分组排名
rank_absolute	integer	SERP局绝对排名
page	integer	所在结果页码
position	string	展示位置：left / right
xpath	string	该的 XPath
domain	string	结果域名
title	string	标题
url	string	结果链接
cache_url	string	页面缓存地址
breadcrumb	string	面屑路径
is_image	boolean	是否带图片
is_video	boolean	是否带视频
is_featured_snippet	boolean	是否为精选摘要
is_malicious	boolean	是否被标记为恶意页面
is_web_story	boolean	是否为 Web Story
description	string	摘要描述
pre_snippet	string	摘要前附加信息
extended_snippet	string	摘要后附加信息
amp_version	boolean	是否存在 AMP 页面
rating	object	评分信息
highlighted	array	摘要中加粗高亮的词
links	array	站点子链接（sitelinks），无则为 null
faq	object	FAQ 扩展，无则为 null
extended_people_also_search	array	扩展搜索
timestamp	string	发布时间，UTC 格式
rectangle	object	结果区块坐标与尺寸；对 Seznam 当前通常为 null

organic.rating

字段	类型	说明
rating_type	string	评分类型，可能为 Max5、Percents、CustomMax
value	integer	评分值
votes_count	integer	评价数量
rating_max	integer	当前评分体系最大值

organic.links[]

字段	类型	说明
type	string	固定为 link_element
title	string	子链接标题
description	string	子链接描述
url	string	子链接地址

organic.faq

字段	类型	说明
type	string	固定为 faq_box
items	array	FAQ 条目

organic.faq.items[]

字段	类型	说明
type	string	固定为 faq_box_element
title	string	问题标题
description	string	下拉答案
links	array	FAQ链接

organic.faq.items[].links[]

字段	类型	说明
type	string	固定为 link_element
title	string	锚文本
url	string	链接地址

rectangle 说明

rectangle含 SERP 片段的坐标与像素尺寸：

字段	类型	说明
x	integer / float	左上角 x 坐标
y	integer / float	左上角 y 坐标
width	integer / float	宽度（像素）
height	integer / float	高度（像素）

注意：Seznam 当前创建任务时尚不支持 calculate_rectangles，因此该搜索引擎下 rectangle 通常始终为 null。

---

2）related_searches 搜索

字段	类型	说明
type	string	固定为 related_searches
rank_group	integer	同类型分组排名
rank_absolute	integer	SERP局绝对排名
page	integer	所在页码
position	string	left / right
xpath	string	素 XPath
items	array	部条目，无则为 null
rectangle	object	区块坐标与尺寸；Seznam 下通常为 null

---

3）local_pack 本地结果

字段	类型	说明
type	string	固定为 local_pack
rank_group	integer	同类型分组排名
rank_absolute	integer	SERP局绝对排名
page	integer	页码
position	string	left / right
xpath	string	素 XPath
title	string	名称
description	string	描述
domain	string	域名
phone	string	电话
url	string	目标链接
is_paid	boolean	是否广告
rating	object	评分信息
cid	string	本地商户唯一标识
rectangle	object	区块坐标与尺寸；Seznam 下通常为 null

---

4）video 视频结果

字段	类型	说明
type	string	固定为 video
rank_group	integer	同类型分组排名
rank_absolute	integer	SERP局绝对排名
page	integer	页码
position	string	left / right
xpath	string	素 XPath
items	array	视频子项，无则为 null
rectangle	object	区块坐标与尺寸；Seznam 下通常为 null

video.items[]

字段	类型	说明
type	string	固定为 video_element
source	string	视频来源
title	string	标题
timestamp	string	发布时间，UTC 格式
url	string	视频链接

---

5）images 图片结果

字段	类型	说明
type	string	固定为 images
rank_group	integer	同类型分组排名
rank_absolute	integer	SERP局绝对排名
page	integer	页码
position	string	left / right
xpath	string	素 XPath
title	string	模块标题
url	string	链接
items	array	图片子项，无则为 null
rectangle	object	区块坐标与尺寸；Seznam 下通常为 null

images.items[]

字段	类型	说明
type	string	固定为 images_element
alt	string	图片 alt 文本
url	string	图片地址，可能指向原站资源或平台缓存资源

---

6）shopping 购物结果

字段	类型	说明
type	string	固定为 shopping
rank_group	integer	同类型分组排名
rank_absolute	integer	SERP局绝对排名
page	integer	页码
position	string	left / right
xpath	string	素 XPath
title	string	模块标题
items	array	商品子项，无则为 null
rectangle	object	区块坐标与尺寸

shopping.items[]

字段	类型	说明
type	string	固定为 shopping_element
title	string	商品标题
price	object	价格信息
source	string	信息来源
description	string	描述
marketplace	string	商家聚合平台或商户账户提供方
marketplace_url	string	平台商品页链接
url	string	商品链接

shopping.items[].price

字段	类型	说明
current	float	当前价格
regular	float	原价
max_value	float	最高价格
currency	string	币种 ISO 代码
is_price_range	boolean	是否为价格区间
displayed_price	string	SERP 中展示的原始价格字符串

---

7）top_stories 热门新闻

字段	类型	说明
type	string	固定为 top_stories
rank_group	integer	同类型分组排名
rank_absolute	integer	SERP局绝对排名
page	integer	页码
position	string	left / right
xpath	string	素 XPath
items	array	新闻子项，无则为 null
rectangle	object	区块坐标与尺寸

top_stories.items[]

字段	类型	说明
type	string	固定为 top_stories_element
source	string	来源站点
domain	string	来源域名
title	string	标题
date	string	页面发布日期
amp_version	boolean	是否为 AMP 页面
timestamp	string	发布时间，UTC 格式
url	string	链接地址
image_url	string	图片地址，可能为原图或平台缓存图

---

8）featured_snippet 精选摘要

字段	类型	说明
type	string	固定为 featured_snippet
rank_group	integer	同类型分组排名
rank_absolute	integer	SERP局绝对排名
page	integer	页码
position	string	left / right
xpath	string	素 XPath
domain	string	域名
title	string	结果标题
featured_title	string	摘要来源页标题
description	string	摘要描述
timestamp	string	发布时间，UTC 格式
url	string	目标链接
images	string / object	图片信息
table	object	表格信息，无则为 null
rectangle	object	区块坐标与尺寸

featured_snippet.images

字段	类型	说明
type	string	固定为 images_element
alt	string	图片 alt 文本
url	string	链接
image_url	string	图片地址，可能为原图或平台缓存图

featured_snippet.table

字段	类型	说明
table_header	array	表头字段名
table_content	array	表格，每个数组代表一行

---

请求示例

cURL

id="02261816-2027-0066-0000-c27d02864073"

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

Python

import requests

task_id = "02231256-2604-0066-2000-57133b8fc54e"
url = f"https://api.seermartech.cn/v3/serp/seznam/organic/task_get/advanced/{task_id}"

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

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

print(data)

TypeScript

import axios from "axios";

const taskId = "02231256-2604-0066-2000-57133b8fc54e";

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

轮询已完成任务再获取结果

接时，通常请求已完成任务列表，再按返回的结果地址或任务 ID 拉取。

Python 示例

import requests

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

# 1. 获取已完成任务列表
ready_url = "https://api.seermartech.cn/v3/serp/seznam/organic/tasks_ready"
ready_resp = requests.get(ready_url, headers=headers)
ready_data = ready_resp.json

results = []

if ready_data.get("status_code") == 20000:
 for task_group in ready_data.get("tasks", []):
 for task in task_group.get("result", []) or []:
 # 2. 按 endpoint_advanced 获取高级结果
 endpoint = task.get("endpoint_advanced")
 if endpoint:
 resp = requests.get(f"https://api.seermartech.cn{endpoint}" if endpoint.startswith("/v3/") else endpoint, headers=headers)
 results.append(resp.json)

 # 3. 或按任务 ID 获取
 # task_id = task.get("id")
 # if task_id:
 # resp = requests.get(
 # f"https://api.seermartech.cn/v3/serp/seznam/organic/task_get/advanced/{task_id}",
 # headers=headers
 # )
 # results.append(resp.json)

print(results)

TypeScript 示例

import axios from "axios";

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

async function fetchCompletedTaskResults {
 const ready = await axios.get(
 "https://api.seermartech.cn/v3/serp/seznam/organic/tasks_ready",
 { headers }
 );

 const results: any[] = [];

 if (ready.data?.status_code === 20000) {
 for (const taskGroup of ready.data.tasks || []) {
 for (const task of taskGroup.result || []) {
 if (task.endpoint_advanced) {
 const endpoint = task.endpoint_advanced.startsWith("/v3/")
 ? `https://api.seermartech.cn${task.endpoint_advanced}`
 : task.endpoint_advanced;

 const detail = await axios.get(endpoint, { headers });
 results.push(detail.data);
 }

 // 或按任务 ID 获取
 // if (task.id) {
 // const detail = await axios.get(
 // `https://api.seermartech.cn/v3/serp/seznam/organic/task_get/advanced/${task.id}`,
 // { headers }
 // );
 // results.push(detail.data);
 // }
 }
 }
 }

 console.log(results);
}

fetchCompletedTaskResults.catch(console.error);

响应示例

{
 "version": "0.1.20220428",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0712 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": "restaurants prague",
 "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": 15,
 "items": [
 {
 "type": "organic",
 "rank_group": 1,
 "rank_absolute": 2,
 "page": 1,
 "position": "left",
 "xpath": "/html/body/div/div/div/div/div/div/div/div/div",
 "domain": "www.facebook.com",
 "title": "Culinary Prague - Hlavní stránka",
 "url": "https://www.facebook.com/culinaryprague/",
 "cache_url": null,
 "related_search_url": null,
 "breadcrumb": "facebook.com/culinaryprague",
 "is_image": false,
 "is_video": false,
 "is_featured_snippet": false,
 "is_malicious": false,
 "is_web_story": false,
 "description": "We will show you the best restaurants in Prague ! Vyšehradská 6, 12000 Praha",
 "pre_snippet": null,
 "extended_snippet": null,
 "images": null,
 "amp_version": false,
 "rating": null,
 "price": null,
 "highlighted": [],
 "links": null,
 "faq": null,
 "extended_people_also_search": null,
 "about_this_result": null,
 "related_result": null,
 "timestamp": null,
 "rectangle": {
 "x": 104,
 "y": 807.06,
 "width": 1075.19,
 "height": 108
 }
 },
 {
 "type": "local_pack",
 "rank_group": 1,
 "rank_absolute": 6,
 "page": 1,
 "position": "left",
 "xpath": "/html/body/div/div/div/div/div/div/div/div/div/div/div/div/div/div/div/div",
 "title": "Prague Marriott Hotel",
 "description": "4,8 (2) Kongresové a seminární hotely nNonstop Praha, Nové Město n",
 "domain": "www.marriottprague.cz",
 "phone": null,
 "url": "http://www.marriottprague.cz/#utm_source=search.seznam.cz&utm_medium=ppd&utm_content=hledani&utm_term=restaurants%20prague&utm_campaign=firmy.cz-13326240",
 "is_paid": false,
 "rating": {
 "rating_type": "CustomMax",
 "value": null,
 "votes_count": 2,
 "rating_max": null
 },
 "cid": null,
 "rectangle": {
 "x": 105.59,
 "y": 1568.59,
 "width": 1072,
 "height": 231.97
 }
 },
 {
 "type": "featured_snippet",
 "rank_group": 1,
 "rank_absolute": 7,
 "page": 1,
 "position": "left",
 "xpath": "/html/body/div/div/div/div/div/div/div/div/div",
 "domain": "cs.wikipedia.org",
 "title": "Albert Einstein – Wikipedie",
 "featured_title": null,
 "description": "Albert Einstein (14. března 1879 Ulm, Německo – 18. dubna 1955 Princeton, New Jersey, USA) byl teoretický fyzik...",
 "timestamp": null,
 "url": "https://cs.wikipedia.org/wiki/Albert_Einstein",
 "images": null,
 "table": null,
 "rectangle": {
 "x": 104,
 "y": 2224.95,
 "width": 1075.19,
 "height": 388.78
 }
 },
 {
 "type": "top_stories",
 "rank_group": 1,
 "rank_absolute": 3,
 "page": 1,
 "position": "left",
 "xpath": "/html/body/div/div/div/div/div/div/div/div/div",
 "title": "Zprávy › Cnn news",
 "items": [],
 "rectangle": {
 "x": 104,
 "y": 606.31,
 "width": 1075.19,
 "height": 243.69
 }
 },
 {
 "type": "images",
 "rank_group": 1,
 "rank_absolute": 5,
 "page": 1,
 "position": "left",
 "xpath": "/html/body/div/div/div/div/div/div/div/div/div",
 "title": "Obrázky › Albert einstein",
 "url": null,
 "items": [],
 "related_image_searches": null,
 "rectangle": {
 "x": 104,
 "y": 1380.63,
 "width": 1075.19,
 "height": 557.16
 }
 },
 {
 "type": "video",
 "rank_group": 1,
 "rank_absolute": 3,
 "page": 1,
 "position": "left",
 "xpath": "/html/body/div/div/div/div/div/div/div/div/div",
 "items": [],
 "rectangle": {
 "x": 104,
 "y": 746.3,
 "width": 1075.19,
 "height": 148.63
 }
 },
 {
 "type": "related_searches",
 "rank_group": 1,
 "rank_absolute": 15,
 "page": 1,
 "position": "left",
 "xpath": "/html/body/div/div/div/div/div/div/div/div/div",
 "items": [],
 "rectangle": {
 "x": 104,
 "y": 3936.47,
 "width": 1075.19,
 "height": 552.75
 }
 }
 ]
 }
 ]
 }
 ]
}

状态码与错误处理

• 顶层 status_code 表示整次请求状态
• tasks[].status_code 表示单个任务状态
• 建议重点处理以下：
• 顶层请求成功，但某个任务失败
• 任务存在但 result 为空
• 任务已过 30 天有效期，无法再获取结果
• 解析 items 时遇到未知 type，应保留容逻辑

通常可按以下策略处理：

1. 判断顶层 status_code == 20000
2. 再遍历 tasks[]，检查每个任务的 status_code
3. 最后按 items[].type 分流解析不同 SERP素

使用建议

• 如果需要稳定获取结果，优调用 /v3/serp/seznam/organic/tasks_ready
• 如果是异步系统，建议在创建任务时设置回调，再用本接口做补拉
• 解析 items 时不要假设结果类型固定，Seznam SERP 可能出现多种混合模块
• rectangle 在 Seznam 下通常不可用，不建议将作为核心业务依赖字段

实用场景

• 监控排名：按任务 ID 获取指定的自然结果，持续追踪目标页面在 Seznam 中的绝对排名与展示形态变化。
• 识别 SERP 版位结构：解析 item_types 与 items，判断某个查询是否出现精选摘要、本地、图片、视频等模块，制定更精细的策略。
• 分析本地搜索竞争：提取 local_pack 中的商户标题、域名、评分与链接，用于本地 SEO 竞争对手对比和商户可见度评估。
• 挖掘展现机会：结合 featured_snippet、top_stories、images、video 等结果类型，识别是否有机会非传统蓝链结果位。
• 校验抓取准确性：使用 check_url 回查真实搜索结果页，合 xpath、title、url 字段做质检与异常排查。