获取 Wp V2 SERP 高级结果（按任务 ID）

接口说明

用于根据任务 ID 获取 /v3/serp/wp/v2/task_get/advanced/$id 的高级搜索结果。该接口适用于已提交并完成的 SERP 任务结果拉取。

请求方式： GET请求地址：

https://api.seermartech.cn/v3/serp/wp/v2/task_get/advanced/$id

$id 为任务唯一标识符。

计费说明

该类接口在创建任务时扣费，任务结果在完成后的 30 天 可重复获取。

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

路径参数

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

沙箱调试

如需查看该高级结果接口可能返回的 SERP素和字段结构，可使用沙箱地址：

https://api.seermartech.cn/v3/serp/google/images/task_get/advanced/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	URL 路径
`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	搜索细化推荐项
`item_types`	array	SERP 中识别到的结果类型
`se_results_count`	integer	SERP 结果总数
`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

表示搜索细化推荐模块。

字段	类型	说明
`type`	string	素类型，固定为 `refinement_chips`
`xpath`	string	该的 XPath
`items`	array	细化项列表

字段	类型	说明
`type`	string	素类型，固定为 `refinement_chips_element`
`title`	string	细化项标题
`url`	string	带细化参数的搜索链接
`domain`	string	SERP 中显示的域名
`options`	array	更进一步的搜索细化选项

字段	类型	说明
`type`	string	素类型，固定为 `refinement_chips_option`
`title`	string	选项标题
`url`	string	带细化参数的搜索链接
`domain`	string	SERP 中显示的域名

SERP素类型

item_types 中可能出现的类型：

carousel
images_search
related_searches

Carousel素

表示与目标的与图片轮播区块。

字段	类型	说明
`type`	string	素类型，固定为 `carousel`
`rank_group`	integer	同类型组排名
`rank_absolute`	integer	在整个 SERP 中的绝对排名
`position`	string	素在页面中的位置：`left`、`right`
`xpath`	string	素 XPath
`title`	string	该结果在 SERP 中的标题
`items`	array	与指定搜索词的和图片
`rectangle`	object	结果在页面中的矩形参数

说明：该搜索引擎类型当前不支持 calculate_rectangles 参数，因此 rectangle 始终为 null。

carousel.items[] 字段

字段	类型	说明
`type`	string	素类型，固定为 `carousel_element`
`title`	string	素标题，通常为可用于进一步细化图片搜索的
`subtitle`	string	素副标题
`image_url`	string	压缩后的特色图片链接
`rectangle`	object	矩形参数；当前通常为 `null`

Images Search素

表示图片搜索结果中的图片条目。

字段	类型	说明
`type`	string	素类型，固定为 `images_search`
`rank_group`	integer	同类型组排名
`rank_absolute`	integer	在整个 SERP 中的绝对排名
`xpath`	string	素 XPath
`title`	string	结果标题
`subtitle`	string	结果副标题，通常为来源站点
`alt`	string	图片的 alt 文本
`url`	string	承载该图片的页面 URL
`source_url`	string	图片源文件 URL
`encoded_url`	string	搜索引擎缓存的图片 URL

表示搜索模块。

字段	类型	说明
`type`	string	素类型，固定为 `related_searches`
`rank_group`	integer	同类型组排名
`rank_absolute`	integer	在整个 SERP 中的绝对排名
`position`	string	素在页面中的位置：`left`、`right`
`xpath`	string	素 XPath
`items`	array	素中的附加项；若没有则为 `null`
`rectangle`	object	结果矩形参数

说明：该搜索引擎类型当前不支持 calculate_rectangles 参数，因此 rectangle 始终为 null。

请求示例

cURL

bash

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

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

Python

python

import requests

task_id = "02231256-2604-0066-2000-57133b8fc54e"

url = f"https://api.seermartech.cn/v3/serp/wp/v2/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/wp/v2/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);
});

响应示例

json

{
 "version": "0.1.20220627",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "34.4921 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "serp",
 "function": "task_get",
 "se": "google",
 "se_type": "images",
 "language_code": "en",
 "location_code": 2840,
 "keyword": "iphone wallpaper",
 "device": "desktop",
 "os": "windows"
 },
 "result": [
 {
 "se_results_count": 0,
 "items_count": 101,
 "items": [
 {
 "type": "images_search",
 "rank_group": 1,
 "rank_absolute": 2,
 "xpath": "/html/body/div/c-wiz/div/div/div/div/div/div/div/span/div/div",
 "title": "50,000+ Best iPhone Wallpaper Photos ...",
 "subtitle": "pexels.com",
 "alt": "50,000+ Best iPhone Wallpaper Photos · 100% Free Download · Pexels Stock Photos",
 "url": "https://www.pexels.com/search/iphone%20wallpaper/",
 "source_url": "https://images.pexels.com/photos/2486168/pexels-photo-2486168.jpeg?cs=srgb&dl=pexels-roberto-nickson-2486168.jpg&fm=jpg",
 "encoded_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQX_myk5jX77-Ljy3cvcOWEVAcS_QuVL3DTXKYUmpz8hYCnzWj7j6tbd8almtUsQSxSXe0&usqp=CAU"
 },
 {
 "type": "images_search",
 "rank_group": 2,
 "rank_absolute": 3,
 "xpath": "/html/body/div/c-wiz/div/div/div/div/div/div/div/span/div/div",
 "title": "75 IPhone Wallpaper Cool Backgrounds ...",
 "subtitle": "artisthue.com",
 "alt": "75 IPhone Wallpaper Cool Backgrounds For You To Save | Artist Hue",
 "url": "https://artisthue.com/75-cool-iphone-wallpapers-backgrounds-for-you-to-save/",
 "source_url": "https://i0.wp.com/artisthue.com/wp-content/uploads/2020/12/Aesthetic-Full-Moon-Wallpaper.jpg?resize=576%2C1024&ssl=1",
 "encoded_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcRv9rxrX1GwaadHzrRf3v23ZKZ2dKHBuS64y-hqojob0NQ8m0WU2Zuvgv4DnNZWkjaEh6w&usqp=CAU"
 },
 {
 "type": "related_searches",
 "rank_group": 1,
 "rank_absolute": 25,
 "position": "left",
 "xpath": "/html/body/div/c-wiz/div/div/div/div/div/div/div/div/span/div/div",
 "items": null,
 "rectangle": null
 }
 ]
 }
 ]
 }
 ]
}

状态码与错误处理

顶层 status_code 表示整个请求的执行状态
tasks[].status_code 表示单个任务的执行状态
当 tasks[].result 为 null，或任务状态码大于等于 40000 时，通常表示该任务执行失败或结果不可用
建议同时检查：
顶层 status_code
tasks_error
单任务 status_code
result_count

错误码完整列表请参考错误码附录。

使用建议

通过任务提交接口创建 SERP 采集任务。
再通过已完成任务列表接口获取可拉取的任务 ID。
使用本接口按 id 拉取高级结果。
若需结构化分析图片结果，重点：

items[].type
rank_group
rank_absolute
title
subtitle
url
source_url
encoded_url

实用场景

监控图片搜索可见性：抓取指定下的图片结果排名、来源站点和图片链接，评估品牌或在图片搜索中的表现。
分析图片来源站点分布：统计 subtitle 与 url 对应站点，识别哪些域名在目标的图片搜索中占据优势。
挖掘图片 SEO 优化方向：结合 alt、title、source_url 分析高排名图片的命名与语义特征，优化站图片素材与落地页。
发现搜索细分需求：利用 refinement_chips 和 related_searches 提取用户进一步搜索的方向，扩展图片选题。
校验 SERP 抓取准确性：通过 check_url 与 xpath 进行人工复核，验证结果是否与搜索页面一致，提升数据质检效率。

获取 Wp V2 SERP 高级结果（按任务 ID）

接口说明

计费说明

路径参数

沙箱调试

响应结构

顶层字段

tasks[] 字段

result[] 字段

spell 对象

refinement_chips 对象

refinement_chips.items[] 字段

refinement_chips.items[].options[] 字段

SERP素类型

Carousel素

carousel.items[] 字段

Images Search素

请求示例

cURL

Python

TypeScript

响应示例

状态码与错误处理

使用建议

实用场景

获取 Wp V2 SERP 高级结果（按任务 ID） ​

接口说明 ​

计费说明 ​

路径参数 ​

沙箱调试 ​

响应结构 ​

顶层字段 ​

tasks[] 字段 ​

result[] 字段 ​

spell 对象 ​

refinement_chips 对象 ​

refinement_chips.items[] 字段 ​

refinement_chips.items[].options[] 字段 ​

SERP素类型 ​

Carousel素 ​

carousel.items[] 字段 ​

Images Search素 ​

Related Searches素 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应示例 ​

状态码与错误处理 ​

使用建议 ​

实用场景 ​

获取 Wp V2 SERP 高级结果（按任务 ID）

接口说明

计费说明

路径参数

沙箱调试

响应结构

顶层字段

tasks[] 字段

result[] 字段

spell 对象

refinement_chips 对象

refinement_chips.items[] 字段

refinement_chips.items[].options[] 字段

SERP素类型

Carousel素

carousel.items[] 字段

Images Search素

Related Searches素

请求示例

cURL

Python

TypeScript

响应示例

状态码与错误处理

使用建议

实用场景