提交 Seznam 自然搜索任务

POST /v3/serp/seznam/organic/task_post

接口说明

该接口用于提交 Seznam 自然搜索（Organic）SERP 抓取任务。Seznam 是捷本地常用搜索引擎之一，主要面向本地搜索市场，支持捷语。

接口提交成功后，平台会创建异步任务。你可以通过返回的任务 id 轮询获取结果，也可以在创建任务时设置 postback_url 或 pingback_url，由本平台在任务完成后主动通知你的系统。

请求地址

POST https://api.seermartech.cn/v3/serp/seznam/organic/task_post

计费说明

• 在创建任务时扣费；
• 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准；
• 支持两种优级：
• 1：普通优级（默认）
• 2：高优级（执行更快，费用更高）
• depth 默认抓取 10 条结果；当 depth过 10，且搜索引擎返回更多结果时，可能产生额外费用；
• 若 calculate_rectangles=true，该任务费用会 翻倍。

参考价示例：响应示例中折合参考价约 ¥0.0096 / 次。 扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求格式

• 请求体为 UTF-8 编码的 JSON
• POST 请求体格式为 JSON 数组：[{ ... }]
• 单次 POST 最多可提交 100 个任务
• 接口频率上限为 每分钟 2000 次调用
• 如果单次 POST 中任务数 100，出部分会返回错误 40006

回调说明

如果在创建任务时设置了：

• postback_url：任务完成后，本平台会向该地址发送 POST 请求，并以 gzip 格式压缩返回结果
• pingback_url：任务完成后，本平台会向该地址发送 GET 通知

你可以在回调地址中使用：

• $id：任务 ID
• $tag：URL 编码后的自定义标签

例如：

• https://your-server.com/postbackscript?id=$id
• https://your-server.com/pingscript?id=$id&tag=$tag

注意事项：

• 如果你的服务端在 10 秒未响应，连接会因时中断； -时后，任务仍会转可获取结果的任务列表，后续可通过任务 ID 拉取；
• postback_url 和 pingback_url 中的特殊字符会自动进行 URL 编码，例如 # 会被编码为 %23。

---

请求参数

字段名	类型	说明
keyword	string	填。搜索，最长 700 个字符。 %## 会被解码，+ 会被解码为空格。如果本身需要 %，请写为 %25；如果需要 +，请写为 %2B。
location_name	string	搜索位置名。若未提供 location_code，则该字段填。使用该字段时无需再传 location_code。示例：Czechia
location_code	integer	搜索位置编码。若未提供 location_name，则该字段填。使用该字段时无需再传 location_name。示例：2203
language_name	string	搜索语言名。若未提供 language_code，则该字段填。使用该字段时无需再传 language_code。示例：Czech
language_code	string	搜索语言代码。若未提供 language_name，则该字段填。使用该字段时无需再传 language_name。示例：cs
url	string	可选。直接传搜索结果页 URL，由本接口自动解析所需参数。但该方式处理复杂，且要求 URL 中已准确语言和位置参数，通常不建议优使用。
priority	integer	可选。任务优级：1 = 普通优级（默认），2 = 高优级。高优级会产生额外费用。
depth	integer	可选。SERP 抓取深度，即需要返回的结果数量。默认 10，最大 500。按每个最多含 10 条结果的 SERP 计费；若 10 条，可能增加费用。
max_crawl_pages	integer	可选。最多抓取的搜索结果页数。默认 1，最大 10。该参数与 depth 决定抓取范围。
device	string	可选。设备类型：desktop 或 mobile。默认 desktop。
os	string	可选。设备操作系统。若 device=desktop，可选 windows、macos，默认 windows；若 device=mobile，可选 android、ios，默认 android。
se_domain	string	可选。搜索引擎域名。通常由本平台自动选择，也可手动指定。示例：search.seznam.cz
search_param	string	可选。搜索请求附加参数。
calculate_rectangles	boolean	可选。是否计算高级结果中 SERP素的像素排名位置。默认 false。若设为 true，任务费用翻倍。
stop_crawl_on_match	array	可选。命中指定目标后停止继续翻页抓取。为目标对象数组，每个对象 match_type 与 match_value。最多可传 10 个对象。响应将返回直到命中目标为止的结果；在满足条件前抓取到的每个 SERP 都会计费。
tag	string	可选。用户自定义任务标识，最长 255 个字符。可用于结果对账或业务。该值会原样出现在响应 data 对象中。
postback_url	string	可选。任务完成后接收结果推送的地址。平台会发送压缩后的 POST 结果。
postback_data	string	当指定 postback_url 时填。表示推送结果的数据格式。可选值：regular、advanced、html。
pingback_url	string	可选。任务完成后接收通知的地址，平台会发送 GET 请求。

stop_crawl_on_match 子字段

字段名	类型	说明
match_value	string	当指定 stop_crawl_on_match 时填。目标域名、子域名或通符值。不要带协议头。示例：example.com、/blog/post-*
match_type	string	当指定 stop_crawl_on_match 时填。匹类型：domain（精确域名或子域名）、with_subdomains（主域名及子域名）、wildcard（通符匹）

位置与语言查询

如需获取可用的搜索位置和语言列表，可调用以下容路径：

• 位置列表：/v3/serp/wp/locations
• 语言列表：/v3/serp/wp/languages

---

请求示例

cURL

curl --location --request POST "https://api.seermartech.cn/v3/serp/seznam/organic/task_post" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "language_code": "cs",
 "location_code": 2203,
 "keyword": "albert einstein"
 },
 {
 "language_name": "Czech",
 "location_name": "Czechia",
 "keyword": "albert einstein",
 "priority": 2,
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 },
 {
 "url": "https://search.seznam.cz/?q=albert+einstein",
 "postback_data": "html",
 "postback_url": "https://your-server.com/postbackscript"
 }
]'

Python

import requests

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

data = [
 {
 # 示例1：最常用的提交方式
 # 提供语言、位置和
 "language_code": "cs",
 "location_code": 2203,
 "keyword": "albert einstein"
 },
 {
 # 示例2：附加参数方式
 # 高优级执行更快，但费用更高
 "language_name": "Czech",
 "location_name": "Czechia",
 "keyword": "albert einstein",
 "priority": 2,
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 },
 {
 # 示例3：直接传查询 URL
 # 任务完成后按指定格式推送结果
 "url": "https://search.seznam.cz/?q=albert+einstein",
 "postback_data": "html",
 "postback_url": "https://your-server.com/postbackscript"
 }
]

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

TypeScript

import axios from "axios";

const postArray = [
 {
 language_name: "Czech",
 location_name: "Czechia",
 keyword: "albert einstein"
 }
];

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

---

响应说明

接口返回 JSON 数据，一个 tasks 数组，用于描述每个已创建任务的处理结果。

顶层响应字段

字段名	类型	说明
version	string	当前 API 版本
status_code	integer	通用状态码。完整错误码请参考 /v3/appendix/errors
status_message	string	通用状态信息
time	string	请求执行耗时，单位秒
cost	float	本次请求总费用
tasks_count	integer	tasks 数组中的任务总数
tasks_error	integer	tasks 数组中出错的任务数量
tasks	array	任务结果数组

tasks 数组字段

字段名	类型	说明
id	string	平台唯一任务 ID，UUID 格式
status_code	integer	任务状态码，范围通常为 10000-60000
status_message	string	任务状态说明
time	string	任务处理耗时
cost	float	单个任务费用
result_count	integer	result 数组数量
path	array	URL 路径
data	object	与提交请求中一致的任务参数
result	array	结果数组。对于创建任务接口，该值通常为 null

---

响应示例

{
 "version": "0.1.20220428",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0616 sec.",
 "cost": 0.0006,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "12345678-1234-1234-1234-1234567890ab",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0021 sec.",
 "cost": 0.0006,
 "result_count": 0,
 "path": [
 "v3",
 "serp",
 "seznam",
 "organic",
 "task_post"
 ],
 "data": {
 "api": "serp",
 "function": "task_post",
 "se": "seznam",
 "se_type": "organic",
 "language_code": "cs",
 "location_code": 2203,
 "keyword": "albert einstein",
 "tag": "some_string_123",
 "postback_url": "https://your-server.com/postbackscript.php",
 "postback_data": "html",
 "device": "desktop",
 "os": "windows"
 },
 "result": null
 }
 ]
}

状态码与错误处理

• 20000：请求成功
• 20100：任务创建成功
• 40006：单次 POST 中提交的任务数量 100
• 错误码请参考：/v3/appendix/errors

建议在接时做好以下处理：

• 校验顶层 status_code
• 遍历 tasks 数组检查每个任务的 status_code
• 对时回调、网络异常、重复通知做幂等处理
• 使用 id 或 tag 业务任务

使用建议

1. 优使用 keyword + location + language 的方式创建任务，比直接传 url 更稳定。
2. Seznam 支持捷语，建议统一使用：

• language_code: "cs" 或
• language_name: "Czech"

3. 如果你希望在目标站点出现后立即停止翻页抓取，可 stop_crawl_on_match，以减少不的抓取成本。
4. 当你需要页面像素位置时再开启 calculate_rectangles，否则会增加费用。
5. 批量提交时，建议每次请求控制在 100 条任务。

实用场景

• 监控排名：定期提交捷语任务，跟踪目标页面在 Seznam 自然结果中的排名变化，用于本地 SEO 效果评估。
• 检测竞品：抓取指定的自然结果，观察竞品域名在捷市场的出现频率和位置，制定竞争策略。
• 发现品牌词舆：针对品牌名或产品词提交查询，快速识别官网、媒体、论坛等在 Seznam 中的自然页面。
• 按目标域名提前停止抓取：使用 stop_crawl_on_match 在命中目标域名后停止继续翻页，降低深度抓取成本并提升采集效率。
• 构建本地化搜索看板：结合任务回调与结果拉取机制，持续沉淀捷市场自然搜索数据，支撑区域 SEO 监控与趋势分析。