SeerMarTech API 文档

主题

获取 Google Shopping 商品高级结果 ​

接口说明 ​

通过任务 id 获取 Google Shopping 商品搜索任务的高级结果。

请求方式 ​

GET https://api.seermartech.cn/v3/merchant/google/products/task_get/advanced/$id

计费说明 ​

该类接口在创建任务时扣费，任务结果在后续 30 天 可反复获取。

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

路径参数 ​

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

沙箱调试 ​

可通过以下沙箱地址查看本接口支持的结果结构和字段，返回值为示例数据，不产生费用：

https://sandbox.本平台.com/v3/merchant/google/products/task_get/advanced/00000000-0000-0000-0000-000000000000

返回结构 ​

接口返回 JSON 对象， tasks 数组。

顶层字段 ​

字段类型说明
versionstring当前 API 版本。
status_codeinteger通用状态码。建议对异常和错误状态做完整处理。
status_messagestring通用状态信息。
timestring执行耗时，单位秒。
costfloat本次请求总成本，单位 USD。对于已创建任务的结果读取通常为 0。
tasks_countintegertasks 数组中的任务数量。
tasks_errorintegertasks 数组中返回错误的任务数量。
tasksarray任务结果数组。

tasks[] 字段 ​

字段类型说明
idstring任务唯一标识，UUID 格式。
status_codeinteger任务状态码，范围通常为 10000-60000。
status_messagestring任务状态信息。
timestring任务执行耗时，单位秒。
costfloat该任务成本，单位 USD。
result_countintegerresult 数组中的结果数量。
patharray请求路径。
dataobject与创建任务时 POST 请求中传的参数一致。
resultarray结果数组。

result[] 字段 ​

字段类型说明
keywordstringPOST 请求中提交的。返回时会对 %## 进行解码，+ 会被还原为空格。
typestringPOST 请求中的搜索引擎类型。
se_domainstringPOST 请求中的搜索引擎域名。
location_codeintegerPOST 请求中的地区编码。
language_codestringPOST 请求中的语言编码。
check_urlstring指向 Google Shopping 结果页的直接链接，可用于核验结果准确性。
datetimestring结果抓取时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00。
spellobject搜索引擎自动纠错信息。
item_typesarray当前 SERP 中出现的结果类型列表。
items_countintegeritems 数组中的数量。
itemsarraySERP素列表。

spell 对象 ​

字段类型说明
keywordstring搜索引擎纠正后的。
typestring自动纠错类型。可选值：did_you_mean、showing_results_for、no_results_found_for、including_results_for

item_types 可能值 ​

  • google_shopping_sponsored_carousel
  • google_shopping_paid
  • google_shopping_serp

items素类型说明 ​

本接口会返回多种 Google Shopping SERP素，不同 type 对应不同字段结构。

1) google_shopping_sponsored_carousel ​

赞助轮播商品组。

字段类型说明
typestring固定为 google_shopping_sponsored_carousel
rank_groupinteger同类型的分组排名。
rank_absoluteinteger在整个 SERP 中的绝对排名。
positionstring页面位置，可能值：left、right
xpathstring素的 XPath。
titlestring素标题。
itemsarray|null轮播中的商品项，无则为 null。
字段类型说明
typestring固定为 google_shopping_sponsored_carousel_element
xpathstring素 XPath。
titlestring商品标题。
tagsarray商品标签。
sellerstring商家名称。
pricefloat商品价格。
currencystring货币代码，ISO 4217 格式，例如 USD。
product_ratingobject商品评分信息。
product_imagesarray商品图片 URL 列表，第一张通常为主图。
shop_ad_aclkstring广告点击引用参数，可用于获取广告跳转链接。
delivery_infoobject送信息。
special_offer_infoobject商家优惠信息。

product_rating / shop_rating 通用结构 ​

字段类型说明
typestring固定为 rating_element
positionstring评分在 SERP 中的位置，left 或 right
rating_typestring评分类型，可见值：Max5、Percents、CustomMax
valuestring评分值。
votes_countinteger评价/投票数量。
rating_maxinteger该评分类型的最大值。

delivery_info 通用结构 ​

字段类型说明
delivery_messagestring送说明文案。
delivery_priceobject|null送价格信息；若运费则为 null。

delivery_price 结构 ​

字段类型说明
currentfloat当前价格。
regularfloat原始未折扣价格。
max_valuefloat最大未折扣价格。
currencystring货币代码，ISO 4217 格式。
is_price_rangeboolean是否为价格区间。
displayed_pricestring页面展示的价格文本。

special_offer_info 结构 ​

字段类型说明
titlestring优惠标题。
sub_titlestring优惠副标题。
fixed_discountinteger固定优惠金额。
fixed_discount_currencystring固定优惠金额币种。
percentage_discountinteger折扣百分比。
coupon_codestring优惠码。
coupon_infostring优惠码说明。
urlstring优惠页面 URL。已废弃，返回 null。
domainstring优惠页面域名。已废弃，返回 null。

2) google_shopping_carousel ​

自然商品轮播组。

字段类型说明
typestring固定为 google_shopping_carousel
rank_groupinteger同类型分组排名。
rank_absoluteinteger整体绝对排名。
positionstring页面位置：left、right
xpathstring素 XPath。
titlestring轮播标题。
itemsarray|null轮播中的商品。
字段类型说明
typestring固定为 google_shopping_carousel_element
xpathstring素 XPath。
titlestring商品标题。
tagsarray商品标签。
sellerstring商家名称。
pricefloat商品价格。
currencystring货币代码。
product_ratingobject商品评分。
product_imagesarray商品图片 URL 列表。
shopping_urlstringGoogle Shopping 商品页链接。
product_idstringGoogle Shopping 商品唯一标识，动态值，可能为 null。
data_docidstringSERP 数据唯一标识，动态值。
gidstringGoogle Shopping局商品标识，动态值，可能为 null。
delivery_infoobject送信息。
special_offer_infoobject优惠信息。

3) google_shopping_paid ​

付费商品广告位。

字段类型说明
typestring固定为 google_shopping_paid
rank_groupinteger同类型分组排名。
rank_absoluteinteger整体绝对排名。
positionstring页面位置：left、right
xpathstring素 XPath。
domainstringSERP 中展示的域名。
titlestring商品标题。
descriptionstring商品描述。
urlstring商家网站商品页链接。已废弃，返回 null。
shop_ad_aclkstring广告点击引用参数，可用于进一步获取广告目标链接。

4) google_shopping_serp ​

Google Shopping 商品主结果项。

字段类型说明
typestring固定为 google_shopping_serp
rank_groupinteger同类型分组排名。
rank_absoluteinteger整体绝对排名。
positionstring页面位置：left、right
xpathstring素 XPath。
domainstring展示域名。
titlestring商品标题。
descriptionstring商品描述。
urlstring商家站商品页链接。已废弃，返回 null。
shopping_urlstringGoogle Shopping 商品页链接。
tagsarray商品标签。
pricefloat当前价格。
price_multiplierinteger分期付款倍数，表示月供覆盖的月份数。
old_pricefloat原价，如有价格变动时返回。
currencystring货币代码。
product_idstringGoogle Shopping 商品唯一标识，动态值，可能为 null。
data_docidstringSERP 数据唯一标识。
sellerstring商家名称。
additional_specificationsobject附加 URL 参数对象，可用于后续请求商品规格或商家接口。
reviews_countinteger商品评论数，可能为 null。
is_best_matchboolean是否带有 “best match” 标签，可能为 null。
product_ratingobject商品评分。
shop_ratingobject店铺评分。
product_imagesarray商品图片 URL 列表。
shop_ad_aclkstring广告点击引用参数。
delivery_infoobject送信息。
stores_count_infoobject同款商品可购买店铺数量信息。
gidstringGoogle Shopping局商品标识，动态值，可能为 null。

stores_count_info 结构 ​

字段类型说明
countstring提供该商品的店铺数量。
displayed_textstringGoogle Shopping 页面的展示文本。
count_from_textboolean是否从展示文本中提取店铺数量。若页面 HTML 中存在明确数量则为 false，否则为 true。

5) related_searches ​

搜索词模块。

字段类型说明
typestring固定为 related_searches
rank_groupinteger同类型分组排名。
rank_absoluteinteger整体绝对排名。
positionstring页面位置：left、right
xpathstring素 XPath。
itemsarray|null列表，无则为 null。

调用示例 ​

cURL ​

bash
id="04171054-0696-0179-0000-e56ea58342c5"

curl --location --request GET "https://api.seermartech.cn/v3/merchant/google/products/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/products/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/products/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.20210617",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.1346 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "se_type": "shopping",
 "se": "google",
 "api": "merchant",
 "function": "products",
 "language_code": "en",
 "location_code": 2840,
 "keyword": "buy iphone",
 "price_min": "5",
 "device": "desktop",
 "os": "windows"
 },
 "result": [
 {
 "items_count": 160,
 "items": [
 {
 "type": "google_shopping_sponsored_carousel",
 "title": "Shop anker solix ps400 portable solar panel 400w",
 "items": [
 {
 "type": "google_shopping_sponsored_carousel_element",
 "title": "Anker SOLIX PS400 Portable Solar Panel (400W)",
 "tags": null,
 "seller": "Wellbots",
 "price": 599,
 "currency": "USD",
 "product_rating": {
 "type": "rating_element",
 "position": "left",
 "rating_type": "Max5",
 "value": 4.5,
 "votes_count": 77,
 "rating_max": 5
 },
 "product_images": [],
 "shop_ad_aclk": "DChcSEwjUhtL2-NeNAxXXSf8BHdzXNBQYABABGgJtZA",
 "delivery_info": null,
 "special_offer_info": {
 "title": "Get 5% OFF this product",
 "sub_title": "Wellbots",
 "fixed_discount": null,
 "fixed_discount_currency": null,
 "percentage_discount": 5,
 "coupon_code": "ANKER5",
 "coupon_info": "Enter code at checkout. Ends in 88 days.",
 "url": null,
 "domain": null
 }
 }
 ]
 },
 {
 "type": "google_shopping_carousel",
 "rank_group": 1,
 "rank_absolute": 2,
 "position": "left",
 "title": "Leather sofas",
 "items": [
 {
 "type": "google_shopping_carousel_element",
 "title": "Member's Mark Harrison Leather Sofa",
 "tags": null,
 "seller": "Sam's Club",
 "price": 1099,
 "currency": "USD",
 "product_rating": {
 "type": "rating_element",
 "position": "left",
 "rating_type": "Max5",
 "value": 4.1,
 "votes_count": 10,
 "rating_max": 5
 },
 "product_images": [],
 "shopping_url": "https://google.com/search?ibp=oshop&q=gid:8594841601800484681",
 "product_id": "9875690875641841227",
 "data_docid": null,
 "gid": "8594841601800484681",
 "delivery_info": null,
 "special_offer_info": null
 }
 ]
 },
 {
 "type": "google_shopping_serp",
 "rank_group": 1,
 "rank_absolute": 3,
 "position": "left",
 "domain": null,
 "title": "Apple iPhone 12 - 128 GB - Black - Unlocked",
 "description": "5G to download movies on the fly and stream high-quality video.",
 "url": null,
 "shopping_url": null,
 "tags": [],
 "price": 1099.99,
 "price_multiplier": null,
 "old_price": null,
 "currency": "USD",
 "product_id": "3805205938126402128",
 "data_docid": "9874368152810998595",
 "seller": "Back Market",
 "additional_specifications": null,
 "reviews_count": 9134,
 "is_best_match": false,
 "product_rating": {
 "type": "rating_element",
 "position": "left",
 "rating_type": "Max5",
 "value": "4.53",
 "votes_count": 9134,
 "rating_max": null
 },
 "shop_rating": null,
 "product_images": [],
 "shop_ad_aclk": "DChcSEwikz5aloKHxAhX8R5EFHc8oBzsYABA-GgJscg",
 "delivery_info": {
 "delivery_message": "$124.88 delivery",
 "delivery_price": {
 "current": 124.88,
 "regular": null,
 "max_value": null,
 "currency": "USD",
 "is_price_range": false,
 "displayed_price": "$124.88"
 }
 },
 "stores_count_info": {
 "count": 5,
 "displayed_text": "Compare prices from 5+ stores",
 "count_from_text": false
 },
 "gid": "9961958114952839788"
 },
 {
 "type": "google_shopping_paid",
 "rank_group": 1,
 "rank_absolute": 103,
 "position": "left",
 "domain": "www.visible.com",
 "title": "Visible® $40/mo Phone Service - Up to $150 Prepaid Mastercard",
 "description": "Includes Unlimited Data, Messages & Minutes on Verizon’s 4G LTE Network.",
 "url": null,
 "shop_ad_aclk": null
 }
 ]
 }
 ]
 }
 ]
}

状态码与错误处理 ​

  • status_code 表示接口或任务执行状态。
  • 建议同时检查顶层 status_code 与 tasks[].status_code。
  • 当 tasks[].status_code >= 40000，通常表示任务级错误，应结合 status_message 进行处理。
  • 实项目中建议建立统一的重试、告警和异常分流机制。

使用建议 ​

  1. 通过创建任务接口创建商品搜索任务。
  2. 再通过就绪任务接口 /v3/merchant/google/products/tasks_ready 获取已完成任务。
  3. 使用返回的任务 id 或 endpoint_advanced 调用本接口获取高级结果。
  4. 如需提取广告目标链接，可结合 shop_ad_aclk 调用卖家广告 URL 接口。
  5. 如需查看更细的商品规格或卖家信息，可结合 additional_specifications 调用接口。

实用场景 ​

  • 监控商品形态：识别下是否出现赞助轮播、自然商品卡片、付费广告位等模块，评估 Shopping SERP 的版位结构变化。
  • 追踪竞品价格与策略：采集 price、old_price、delivery_info、stores_count_info 等字段，分析竞品价格带、运费和履约优势。
  • 挖掘高转化商品线索：结合 product_rating、reviews_count、is_best_match 判断哪些商品更受欢迎，选品和广告投放。
  • 识别商家促销动作：通过 special_offer_info、coupon_code、折扣字段监控竞品优惠活动，支持营销节奏制定。
  • 构建商品报库：沉淀 product_id、gid、data_docid、shopping_url 等标识，用于后续商品抓取、同款聚合和跨期比对。

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

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