SeerMarTech API 文档

主题

获取 Google Shopping 商品规格结果（高级版） ​

接口说明 ​

通过任务 ID 获取 Google Shopping 商品规格页的解析结果。

请求方式： GET请求地址：https://api.seermartech.cn/v3/merchant/google/product_spec/task_get/advanced/$id

该接口用于查询已创建任务的结果。任务提交时计费，任务结果在 30 天 可重复获取。 扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

计费说明 ​

本接口本身为任务结果查询接口，通常不会因重复获取结果再次收费。 根据平台规则，在创建任务时扣费，结果可在随后 30 天获取。

路径参数 ​

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

沙箱调试 ​

可使用以下沙箱地址获取带模拟数据的完整响应结构，用于联调和字段适：

https://api.seermartech.cn/v3/merchant/google/product_spec/task_get/advanced/00000000-0000-0000-0000-000000000000

说明：

  • 沙箱响应会返回该端点支持的字段
  • 字段值为模拟数据
  • 使用沙箱接口不会产生扣费

返回结构 ​

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

顶层字段 ​

字段类型说明
versionstring当前 API 版本
status_codeinteger通用状态码
status_messagestring通用信息说明
timestring执行耗时，单位秒
costfloat本次请求总成本，单位 USD
tasks_countintegertasks 数组中的任务数
tasks_errorinteger返回错误的任务数
tasksarray任务结果数组

建议对 status_code 和任务级别的异常状态建立统一处理机制，以便应对请求失败、任务不存在、结果未就绪等。

tasks[] 字段 ​

字段类型说明
idstring任务 ID，UUID 格式
status_codeinteger任务状态码
status_messagestring任务状态说明
timestring任务执行耗时，单位秒
costfloat单任务成本，单位 USD
result_countintegerresult 数组中的结果数
patharray请求路径
dataobject与创建任务时一致的请求参数
resultarray结果数组

tasks[].data 字段 ​

字段类型说明
product_idstringPOST 任务中传的商品 ID
typestring搜索引擎类型。固定值：shopping_specifications
se_domainstringPOST 任务中指定的搜索引擎域名
location_codeintegerPOST 任务中指定的位置编码
language_codestringPOST 任务中指定的语言编码

tasks[].result[] 字段 ​

字段类型说明
product_idstring商品 ID
typestring搜索类型，固定为 shopping_specifications
se_domainstring搜索引擎域名
location_codeinteger位置编码
language_codestring语言编码
titlestring商品标题
descriptionstring商品描述
image_urlstring商品图片 URL
tagsarray商品标签
check_urlstring搜索引擎结果直达链接，可用于人工核验结果准确性
datetimestring结果抓取时间，格式如 2019-11-15 12:57:46 +00:00
item_typesarray当前结果中的类型
items_countintegeritems 数组中的数量
itemsarray商品规格页中的结构化条目

tasks[].result[].item_types 可选值 ​

值说明
shopping_specification商品规格项

tasks[].result[].items[] 字段 ​

items 数组商品规格页上的属性项及数据。

字段类型说明
typestring素类型，固定为 shopping_specification
rank_groupinteger在相同 type素组的位置
rank_absoluteinteger在商品规格页所有中的绝对位置
positionstring素所在位置。当前可返回：right
xpathstring素的 XPath
block_namestring商品属性区块名称，即该规格项所属的规格分组
specification_namestring商品属性名称
specification_valuestring商品属性值

请求示例 ​

cURL ​

bash
id="04171306-0696-0188-0000-98b668ecaf09"

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

Python ​

python
import requests

task_id = "02231453-2604-0066-2000-64d39c6677d4"
url = f"https://api.seermartech.cn/v3/merchant/google/product_spec/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 = "02231453-2604-0066-2000-64d39c6677d4";

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

结合 tasks_ready 拉取已完成任务 ​

通常建议查询已完成任务列表，再逐个调用本接口获取结果。

Python 示例 ​

python
import requests

base_url = "https://api.seermartech.cn"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

# 1. 获取已完成任务列表
ready_resp = requests.get(
 f"{base_url}/v3/merchant/google/product_spec/tasks_ready",
 headers=headers
)
ready_data = ready_resp.json

results = []

if ready_data.get("status_code") == 20000:
 for task_group in ready_data.get("tasks", []):
 for task_item in task_group.get("result", []) or []:
 endpoint = task_item.get("endpoint_advanced")
 task_id = task_item.get("id")

 # 2. 通过完成任务返回的 endpoint_advanced 直接取结果
 if endpoint:
 resp = requests.get(f"{base_url}{endpoint}", headers=headers)
 results.append(resp.json)

 # 3. 或通过 task_id 手动拼接结果查询地址
 # if task_id:
 # resp = requests.get(
 # f"{base_url}/v3/merchant/google/product_spec/task_get/advanced/{task_id}",
 # headers=headers
 # )
 # results.append(resp.json)

print(results)

TypeScript 示例 ​

typescript
import axios from "axios";

const baseURL = "https://api.seermartech.cn";
const headers = {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json",
};

async function fetchCompletedProductSpecTasks {
 const readyResponse = await axios.get(
 `${baseURL}/v3/merchant/google/product_spec/tasks_ready`,
 { headers }
 );

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

 if (readyData.status_code === 20000) {
 for (const taskGroup of readyData.tasks || []) {
 for (const taskItem of taskGroup.result || []) {
 // 方式 1：直接使用返回的高级结果端点
 if (taskItem.endpoint_advanced) {
 const resultResponse = await axios.get(
 `${baseURL}${taskItem.endpoint_advanced}`,
 { headers }
 );
 results.push(resultResponse.data);
 }

 // 方式 2：通过任务 ID 手动拼接查询地址
 // if (taskItem.id) {
 // const resultResponse = await axios.get(
 // `${baseURL}/v3/merchant/google/product_spec/task_get/advanced/${taskItem.id}`,
 // { headers }
 // );
 // results.push(resultResponse.data);
 // }
 }
 }
 } else {
 console.error(`error. Code: ${readyData.status_code} Message: ${readyData.status_message}`);
 }

 console.log(results);
}

fetchCompletedProductSpecTasks.catch(console.error);

响应示例 ​

json
{
 "version": "0.1.20210805",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0943 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "se_type": "shopping_specifications",
 "api": "merchant",
 "function": "product_spec",
 "se": "google",
 "language_code": "en",
 "location_code": 2840,
 "product_id": "8630889977405722046",
 "device": "desktop",
 "os": "windows"
 },
 "result": [
 {
 "check_url": "https://www.google.com/shopping/product/8630889977405722046/specs?&hl=en&gl=US&gws_rd=cr&uule=w+CAIQIFISCQs2MuSEtepUEUK33kOSuTsc",
 "datetime": "2021-08-12 08:45:01 +00:00",
 "item_types": [
 "shopping_specification"
 ],
 "items_count": 3,
 "items": [
 {
 "type": "shopping_specification",
 "rank_group": 1,
 "rank_absolute": 1,
 "position": "right",
 "xpath": "/html/body/div/div/div/div/table/tr",
 "block_name": "Universal Product Identifiers",
 "specification_name": "Brand",
 "specification_value": "Apple"
 },
 {
 "type": "shopping_specification",
 "rank_group": 2,
 "rank_absolute": 2,
 "position": "right",
 "xpath": "/html/body/div/div/div/div/table/tr",
 "block_name": "Universal Product Identifiers",
 "specification_name": "Part Numbers",
 "specification_value": "364FC3802F6B4DB8A02B0E541E551BE8, A1897, I8P-64-SIL-TMO-E, I8P-64-SIL-TMO-G, I8P-64-SIL-TMO-VG, IPHONE8PLUSMQ902LLA, MQ8E2LL/A, MQ8U2LL/A, MQ912, MQ912LL/A, PH-AP-IP8000-FAC-064-PR-A1905-Z-1GFA"
 },
 {
 "type": "shopping_specification",
 "rank_group": 3,
 "rank_absolute": 3,
 "position": "right",
 "xpath": "/html/body/div/div/div/div/table/tr",
 "block_name": "Universal Product Identifiers",
 "specification_name": "GTIN",
 "specification_value": "00190198456168"
 }
 ]
 }
 ]
 }
 ]
}

状态码与错误处理 ​

  • 顶层 status_code 表示整个请求的执行状态
  • tasks[].status_code 表示单个任务的执行状态
  • 当任务尚未完成、任务 ID 无效或结果不可用时，应以 status_code 和 status_message 为准进行处理
  • 建议统一记录以下信息：
  • 请求路径
  • 任务 ID
  • 顶层状态码与消息
  • 任务级状态码与消息
  • 原始响应

完整错误码说明可参考错误码文档。

字段解读建议 ​

商品规格页结果中的 items 是本接口最核心的数据结构，适合直接用于结构化商品属性抽取。常见处理方式：

  • 使用 block_name 对规格项进行分组，例如品牌、型号、通用商品标识等
  • 使用 specification_name 作为属性名键
  • 使用 specification_value 作为属性值
  • 使用 rank_absolute 保留规格在页面中的原始顺序
  • 使用 check_url 做人工复核或质检回溯

实用场景 ​

  • 抽取商品标准属性：批量抓取品牌、GTIN、部件号等规格字段，沉淀为商品主数据，便于商品库标准化管理。
  • 校验 Merchant Feed 完整性：将接口返回的规格项与自有商品 Feed 对比，发现缺失或错误属性，提升投放与收录质量。
  • 监控竞品商品规格：追踪竞品在购物结果页展示的核心参数，比价、卖点拆解与选品分析。
  • 构建属性映射表：基于 block_name、specification_name、specification_value 生成统一属性标签体系，支持类目治理与搜索过滤。
  • 复核页面展示信息：结合 check_url 与抓取时间字段，对异常商品规格结果进行人工核验，提高数据质检效率。

统一入口：官网 · LLM API · 控制台

© 2026 SeerMarTech · GEO · SEO 营销数据 API