获取 Naver 自然搜索 SERP 结果（按任务 ID，Regular）

通过任务 ID 获取已提交的 Naver 自然搜索结果。请求成功后，可在任务创建后的 30 天多次获取结果；在创建任务时计费。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

接口说明

GET https://api.seermartech.cn/v3/serp/naver/organic/task_get/regular/$id

计费说明

本接口本身不对已完成任务的结果读取重复收费；
费用发生在任务提交阶段；
任务结果可在 30 天 随时查询；
实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

路径参数

字段	类型	说明
`id`	string	任务唯一标识，UUID 格式。该 ID 可在任务创建后 30 天用于随时获取结果。

沙箱调试

可使用以下沙箱地址查看本接口支持的返回结构与字段，返回值为演示数据，不会计费：

https://api.seermartech.cn/v3/serp/naver/organic/task_get/regular/00000000-0000-0000-0000-000000000000

沙箱响应会该端点下所有可返回的结果项与字段，但字段值为模拟数据。

返回结果结构

接口返回 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	与创建任务时 POST 请求中传的参数一致。
`result`	array	结果数组。

`tasks[].result[]` 字段

字段	类型	说明
`keyword`	string	POST 提交的。返回时会解码 `%##`；加号 `+` 会被还原为空格。
`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`。示例：`2019-11-15 12:57:46 +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` 可取值

item_types 表示本次 SERP 中出现过的结果类型，可能：

images
local_pack
map
organic
paid
related_searches
video

注意：

该数组会列出 SERP 中检测到的结果类型；
但本接口返回 organic 和 paid 两类结果的详细数据；
如需获取 SERP 特性、富摘要等结果项，请使用对应的高级 SERP 端点：/v3/serp/naver/organic/task_get/advanced

`items[]` 结果项说明

本接口会在 items 中返回 organic 与 paid 两类结果。

自然结果 `organic`

字段	类型	说明
`type`	string	结果类型，固定为 `organic`。
`rank_group`	integer	同类型结果中的组排名。不同 `type` 的结果不会计该排名。
`rank_absolute`	integer	在整个 SERP 中的绝对排名。
`page`	integer	结果所在的搜索结果页码。
`domain`	string	结果所属域名。
`title`	string	结果标题。
`description`	string	结果描述。
`url`	string	结果链接。
`breadcrumb`	string	结果面屑路径。

竞价结果 `paid`

字段	类型	说明
`type`	string	结果类型，固定为 `paid`。
`rank_group`	integer	同类型结果中的组排名。不同 `type` 的结果不会计该排名。
`rank_absolute`	integer	在整个 SERP 中的绝对排名。
`page`	integer	结果所在的搜索结果页码。
`domain`	string	结果所属域名。
`title`	string	结果标题。
`description`	string	结果描述。
`url`	string	结果链接。
`breadcrumb`	string	结果面屑路径。

调用方式

通常有两种方式获取结果：

调用 /v3/serp/naver/organic/tasks_ready 获取已完成任务列表；
再根据返回的任务结果地址或任务 ID，调用本接口读取 SERP 数据。

请求示例

cURL

bash

id="09171517-0696-0242-0000-a96bc1ad0bce"

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

Python

python

import requests

task_id = "09171517-0696-0242-0000-a96bc1ad0bce"
url = f"https://api.seermartech.cn/v3/serp/naver/organic/task_get/regular/{task_id}"

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

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

TypeScript

typescript

import axios from "axios";

const taskId = "02201650-1073-0066-2000-1d132bb28897";

axios({
 method: "get",
 url: `https://api.seermartech.cn/v3/serp/naver/organic/task_get/regular/${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);
});

获取已完成任务后批量获取结果示例

Python

python

import requests

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

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

results = []

if ready_resp.get("status_code") == 20000:
 for task_group in ready_resp.get("tasks", []):
 for task_info in task_group.get("result", []):
 # 2. 通过 endpoint_regular 直接取结果
 endpoint = task_info.get("endpoint_regular")
 if endpoint:
 full_url = f"https://api.seermartech.cn{endpoint}" if endpoint.startswith("/v3/") else endpoint
 result_resp = requests.get(full_url, headers=headers).json
 results.append(result_resp)

 # 3. 或通过任务 ID 组本接口地址取结果
 # task_id = task_info.get("id")
 # if task_id:
 # url = f"https://api.seermartech.cn/v3/serp/naver/organic/task_get/regular/{task_id}"
 # result_resp = requests.get(url, headers=headers).json
 # results.append(result_resp)

print(results)

TypeScript

typescript

import axios from "axios";

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

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

 const readyData = readyResponse.data;
 const results: any[] = [];

 if (readyData.status_code === 20000) {
 for (const taskGroup of readyData.tasks || []) {
 for (const taskInfo of taskGroup.result || []) {
 // 方式一：直接调用已返回的 endpoint_regular
 if (taskInfo.endpoint_regular) {
 const endpoint = taskInfo.endpoint_regular.startsWith("/v3/")
 ? `https://api.seermartech.cn${taskInfo.endpoint_regular}`
 : taskInfo.endpoint_regular;

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

 // 方式二：用任务 ID 拼接本接口地址
 /*
 if (taskInfo.id) {
 const resultResponse = await axios.get(
 `https://api.seermartech.cn/v3/serp/naver/organic/task_get/regular/${taskInfo.id}`,
 { headers }
 );
 results.push(resultResponse.data);
 }
 */
 }
 }
 }

 console.log(results);
}

fetchCompletedTaskResults.catch(console.error);

响应示例

json

{
 "version": "0.1.20210304",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.2318 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "09171517-0696-0242-0000-a96bc1ad0bce",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0213 sec.",
 "cost": 0,
 "result_count": 1,
 "path": [
 "v3",
 "serp",
 "naver",
 "organic",
 "task_get",
 "regular",
 "09171517-0696-0242-0000-a96bc1ad0bce"
 ],
 "data": {
 "api": "serp",
 "function": "task_get",
 "se": "naver",
 "se_type": "organic",
 "keyword": "iphone",
 "priority": 2,
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag",
 "device": "desktop",
 "os": "windows"
 },
 "result": [
 {
 "keyword": "iphone",
 "type": "organic",
 "se_domain": "naver.com",
 "location_code": 2410,
 "language_code": "ko",
 "check_url": "https://search.naver.com/search.naver?query=iphone",
 "datetime": "2019-11-15 12:57:46 +00:00",
 "spell": null,
 "refinement_chips": null,
 "item_types": [
 "organic",
 "paid"
 ],
 "se_results_count": 0,
 "pages_count": 1,
 "items_count": 110,
 "items": [
 {
 "type": "organic",
 "rank_group": 1,
 "rank_absolute": 1,
 "page": 1,
 "domain": "example.com",
 "title": "示例自然结果标题",
 "description": "示例自然结果描述",
 "url": "https://example.com/page",
 "breadcrumb": "example.com > page"
 },
 {
 "type": "paid",
 "rank_group": 1,
 "rank_absolute": 2,
 "page": 1,
 "domain": "ads-example.com",
 "title": "示例广告标题",
 "description": "示例广告描述",
 "url": "https://ads-example.com/landing",
 "breadcrumb": "ads-example.com > landing"
 }
 ]
 }
 ]
 }
 ]
}

状态码与错误处理

顶层 status_code 表示整次请求的执行状态；
tasks[].status_code 表示单个任务的执行结果；
建议同时校验：
HTTP 状态码；
顶层 status_code；
tasks[].status_code；
result 是否为空。

当 tasks[].status_code >= 40000 或 result 为空时，应按失败处理并记录 status_message 以便排查。

使用提示

返回时会自动完成 URL 解码；
如果搜索引擎对做了自动纠错，结果可能基于纠正后的词返回；
rank_group 在同类型结果排名；
rank_absolute 是整个 SERP 中的绝对位置；
如需更丰富的 SERP 特征数据，请改用高级结果接口 /v3/serp/naver/organic/task_get/advanced。

实用场景

监控品牌词排名：按任务 ID 拉取品牌词在 Naver 自然结果中的排名与页面位置，及时发现品牌变化。
分析竞品投放占位：同时查看 organic 与 paid 结果，识别竞品是否通过广告和自然结果双重占位抢流量。
校验本地化搜索表现：结合 location_code 和 language_code，核对不同地区、语言环境下的排名差异。
复核抓取准确性：使用 check_url 回看真实搜索结果页面，人工验收 SERP 数据质量。
构建历史排名库：定期创建任务并在 30 天回收结果，沉淀、域名、标题与排名的历史变化数据。

获取 Naver 自然搜索 SERP 结果（按任务 ID，Regular） ​

接口说明 ​

计费说明 ​

路径参数 ​

沙箱调试 ​

返回结果结构 ​

顶层字段 ​

tasks[] 字段 ​

tasks[].result[] 字段 ​

spell 字段 ​

item_types 可取值 ​

items[] 结果项说明 ​

自然结果 organic ​

竞价结果 paid ​

调用方式 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

获取已完成任务后批量获取结果示例 ​

Python ​

TypeScript ​

响应示例 ​

状态码与错误处理 ​

使用提示 ​

实用场景 ​

获取 Naver 自然搜索 SERP 结果（按任务 ID，Regular）

接口说明

计费说明

路径参数

沙箱调试

返回结果结构

顶层字段

`tasks[]` 字段

`tasks[].result[]` 字段

`spell` 字段

`item_types` 可取值

`items[]` 结果项说明

自然结果 `organic`

竞价结果 `paid`

调用方式

请求示例

cURL

Python

TypeScript

获取已完成任务后批量获取结果示例

Python

TypeScript

响应示例

状态码与错误处理

使用提示

实用场景