设置 Naver 自然搜索结果任务

POST /v3/serp/naver/organic/task_post

本接口使用 POST 方法，路径为：

/v3/serp/naver/organic/task_post

用于创建 Naver 自然搜索结果（Organic SERP）采集任务。本接口最多返回前 15 条搜索结果。Naver 搜索结果不支持按地域和语言区分，因此请求参数中不语言和地域字段。不过，您可以使用任意语言提交，搜索结果可能会因查询所使用的语言不同而变化。

任务支持两种执行优级：

1：普通优级，默认值
2：高优级，执行速度更快，但会产生额外费用

计费说明

创建任务时计费，任务结果查询不会重复收取创建任务费用。
设置 depth 大于 15 时，如果返回 15 条结果，可能按额外 SERP 结果计费。
使用 priority: 2 时会产生高优级附加费用。
实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求限制

请求体使用 UTF-8 编码的 JSON 格式。
请求体是 JSON 数组，格式为 [{ ... }]。平台限流以认证说明中的 30/60/120 次/分钟规则为准。
单次请求最多 100 个任务。 -过 100 个任务的部分将返回错误码 40006。

任务创建成功后，可以通过返回的任务唯一标识 id 获取结果。也可以在请求中设置 postback_url 或 pingback_url，任务完成后由本平台主动通知您的服务器。

如果您的服务器在 10 秒未响应回调请求，连接将因时中断，任务会转处理任务列表。建议为回调接口设置快速响应机制，并在后台异步处理任务结果。

请求参数

请求体中的每个对象代表一个任务。

字段	类型	填	说明
`keyword`	string	是	搜索，最多 700 个字符。字段中的 `%##` 编码会被解码，`+` 会被解码为空格。如需在中使用 `%`，请编码为 `%25`；如需使用 `+`，请编码为 `%2B`。
`url`	string	否	搜索查询的直接 URL。本平台会尝试从 URL 中解析所需参数。通常不建议使用此方式。示例：`https://search.naver.com/search.naver?where=nexearch&sm=top_hty&fbm=1&ie=utf8&query=iphone`
`priority`	integer	否	任务优级：`1` 普通优级，默认值；`2` 高优级。高优级任务会产生额外费用。
`depth`	integer	否	SERP 解析深度，即需要获取的结果数量。默认值为 `15`，最大值为 `700`。每个最多 15 条结果的 SERP 会单独计费；设置 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 为止。系统会对满足条件前已抓取的每个 SERP 计费。
`tag`	string	否	用户自定义任务标识，最长 255 个字符。可用于在结果中匹任务，指定的值会出现在响应任务的 `data` 对象中。
`postback_url`	string	否	任务完成后接收结果的 URL。本平台会向该地址发送 gzip 压缩的 POST 请求。支持使用 `$id` 和 `$tag` 占位符，发送时会替换为任务 ID 和经过 URL 编码的标签值。
`postback_data`	string	否	`postback_url` 返回数据类型。设置 `postback_url` 时填。可选值：`regular`、`advanced`、`html`。
`pingback_url`	string	否	任务完成通知 URL。本平台会向该地址发送 GET 请求。支持使用 `$id` 和 `$tag` 占位符。

`stop_crawl_on_match` 子字段

每个目标对象 match_type 和 match_value：

字段	类型	填	说明
`match_value`	string	是	要匹的域名、子域名或通符值。域名或子域名不得请求协议。例如：`本平台.com`、`/blog/post-*`。
`match_type`	string	是	匹类型：`domain` 精确匹域名或子域名；`with_subdomains` 匹主域名及子域名；`wildcard` 按通符模式匹。

示例：

json

{
  "stop_crawl_on_match": [
    {
      "match_type": "domain",
      "match_value": "example.com"
    },
    {
      "match_type": "wildcard",
      "match_value": "/blog/post-*"
    }
  ]
}

回调 URL 占位符

postback_url 和 pingback_url 支持以下占位符：

$id：任务唯一 ID
$tag：经过 URL 编码的任务标签

示例：

text

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

回调 URL 中的特殊字符会进行 URL 编码，例如 # 会编码为 %23。

请求示例

curl

bash

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

python

import requests

url = "https://api.seermartech.cn/v3/serp/naver/organic/task_post"

# 请求体是 JSON 数组
post_data = [
    {
        "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={
        "Authorization": "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json"
    },
    json=post_data
)

result = response.json()

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        "请求失败，错误码：{}，消息：{}".format(
            result.get("status_code"),
            result.get("status_message")
        )
    )

TypeScript

typescript

import axios from "axios";

const postData = [
  {
    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: postData
})
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.error(error.response?.data || error.message);
  });

响应说明

接口返回 JSON 对象 tasks 数组。每个任务对象对应请求体中的一个任务。

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	总体状态码。成功通常为 `20000`。
`status_message`	string	总体状态信息。
`time`	string	请求执行耗时，单位为秒。
`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` 数组中的数量。创建任务时通常为 `0`。
`path`	array	请求 URL 路径信息。
`data`	object	创建任务时提交的参数。
`result`	array/null	任务结果数组。创建任务接口返回时为 `null`，需要在任务完成后通过任务结果接口获取。

响应示例

json

{
  "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": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20100,
      "status_message": "Task Created.",
      "time": "0.0100 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
    }
  ]
}

错误处理

请根据顶层 status_code、status_message 以及各任务对象中的 status_code 和 status_message 分别处理请求级和任务级错误。

常见：

单次请求任务数 100 个：出部分返回错误码 40006。
keyword 缺失或格式不合法。
postback_url 已设置但缺少 postback_data。
stop_crawl_on_match 中缺少填字段。
回调服务器在 10 秒未返回响应，导致回调请求时。

实用场景

监控品牌排名：批量提交品牌词和产品词，获取 Naver 自然结果中的排名与展示页面，评估品牌搜索。
对比竞品 SERP 表现：使用 stop_crawl_on_match 或指定抓取深度，定位竞品域名在不同下的排名位置，支持竞品 SEO 分析。
采集移动端搜索结果：设置 device: "mobile" 并选择对应操作系统，分析移动端与桌面端 SERP 展示差异，优化移动搜索策略。
构建排名监测任务：通过 tag 标记业务线、项目或组，并结合 pingback_url 接收完成通知，降低批量任务的轮询成本。
扩展长尾结果采集：提高 depth 或 max_crawl_pages，获取更多搜索结果页面，用于长尾词挖掘、选题和搜索意图分析。

设置 Naver 自然搜索结果任务 ​

计费说明 ​

请求限制 ​

请求参数 ​

stop_crawl_on_match 子字段 ​

回调 URL 占位符 ​

请求示例 ​

curl ​

Python ​

TypeScript ​

响应说明 ​

tasks 子字段 ​

响应示例 ​

错误处理 ​

实用场景 ​