获取 Naver 自然搜索高级结果（按任务 ID）

接口说明

通过任务 ID 获取已提交的 Naver 自然搜索（Organic）高级版 SERP 结果。

请求方式

GET /v3/serp/naver/organic/task_get/advanced/$id

完整地址

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

计费说明

本接口本身不会重复收费，在创建任务时扣费。任务提交成功后，可在 30 天多次获取结果。

扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

路径参数

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

沙盒调试

如需查看该端点支持的 SERP素结构，可使用沙盒地址：

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

沙盒响应会返回该接口下所有可用结果项及模拟字段值，不会产生费用。

响应结构

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

顶层字段

字段	类型	说明
`version`	string	当前 API 版本
`status_code`	integer	接口通用状态码
`status_message`	string	接口通用状态信息
`time`	string	执行耗时，单位秒
`cost`	float	本次请求总成本
`tasks_count`	integer	`tasks` 数组中的任务数量
`tasks_error`	integer	返回错误的任务数量
`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	接口路径
`data`	object	与创建任务时 POST 请求中传的参数一致
`result`	array	结果数组

`result[]` 字段

字段	类型	说明
`keyword`	string	查询。返回时会对 `%##` 进行解码，`+` 会被解码为空格
`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`
`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	纠错类型

type 可选值：

did_you_mean
showing_results_for
no_results_found_for
including_results_for

`item_types` 可选值

images
local_pack
map
organic
paid
related_searches
video

SERP素说明

items[] 中会按页面结构返回不同类型的。以下为主要字段说明。

1. `organic` 自然结果

字段	类型	说明
`type`	string	固定为 `organic`
`rank_group`	integer	同类型结果的排名
`rank_absolute`	integer	整个 SERP 中的绝对排名
`page`	integer	所在搜索结果页码
`position`	string	页面布局位置，可为 `left` 或 `right`
`xpath`	string	素在页面中的 XPath
`domain`	string	结果域名
`title`	string	标题
`url`	string	结果链接
`cache_url`	string	页面缓存链接
`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	评分信息
`highlighted`	array	摘要中加粗高亮的词
`links`	array	子链接（sitelinks），无则为 `null`
`faq`	object	FAQ 扩展，无则为 `null`
`extended_people_also_search`	array	返回搜索结果页后可能出现的搜索扩展
`timestamp`	string	结果发布时间，UTC 格式
`rectangle`	object	页面坐标与尺寸信息。Naver 当前不支持 `calculate_rectangles`，因此该字段始终为 `null`

`organic.rating`

字段	类型	说明
`rating_type`	string	评分类型，可能为 `Max5`、`Percents`、`CustomMax`
`value`	integer	评分值
`votes_count`	integer	评价数量
`rating_max`	integer	评分上限

`organic.links[]`

字段	类型	说明
`type`	string	固定为 `link_element`
`title`	string	子链接标题
`description`	string	子链接描述
`url`	string	子链接 URL

`organic.faq`

字段	类型	说明
`type`	string	固定为 `faq_box`
`items`	array	FAQ 项列表

`organic.faq.items[]`

字段	类型	说明
`type`	string	固定为 `faq_box_element`
`title`	string	问题标题
`description`	string	下拉答案
`links`	array	FAQ 中出现的链接

`organic.faq.items[].links[]`

字段	类型	说明
`type`	string	固定为 `link_element`
`title`	string	锚文本
`url`	string	链接地址

`rectangle`

字段	类型	说明
`x`	integer	左上角 x 坐标
`y`	integer	左上角 y 坐标
`width`	integer	素宽度，像素
`height`	integer	素高度，像素

注意：Naver 暂不支持任务创建时的 calculate_rectangles 参数，因此所有类型中的 rectangle 通常都为 null。

2. `paid` 付费广告结果

字段	类型	说明
`type`	string	固定为 `paid`
`rank_group`	integer	同类型结果排名
`rank_absolute`	integer	绝对排名
`page`	integer	页码
`position`	string	位置，`left` 或 `right`
`xpath`	string	XPath
`domain`	string	广告展示域名
`description`	string	广告描述
`title`	string	广告标题
`url`	string	广告链接
`breadcrumb`	string	广告面屑
`highlighted`	array	加粗高亮词
`extra`	object	广告附加信息
`description_rows`	array	扩展描述，无则为 `null`
`links`	array	广告子链接，无则为 `null`
`rectangle`	object	坐标与尺寸，通常为 `null`

`paid.extra`

字段	类型	说明
`ad_aclk`	string	广告标识符

`paid.links[]`

字段	类型	说明
`type`	string	固定为 `link_element`
`title`	string	链接标题
`description`	string	链接描述
`url`	string	链接地址
`ad_aclk`	string	广告标识符

3. `related_searches` 搜索

字段	类型	说明
`type`	string	固定为 `related_searches`
`rank_group`	integer	同类型排名
`rank_absolute`	integer	绝对排名
`page`	integer	页码
`position`	string	位置，`left` 或 `right`
`xpath`	string	XPath
`items`	array	素中的附加项，无则为 `null`
`rectangle`	object	坐标与尺寸，通常为 `null`

4. `local_pack` 本地结果

字段	类型	说明
`type`	string	固定为 `local_pack`
`rank_group`	integer	同类型排名
`rank_absolute`	integer	绝对排名
`page`	integer	页码
`position`	string	位置，`left` 或 `right`
`xpath`	string	XPath
`title`	string	商户名称
`description`	string	描述
`domain`	string	展示域名
`phone`	string	电话号码
`url`	string	结果链接
`is_paid`	boolean	是否为广告
`rating`	object	评分信息
`cid`	string	本地商户唯一标识
`rectangle`	object	坐标与尺寸，通常为 `null`

rating 字段结构与 organic.rating 一致。

5. `map` 地图结果

字段	类型	说明
`type`	string	固定为 `map`
`rank_group`	integer	同类型排名
`rank_absolute`	integer	绝对排名
`page`	integer	页码
`position`	string	位置，`left` 或 `right`
`xpath`	string	XPath
`title`	string	地图结果标题
`url`	string	地图链接
`rectangle`	object	坐标与尺寸，通常为 `null`

6. `video` 视频结果

字段	类型	说明
`type`	string	固定为 `video`
`rank_group`	integer	同类型排名
`rank_absolute`	integer	绝对排名
`page`	integer	页码
`position`	string	位置，`left` 或 `right`
`xpath`	string	XPath
`items`	array	视频子项列表，无则为 `null`
`rectangle`	object	坐标与尺寸，通常为 `null`

`video.items[]`

字段	类型	说明
`type`	string	固定为 `video_element`
`source`	string	视频来源
`title`	string	视频标题
`timestamp`	string	发布时间，UTC 格式
`url`	string	视频链接

7. `images` 图片结果

字段	类型	说明
`type`	string	固定为 `images`
`rank_group`	integer	同类型排名
`rank_absolute`	integer	绝对排名
`page`	integer	页码
`position`	string	位置，`left` 或 `right`
`xpath`	string	XPath
`title`	string	图片模块标题
`url`	string	链接
`items`	array	图片子项列表，无则为 `null`
`rectangle`	object	坐标与尺寸，通常为 `null`

`images.items[]`

字段	类型	说明
`type`	string	固定为 `images_element`
`alt`	string	图片 `alt` 文本
`url`	string	图片地址；可能指向原始资源，也可能指向平台缓存存储地址

调用示例

cURL

bash

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

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

Python

python

import requests

task_id = "02261816-2027-0066-0000-c27d02864073"
url = f"https://api.seermartech.cn/v3/serp/naver/organic/task_get/advanced/{task_id}"

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

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

TypeScript

typescript

import axios from "axios";

const taskId = "02231256-2604-0066-2000-57133b8fc54e";

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

与 `tasks_ready`合使用

在生产中，通常调用：

GET /v3/serp/naver/organic/tasks_ready

获取已完成任务列表，再按返回的任务 ID 或高级结果端点逐个获取结果：

GET /v3/serp/naver/organic/task_get/advanced/$id

这种方式适合批量轮询和异步任务消费。

响应示例

json

{
 "version": "0.1.20210304",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.2266 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "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": [
 {
 "se_results_count": 0,
 "pages_count": 1,
 "items_count": 117,
 "items": [
 {
 "type": "organic",
 "xpath": "/body/div/div/div/div/section",
 "domain": "www.apple.com",
 "title": "iPhone - Apple (KR)",
 "url": "https://www.apple.com/kr/iphone/",
 "cache_url": null,
 "breadcrumb": "www.apple.com/kr/iphone",
 "is_image": false,
 "is_video": false,
 "is_featured_snippet": false,
 "is_malicious": false,
 "is_web_story": false,
 "description": "세상에서 가장 강력한 개인용 기기, iPhone 을 만나볼까요? iPhone 12 Pro, iPhone 12 Pro Max, iPhone 12, iPhone 12 mini, iPhone SE를 지금 살펴보세요.",
 "pre_snippet": null,
 "extended_snippet": null,
 "amp_version": false,
 "rating": null,
 "highlighted": null,
 "links": [],
 "faq": null,
 "extended_people_also_search": null,
 "timestamp": null,
 "rectangle": null
 },
 {
 "type": "paid",
 "rank_group": 1,
 "rank_absolute": 2,
 "page": 1,
 "position": "left",
 "xpath": "/html/body/div/div/div/div/div/div/ul/li",
 "title": "IPHONE LG헬로모바일",
 "domain": "adcr.naver.com",
 "breadcrumb": "direct.lghellovision.net",
 "url": "https://adcr.naver.com/adcr?...",
 "highlighted": null,
 "extra": {
 "ad_aclk": null
 },
 "description": "0원부터 만나는 아이폰 시리즈, 중고폰+알뜰요금제 조합으로 통신비 절약",
 "description_rows": null,
 "links": null,
 "rectangle": null
 },
 {
 "type": "related_searches",
 "rank_group": 1,
 "rank_absolute": 21,
 "page": 1,
 "position": "left",
 "xpath": "/html/body/div/div/div/div/section/div/div",
 "items": [],
 "rectangle": null
 },
 {
 "type": "images",
 "rank_group": 1,
 "rank_absolute": 2,
 "page": 1,
 "position": "left",
 "xpath": "/html/body/div/div/section/div/div",
 "title": null,
 "url": null,
 "items": [],
 "rectangle": null
 },
 {
 "type": "video",
 "rank_group": 1,
 "rank_absolute": 12,
 "page": 1,
 "position": "left",
 "xpath": "/html/body/div/div/div/div/section/div/div",
 "items": [],
 "rectangle": null
 },
 {
 "type": "local_pack",
 "rank_group": 1,
 "rank_absolute": 11,
 "page": 1,
 "position": "left",
 "xpath": "/html/body/div/div/div/div/div/div/section/div/div/div/ul/li",
 "title": "A 바비레드 강남본점",
 "description": "큐브스이크와 크림파스타가 맛있는 강남역 소개 장소",
 "domain": "map.naver.com",
 "phone": null,
 "url": "https://map.naver.com/v5/search/...",
 "is_paid": false,
 "rating": null,
 "cid": "21607745",
 "rectangle": null
 },
 {
 "type": "local_pack",
 "rank_group": 2,
 "rank_absolute": 12,
 "page": 1,
 "position": "left",
 "xpath": "/html/body/div/div/div/div/div/div/section/div/div/div/ul/li",
 "title": "B 아티초크0125",
 "description": null,
 "domain": "map.naver.com",
 "phone": null,
 "url": "https://map.naver.com/v5/search/...",
 "is_paid": false,
 "rating": null,
 "cid": "37402879",
 "rectangle": null
 },
 {
 "type": "map",
 "rank_group": 1,
 "rank_absolute": 2,
 "page": 1,
 "position": "left",
 "xpath": "/html/body/div/div/div/div/div/div",
 "title": "서울특별시",
 "url": "https://map.naver.com/v5/directions/...",
 "rectangle": null
 }
 ]
 }
 ]
 }
 ]
}

状态码与错误处理

顶层 status_code 表示接口调用整体状态。
tasks[].status_code 表示单个任务的执行状态。
如果 tasks[].status_code >= 40000，通常表示任务级错误，应结合 status_message 做针对性处理。
若 result 为空，建议检查：
任务是否已完成
任务 ID 是否正确
是否 30 天可查询期限
创建任务时的参数是否有效

使用建议

优异步获取：通过创建任务创建采集，再用本接口按 ID 获取结果。
结合 tasks_ready 轮询：适合批量任务处理。
按 item_types 分流解析：不同 SERP 模块结构差异较大，建议按类型分别解析。
保留 check_url：便于人工复核排名与 SERP 展示。
容空字段：如 faq、links、rating、rectangle 等字段可能为 null。

实用场景

监控排名：按任务 ID 回查自然结果中的 rank_absolute、domain、url，持续跟踪品牌词或核心业务词在 Naver 的排名表现。
识别 SERP 版位结构：解析 item_types 与 items，判断某个是否出现图片、视频、本地、广告等模块，为 SEO布局提供依据。
分析竞品形态：提取 organic、paid、local_pack 中的标题、描述、域名和链接，快速了解竞品在自然结果与广告结果中的占位方式。
验证本地搜索可见性：利用 local_pack 和 map素中的商户名称、cid、URL 等字段，评估门店或服务点在 Naver 本地结果中的。
抽取富结果特征：检查 faq、links、rating、is_featured_snippet 等字段，识别哪些页面触发了富摘要展示，从而优化页面结构与策略。

获取 Naver 自然搜索高级结果（按任务 ID） ​

接口说明 ​

请求方式 ​

完整地址 ​

计费说明 ​

路径参数 ​

沙盒调试 ​

响应结构 ​

顶层字段 ​

tasks[] 字段 ​

result[] 字段 ​

spell 字段 ​

item_types 可选值 ​

SERP素说明 ​

1. organic 自然结果 ​

organic.rating ​

organic.links[] ​

organic.faq ​

organic.faq.items[] ​

organic.faq.items[].links[] ​

rectangle ​

2. paid 付费广告结果 ​

paid.extra ​

paid.links[] ​

3. related_searches 搜索 ​

4. local_pack 本地结果 ​

5. map 地图结果 ​

6. video 视频结果 ​

video.items[] ​

7. images 图片结果 ​

images.items[] ​

调用示例 ​