获取 Wp V2 SERP 常规结果

接口说明

通过任务 id 获取已提交的 Wp V2 SERP 采集结果。

• 请求方法：GET
• 请求地址：https://api.seermartech.cn/v3/serp/wp/v2/task_get/regular/$id

说明：

• $id 为任务唯一标识符，格式为 UUID
• 任务结果可在任务提交后的 30 天反复获取
• 计费发生在创建任务时，获取结果本身不额外扣费
• 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准

请求参数

路径参数

字段	类型	说明
id	string	任务唯一标识符，UUID 格式。可在 30 天用于随时查询该任务结果。

沙盒调试

如需查看该接口可返回的字段结构，可调用沙盒地址：

https://sandbox.本平台.com/v3/serp/google/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	任务唯一标识符，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	结果数据列表。

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 / null	搜索引擎自动纠错信息；若无纠错则为 null。
refinement_chips	object / null	搜索细化建议；若无则为 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	纠错类型。可选值：did_you_mean、showing_results_for、no_results_found_for、including_results_for。

说明：

• 若无自动纠错，spell 为 null
• 某些搜索引擎支持部分纠错类型

refinement_chips 对象

字段	类型	说明
type	string	固定为 refinement_chips。
xpath	string	该的 XPath。
items	array	细化建议项列表。

refinement_chips.items[] 字段

字段	类型	说明
type	string	固定为 refinement_chips_element。
title	string	细化建议标题。
url	string	带细化条件的搜索链接。
domain	string	SERP 中展示的域名。
options	array	更多细化选项。

refinement_chips.items[].options[] 字段

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

item_types 支持值

item_types 表示该次返回的 SERP 中识别到的所有结果类型，可能：

answer_box、app、carousel、multi_carousel、featured_snippet、google_flights、google_reviews、third_party_reviews、google_posts、images、jobs、knowledge_graph、local_pack、hotels_pack、map、organic、paid、people_also_ask、related_searches、people_also_search、shopping、top_stories、twitter、video、events、mention_carousel、recipes、top_sights、scholarly_articles、popular_products、podcasts、questions_and_answers、find_results_on、stocks_box、visual_stories、commercial_units、local_services、google_hotels、math_solver、currency_box、product_considerations、found_on_web、short_videos、refine_products、explore_brands、perspectives、discussions_and_forums、compare_sites、courses、ai_overview

注意：

• item_types 会列出该 SERP 中发现的所有结果类型
• 但本接口返回 featured_snippet、organic、paid 三类条目数据
• 如需获取 SERP 特性及富结果明细，应使用对应的高级 SERP 接口

items[] 结果类型说明

organic 自然结果

字段	类型	说明
type	string	固定为 organic。
rank_group	integer	同类型结果中的组排名。不同 type 之间互不计。
rank_absolute	integer	在当前 SERP部已返回中的绝对排名。高级 SERP 特性的位置不会计本结果。
page	integer	结果所在的搜索结果页码。
domain	string	结果域名。
title	string	标题。
description	string	描述文本。
url	string	结果链接。
breadcrumb	string	面屑路径。

paid 广告结果

字段	类型	说明
type	string	固定为 paid。
rank_group	integer	同类型结果中的组排名。
rank_absolute	integer	当前 SERP 已返回中的绝对排名。
page	integer	结果所在页码。
title	string	广告标题。
domain	string	广告域名。
description	string	广告描述。
url	string	广告落地页链接。
breadcrumb	string	广告面屑路径。

featured_snippet 精选摘要

字段	类型	说明
type	string	固定为 featured_snippet。
rank_group	integer	同类型结果中的组排名。
rank_absolute	integer	当前 SERP 已返回中的绝对排名。
page	integer	结果所在页码。
domain	string	结果域名。
title	string	结果标题。
description	string	摘要描述。
url	string	结果链接。
breadcrumb	string / null	固定为 null。

计费说明

• 创建任务时扣费，按任务采集成本结算
• 通过本接口按 id 获取已完成任务结果，30 天
• 响应中的 cost 字段单位为 USD
• 若用于核算，可按响应头中的扣费金额核算
• 例如结果查询接口通常不额外扣费，则可视为：参考价约 ¥0.0000 / 次
• 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准

调用示例

curl

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

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

Python

import requests

task_id = "02201650-1073-0066-2000-1d132bb28897"
url = f"https://api.seermartech.cn/v3/serp/wp/v2/task_get/regular/{task_id}"

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

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

print(data)

TypeScript

import axios from "axios";

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

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

结合 tasks_ready 获取已完成任务

在批量任务模式下，常见流程如下：

1. 调用 /v3/serp/wp/v2/tasks_ready 获取已完成任务列表
2. 从返回结果中提取任务 id 或 endpoint_regular
3. 再调用 /v3/serp/wp/v2/task_get/regular/$id 获取对应结果

这种方式适合异步轮询与批量采集场景。

响应示例

{
 "version": "0.1.20200129",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.3059 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "09171517-0696-0242-0000-a96bc1ad0bce",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0312 sec.",
 "cost": 0,
 "result_count": 1,
 "path": [
 "v3",
 "serp",
 "wp",
 "v2",
 "task_get",
 "regular",
 "09171517-0696-0242-0000-a96bc1ad0bce"
 ],
 "data": {
 "api": "serp",
 "function": "task_get",
 "se": "wp",
 "se_type": "v2",
 "language_code": "en",
 "location_code": 2840,
 "keyword": "flight ticket new york san francisco",
 "priority": "2",
 "tag": "tag2",
 "device": "desktop",
 "os": "windows"
 },
 "result": [
 {
 "keyword": "flight ticket new york san francisco",
 "type": "v2",
 "se_domain": "example.com",
 "location_code": 2840,
 "language_code": "en",
 "check_url": "https://example.com/search?q=flight+ticket+new+york+san+francisco",
 "datetime": "2019-11-15 12:57:46 +00:00",
 "spell": null,
 "refinement_chips": null,
 "item_types": [
 "featured_snippet",
 "organic",
 "paid"
 ],
 "se_results_count": 85600000,
 "pages_count": 1,
 "items_count": 96,
 "items": [
 {
 "type": "featured_snippet",
 "rank_group": 1,
 "rank_absolute": 1,
 "page": 1,
 "domain": "example.com",
 "title": "Sample Featured Snippet",
 "description": "Sample description",
 "url": "https://example.com/page",
 "breadcrumb": null
 },
 {
 "type": "organic",
 "rank_group": 1,
 "rank_absolute": 2,
 "page": 1,
 "domain": "example.org",
 "title": "Sample Organic Result",
 "description": "Organic result description",
 "url": "https://example.org/page",
 "breadcrumb": "example.org › page"
 },
 {
 "type": "paid",
 "rank_group": 1,
 "rank_absolute": 3,
 "page": 1,
 "title": "Sample Ad",
 "domain": "ads.example.net",
 "description": "Paid result description",
 "url": "https://ads.example.net/landing",
 "breadcrumb": "ads.example.net › landing"
 }
 ]
 }
 ]
 }
 ]
}

状态码与错误处理

建议重点处理以下两层状态：

顶层状态

• status_code：接口请求是否成功
• status_message：接口级说明信息

任务级状态

• tasks[].status_code：单个任务的执行状态
• tasks[].status_message：单个任务的执行说明

处理建议：

• 判断顶层 status_code 是否成功
• 再逐个判断 tasks[] 中每个任务的 status_code
• 若 result 为空或状态码为错误区间，应记录日志并重试/告警流程
• 建议对时、任务不存在、结果过期、参数错误等建立统一异常处理机制

实用场景

• 回查异步采集结果：批量提交 SERP 任务，再按任务 ID 获取结果，适合大规模监控流程。
• 监控自然位次与广告位分布：提取 organic、paid、featured_snippet 条目，分析品牌词或竞品词的结果版位结构。
• 校验采集准确性：使用 check_url 回到搜索结果页，人工抽检与质量控制。
• 识别纠错影响：通过 spell 判断搜索引擎是否改写了原始查询，统计与真实展示结果不一致。
• 分析 SERP 页面形态：结合 item_types 判断某个是否出现精选摘要、广告等结果类型，为 SEO 优级和策略提供依据。