Naver 自然搜索任务创建

POST /v3/serp/naver/organic/task_post

接口说明

该接口用于提交 Naver 自然搜索（Organic SERP）抓取任务，对应路径为：

POST /v3/serp/naver/organic/task_post

Naver 搜索结果默认返回前 15 条。该搜索引擎的结果不区分 location 和 language 参数，因此本接口无需传语言和地区字段。不过，你仍可使用任意语言的发起查询，最终返回结果可能会随查询语言而变化。

接口支持两种任务优级：

• 1：普通优级（默认）
• 2：高优级

高优级任务通常执行更快，但会产生额外费用。

计费说明

该接口在创建任务时计费。

• 基础参考价：约 ¥0.0240 / 次
• 若使用高优级、增大抓取深度，或抓取到更多结果页，费用可能增加
• 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准

请求方式

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

请求规则

• 请求体为 UTF-8 编码的 JSON
• POST 请求体格式为 JSON 数组：[{...}]
• 单次 POST 最多可提交 100 个任务
• 每分钟最多可发起 2000 次 API 调用
• 若单次请求中任务数 100，出部分将返回错误 40006

任务创建成功后，你可以：

• 通过返回的任务 id 轮询结果；
• 或在创建任务时传 postback_url / pingback_url，由系统在任务完成后主动通知。

如果你的回调服务在 10 秒未响应，连接会因时中断，任务将转可提取结果列表。错误码和错误信息取决于你的服务端。

---

请求参数

顶层任务对象字段

字段名	类型	填	说明
keyword	string	是	查询。最长 700 个字符。 %## 会被解码，+ 会被解码为空格；若中需要保留 %，请写为 %25；若需要保留 +，请写为 %2B。
url	string	否	直接传搜索 URL，系统会自动解析为所需字段。一般不建议使用该方式。示例：https://search.naver.com/search.naver?where=nexearch&sm=top_hty&fbm=1&ie=utf8&query=iphone
priority	integer	否	任务优级。1 = 普通优级（默认）；2 = 高优级。高优级会额外计费。
depth	integer	否	抓取结果数量。默认 15，最大 700。每 15 条结果按 1 个 SERP 单位计费；若 depth > 15 且搜索引擎返回更多结果，可能产生额外费用。
max_crawl_pages	integer	否	最大抓取页数。默认 1，最大 100。该参数与 depth合使用，用于控制翻页抓取范围。
device	string	否	设备类型。可选：desktop、mobile。默认 desktop。
os	string	否	操作系统类型。若 device=desktop，可选 windows、macos，默认 windows；若 device=mobile，可选 android、ios，默认 android。
se_domain	string	否	搜索引擎域名。通常会自动选择，也可自定义，例如：search.naver.com
search_param	string	否	附加搜索参数。用于补搜索请求控制项。
stop_crawl_on_match	array	否	命中指定目标后停止继续翻页抓取。最多可传 10 个目标对象。若设置，响应只会返回抓取到并命中项为止的结果。系统会对满足条件前已抓取的每个 SERP 计费。
tag	string	否	自定义任务标识，最长 255 字符。可用于请求结果，返回结果中的 data 对象会原样带回该值。
postback_url	string	否	任务完成后，系统会将结果以 gzip 压缩的 POST 请求发送到该地址。支持 $id 和 $tag 变量替换。
postback_data	string	条件填	当设置 postback_url 时填。可选值：regular、advanced、html。
pingback_url	string	否	任务完成后，系统会向该地址发送 GET 通知。支持 $id 和 $tag 变量替换。

stop_crawl_on_match 目标对象字段

字段名	类型	填	说明
match_value	string	是	要匹的目标域名、子域名或通符表达式。不要协议头。示例：本平台.com、/blog/post-*
match_type	string	是	匹类型。可选值：domain、with_subdomains、wildcard

回调参数说明

postback_url

任务完成后，系统会将结果推送到该 URL。

支持占位符：

• $id：任务 ID
• $tag：经过 URL 编码的任务标记

示例：

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

注意：

• postback_url 中的特殊字符会进行 URL 编码
• 例如 # 会被编码为 %23

pingback_url

任务完成后，系统会向该 URL 发送 GET 通知。

支持占位符：

• $id
• $tag

示例：

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

注意事项同 postback_url。

---

返回结果说明

接口返回 JSON 数据 tasks 数组，记录本次提交的任务信息。

顶层响应字段

字段名	类型	说明
version	string	当前 API 版本
status_code	integer	接口通用状态码
status_message	string	接口通用状态信息
time	string	执行耗时，单位秒
cost	float	本次请求总费用，单位 USD
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	单个任务费用，单位 USD
result_count	integer	result 数组数量
path	array	请求路径
data	object	创建任务时传的参数回显
result	array/null	对于任务创建接口，此处通常为 null

建议你在接时实现完整的状态码和异常处理逻辑，是针对任务级失败、时和回调异常的处理。

---

请求示例

cURL

curl --location --request POST "https://api.seermartech.cn/v3/serp/naver/organic/task_post" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "keyword": "albert einstein"
 },
 {
 "keyword": "albert einstein",
 "priority": 2,
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 }
]'

Python

import requests

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

# 请求体是 JSON 数组
payload = [
 {
 "keyword": "albert einstein"
 },
 {
 "keyword": "albert einstein",
 "priority": 2,
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 }
]

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

TypeScript

import axios from "axios";

const payload = [
 {
 keyword: "albert einstein"
 },
 {
 keyword: "albert einstein",
 priority: 2,
 tag: "some_string_123",
 pingback_url: "https://your-server.com/pingscript?id=$id&tag=$tag"
 }
];

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

---

返回示例

{
 "version": "0.1.20210304",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.1338 sec.",
 "cost": 0.0015,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0317 sec.",
 "cost": 0.0015,
 "result_count": 0,
 "path": [
 "v3",
 "serp",
 "naver",
 "organic",
 "task_post"
 ],
 "data": {
 "api": "serp",
 "function": "task_post",
 "se": "naver",
 "se_type": "organic",
 "keyword": "albert einstein",
 "priority": 2,
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag",
 "device": "desktop",
 "os": "windows"
 },
 "result": null
 }
 ]
}

---

常见状态与错误处理

状态码	含义
20000	请求成功
20100	任务已成功创建
40006	单次 POST 请求中的任务数 100

说明：

• status_code 既可能出现在顶层响应，也可能出现在单个任务对象中；
• 接时应分别判断接口级状态与任务级状态；
• 更多错误码请参考 /v3/appendix/errors

使用建议

• 优使用 keyword 创建任务，只有在你明确需要复用现成搜索链接时再使用 url
• 若需要抓取更多结果，请合理组合 depth 与 max_crawl_pages，无效翻页带来的额外成本
• 若你只心某个竞品域名是否出现在结果中，可结合 stop_crawl_on_match 降低抓取页数
• 生产环境建议 pingback_url 或 postback_url，减少轮询压力
• 回调服务需确保 10 秒可响应，时导致结果改走取列表

实用场景

• 监控品牌词排名：提交品牌词或核心产品词的 Naver 自然搜索任务，持续追踪品牌官网、新闻页和第三方页面的位置。
• 分析竞品可见度：抓取竞品在 Naver 的自然结果，判断竞品站点是否前 15 或更深层结果，为韩国市场 SEO 策略提供依据。
• 验证多语言检索表现：用韩语、英语或语言分别提交同一主题，比较不同语言查询下的结果差异，优化跨语言布局。
• 定位目标域名是否上榜：结合 stop_crawl_on_match，在命中指定域名后立即停止翻页，快速判断官网或竞品页面是否搜索结果并控制成本。
• 构建自动化结果回流流程： pingback_url 或 postback_url，在任务完成后自动接收结果，用于报表系统、排名预警或 SEO 数据仓库更新。