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

本接口使用 GET 方法，通过任务 ID 获取 Seznam 自然搜索结果高级版数据。

请求方法与路径：

text

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

，$id 为任务唯一标识。

计费说明

在提交任务时计费。
任务完成后，可在 30 天查询结果。
查询任务结果不会产生额外费用。
实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。
任务 ID 在任务提交后的 30 天有效。

请求参数

该接口不接收 JSON 请求体，任务 ID 通过 URL 路径传。

参数	类型	填	说明
`id`	string	是	任务唯一标识，UUID 格式。可在任务提交后的 30 天用于查询任务结果。

认证方式

请求头中使用 Bearer Token：

http

Authorization: Bearer smt_live_YOUR_KEY
Content-Type: application/json

请求示例

cURL

bash

curl --location \
  --request GET \
  "https://api.seermartech.cn/v3/serp/seznam/organic/task_get/advanced/02261816-2027-0066-0000-c27d02864073" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json"

Python

python

import requests

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

response = requests.get(
    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.raise_for_status()
result = response.json()
print(result)

TypeScript

typescript

import axios from "axios";

const taskId = "02261816-2027-0066-0000-c27d02864073";

axios
  .get(
    `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.response?.data || error.message);
  });

沙盒测试

可以使用以下沙盒任务 ID 查看该接口支持的 SERP 特征及扩展字段：

text

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

沙盒响应中的字段会使用模拟数据，调用沙盒接口不会产生费用。

响应结构

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

顶层响应字段

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	通用响应状态码。成功通常为 `20000`。
`status_message`	string	通用状态说明。
`time`	string	请求执行耗时，例如 `0.0712 sec.`。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务数量。
`tasks_error`	integer	`tasks` 数组中返回错误的任务数量。
`tasks`	array	任务结果数组。

`tasks` 数组

字段	类型	说明
`id`	string	任务唯一标识，UUID 格式。
`status_code`	integer	任务状态码，通常在 `10000` 至 `60000` 范围。
`status_message`	string	任务状态说明。
`time`	string	任务执行耗时。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`result_count`	integer	`result` 数组中的结果数量。
`path`	array	请求 URL 路径信息。
`data`	object	提交任务时使用的参数。
`result`	array	SERP 结果数组。

data 对象可能以下任务参数：

字段	类型	说明
`api`	string	API 类型，例如 `serp`。
`function`	string	API 操作，例如 `task_get`。
`se`	string	搜索引擎类型，例如 `seznam`。
`se_type`	string	搜索结果类型，例如 `organic`。
`keyword`	string	查询。
`language_code`	string	语言代码。
`location_code`	integer	地区代码。
`device`	string	设备类型，例如 `desktop`。
`os`	string	操作系统，例如 `windows`。
`tag`	string	用户自定义任务标签。
`postback_url`	string	异步回调地址。
`postback_data`	string	回调数据格式。
`calculate_rectangles`	boolean	是否计算 SERP素的矩形坐标。对于 Seznam 任务，此参数暂不可用， `rectangle` 始终为 `null`。

`result` 结果字段

字段	类型	说明
`keyword`	string	提交任务时的。返回值会对 URL 编码进行解码，`+` 会被解码为空格。
`type`	string	搜索结果类型。
`se_domain`	string	搜索引擎域名。
`location_code`	integer	地区代码。
`language_code`	string	语言代码。
`check_url`	string	搜索引擎结果页的直接 URL，可用于核验结果准确性。
`datetime`	string	获取结果的 UTC 时间，格式为 `yyyy-mm-dd hh-mm-ss +00:00`。
`spell`	object	搜索引擎自动纠错信息。没有纠错时通常为 `null`。
`refinement_chips`	object	搜索筛选标签。该搜索引擎通常返回 `null`。
`item_types`	array	SERP 中出现的结果类型。
`se_results_count`	integer	SERP 中的结果总数。
`pages_count`	integer	获取到的 SERP 页数。
`items_count`	integer	`items` 数组中的数量。
`items`	array	SERP 中的各类结果。

`spell` 自动纠错

字段	类型	说明
`keyword`	string	自动纠错后的，结果将针对该返回。
`type`	string	纠错类型。可选值：`did_you_mean`、`showing_results_for`、`no_results_found_for`、`including_results_for`。

`item_types` 可选值

text

images
local_pack
organic
related_searches
top_stories
featured_snippet
video
shopping

`items` 通用字段

不同 SERP 特征会使用不同字段，但通常以下定位信息：

字段	类型	说明
`type`	string	SERP素类型。
`rank_group`	integer	同类型的分组排名。不同类型之间不会影响该排名。
`rank_absolute`	integer	在整个 SERP 中的绝对排名。
`page`	integer	素所在的 SERP 页码。
`position`	string	素在页面中的对齐方式，可为 `left` 或 `right`。
`xpath`	string	素在 SERP 页面中的 XPath。
`rectangle`	object	素在 SERP 页面中的坐标和尺寸。Seznam 当前始终返回 `null`。

`rectangle` 字段

当接口返回矩形信息时，字段结构如下：

字段	类型	说明
`x`	integer/float	素左上角的横坐标。
`y`	integer/float	素左上角的纵坐标。
`width`	integer/float	素宽度，单位为像素。
`height`	integer/float	素高度，单位为像素。

`organic` 自然结果

当 type 为 organic 时，可能以下字段：

字段	类型	说明
`domain`	string	搜索结果域名。
`title`	string	搜索结果标题。
`url`	string	搜索结果 URL。
`cache_url`	string	页面缓存 URL，没有缓存时为 `null`。
`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	结果评分信息，没有评分时为 `null`。
`highlighted`	array	描述中以粗体突出显示的词语。
`links`	array	站点链接，没有站点链接时为 `null`。
`faq`	object	FAQ 扩展，没有 FAQ 时为 `null`。
`extended_people_also_search`	array	搜索扩展。
`timestamp`	string	结果发布时间，UTC 格式。

`rating` 评分字段

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

`links` 站点链接字段

字段	类型	说明
`type`	string	素类型，通常为 `link_element`。
`title`	string	链接标题。
`description`	string	链接描述。
`url`	string	站点链接 URL。

`faq` 常见问题字段

字段	类型	说明
`type`	string	素类型，通常为 `faq_box`。
`items`	array	FAQ 问答项。

FAQ 项字段：

字段	类型	说明
`type`	string	素类型，通常为 `faq_box_element`。
`title`	string	问题标题。
`description`	string	展开区域中的答案。
`links`	array	FAQ 项中的链接。

FAQ 链接字段：

字段	类型	说明
`type`	string	素类型，通常为 `link_element`。
`title`	string	链接锚文本。
`url`	string	链接 URL。

`related_searches` 搜索

搜索的 type 为 related_searches，除通用排名字段外，还：

字段	类型	说明
`items`	array/null	搜索项。没有搜索时为 `null`。

`local_pack` 本地结果

当 type 为 local_pack 时，可能：

字段	类型	说明
`title`	string	本地商户或地点名称。
`description`	string	商户描述。
`domain`	string	商户域名。
`phone`	string	电话号码。
`url`	string	商户 URL。
`is_paid`	boolean	是否为付费广告结果。
`rating`	object	商户评分信息。
`cid`	string	商户唯一标识。

`video` 视频结果

当 type 为 video 时，：

字段	类型	说明
`items`	array/null	视频条目列表。
`type`	string	视频条目类型，通常为 `video_element`。
`source`	string	视频来源。
`title`	string	视频标题。
`timestamp`	string	视频发布时间，UTC 格式。
`url`	string	视频 URL。

`images` 图片结果

当 type 为 images 时，：

字段	类型	说明
`title`	string	图片结果模块标题。
`url`	string	图片模块 URL。
`items`	array/null	图片条目列表。

图片条目字段：

字段	类型	说明
`type`	string	图片条目类型，通常为 `images_element`。
`alt`	string	图片 `alt` 文本。
`url`	string	图片原始页面或图片资源 URL。
`rectangle`	object/null	图片在 SERP 中的坐标信息。

`shopping` 商品结果

当 type 为 shopping 时，：

字段	类型	说明
`title`	string	商品标题。
`items`	array/null	商品条目列表。

商品条目字段：

字段	类型	说明
`type`	string	商品条目类型，通常为 `shopping_element`。
`title`	string	商品标题。
`price`	object	商品价格信息。
`displayed_price`	string	页面展示的原始价格文本。
`source`	string	商品信息来源。
`description`	string	商品描述。
`marketplace`	string	商品所在电商平台或商户平台。
`marketplace_url`	string	商品在电商平台中的页面 URL。
`url`	string	商品 URL。
`rectangle`	object/null	商品的坐标信息。

`price` 价格字段

字段	类型	说明
`current`	float	当前价格。
`regular`	float	常规价格。
`max_value`	float	价格范围中的最高价格。
`currency`	string	价格币种，使用 ISO 货币代码。
`is_price_range`	boolean	是否为价格区间。

`top_stories` 资讯结果

当 type 为 top_stories 时，：

字段	类型	说明
`items`	array/null	资讯条目列表。

资讯条目字段：

字段	类型	说明
`type`	string	条目类型，通常为 `top_stories_element`。
`source`	string	资讯来源。
`domain`	string	来源域名。
`title`	string	资讯标题。
`date`	string	页面来源的发布日期。
`amp_version`	boolean	是否存在 AMP 版本。
`timestamp`	string	结果发布时间，UTC 格式。
`url`	string	资讯 URL。
`image_url`	string	资讯图片 URL。
`rectangle`	object/null	资讯模块坐标信息。

`featured_snippet` 精选摘要

当 type 为 featured_snippet 时，：

字段	类型	说明
`domain`	string	精选摘要来源域名。
`title`	string	搜索结果标题。
`featured_title`	string	精选摘要来源页面标题。
`description`	string	精选摘要。
`timestamp`	string	结果发布时间，UTC 格式。
`url`	string	来源页面 URL。
`images`	object/null	精选摘要中的图片信息。
`table`	object/null	精选摘要中的表格信息。

`table` 表格字段

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

时间字段格式

datetime、timestamp 等时间字段均使用 UTC 格式：

text

yyyy-mm-dd hh-mm-ss +00:00

示例：

text

2019-11-15 12:57:46 +00:00

响应示例

json

{
  "version": "0.1.20220428",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.0712 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "02261816-2027-0066-0000-c27d02864073",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.0500 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "serp",
        "seznam",
        "organic",
        "task_get",
        "advanced"
      ],
      "data": {
        "api": "serp",
        "function": "task_get",
        "se": "seznam",
        "se_type": "organic",
        "language_code": "cs",
        "location_code": 2203,
        "keyword": "restaurants prague",
        "device": "desktop",
        "os": "windows"
      },
      "result": [
        {
          "keyword": "restaurants prague",
          "type": "organic",
          "se_domain": "search.seznam.cz",
          "location_code": 2203,
          "language_code": "cs",
          "check_url": "https://search.seznam.cz/",
          "datetime": "2019-11-15 12:57:46 +00:00",
          "item_types": [
            "organic",
            "local_pack",
            "featured_snippet",
            "top_stories",
            "images",
            "video",
            "related_searches"
          ],
          "se_results_count": 0,
          "pages_count": 1,
          "items_count": 3,
          "items": [
            {
              "type": "organic",
              "rank_group": 1,
              "rank_absolute": 2,
              "page": 1,
              "position": "left",
              "xpath": "/html/body/div/div/div",
              "domain": "www.example.com",
              "title": "示例搜索结果",
              "url": "https://www.example.com/",
              "cache_url": null,
              "breadcrumb": "example.com",
              "is_image": false,
              "is_video": false,
              "is_featured_snippet": false,
              "is_malicious": false,
              "is_web_story": false,
              "description": "示例搜索结果描述。",
              "pre_snippet": null,
              "extended_snippet": null,
              "amp_version": false,
              "rating": null,
              "highlighted": [],
              "links": null,
              "faq": null,
              "extended_people_also_search": null,
              "timestamp": null,
              "rectangle": null
            },
            {
              "type": "local_pack",
              "rank_group": 1,
              "rank_absolute": 6,
              "page": 1,
              "position": "left",
              "xpath": "/html/body/div/div/div",
              "title": "示例本地商户",
              "description": "示例商户描述",
              "domain": "www.example.com",
              "phone": null,
              "url": "https://www.example.com/business",
              "is_paid": false,
              "rating": null,
              "cid": null,
              "rectangle": null
            },
            {
              "type": "related_searches",
              "rank_group": 1,
              "rank_absolute": 15,
              "page": 1,
              "position": "left",
              "xpath": "/html/body/div/div/div",
              "items": null,
              "rectangle": null
            }
          ]
        }
      ]
    }
  ]
}

状态码与异常处理

请根据以下字段判断请求和任务是否成功：

顶层 status_code：判断 API 请求是否成功。
任务级 tasks[].status_code：判断任务是否成功。
status_message：查看对应的状态说明。
当状态码表示错误，或 result 为空时，应记录错误信息并执行重试、告警或人工排查。
建议在业务系统中完整处理网络异常、认证失败、任务过期、任务不存在和结果为空等。

实用场景

监控自然排名：定期读取指定的 organic 结果，跟踪目标域名在 Seznam 中的排名变化。
分析 SERP 特征占位：利用 item_types、featured_snippet、local_pack、video 和 images 等字段，评估页面获得特殊搜索展现的机会。
提取本地搜索竞争信息：读取 local_pack 中的商户名称、域名、电话、评分和 cid，用于本地 SEO 竞品分析。
发现优化方向：结合 related_searches、faq 和 extended_people_also_search，扩展和主题。
核验搜索结果页面结构：使用 check_url、xpath、排名字段和 SERP素类型，对采集结果进行准确性校验和页面结构分析。

通过任务 ID 获取 Seznam 自然搜索结果（高级版） ​

计费说明 ​

请求参数 ​

认证方式 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

沙盒测试 ​

响应结构 ​

顶层响应字段 ​

tasks 数组 ​

result 结果字段 ​

spell 自动纠错 ​

item_types 可选值 ​

items 通用字段 ​

rectangle 字段 ​

organic 自然结果 ​

rating 评分字段 ​

links 站点链接字段 ​

faq 常见问题字段 ​

related_searches 搜索 ​

local_pack 本地结果 ​

video 视频结果 ​

images 图片结果 ​

shopping 商品结果 ​

price 价格字段 ​

top_stories 资讯结果 ​

featured_snippet 精选摘要 ​

table 表格字段 ​

时间字段格式 ​

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

计费说明

请求参数

认证方式

请求示例

cURL

Python

TypeScript

沙盒测试

响应结构

顶层响应字段

`tasks` 数组

`result` 结果字段

`spell` 自动纠错

`item_types` 可选值

`items` 通用字段

`rectangle` 字段

`organic` 自然结果

`rating` 评分字段

`links` 站点链接字段

`faq` 常见问题字段

`related_searches` 搜索

`local_pack` 本地结果

`video` 视频结果

`images` 图片结果

`shopping` 商品结果

`price` 价格字段

`top_stories` 资讯结果

`featured_snippet` 精选摘要

`table` 表格字段

时间字段格式