获取 Google Shopping 商家列表高级结果

通过任务 ID 获取 Google Shopping 商家列表（Sellers）高级结果。

接口说明

请求方式： GET接口路径： /v3/merchant/google/sellers/task_get/advanced/$id

计费说明

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

由于该接口为结果查询接口，当前请求本身通常不额外扣费。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

如果参考异步任务提交价格进行估算，请以创建任务接口的单价为准，并按人民币换算展示；本页不单独计费。

路径参数

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

沙箱调试

你可以使用以下沙箱地址获取完整字段结构的模拟数据：

https://api.seermartech.cn/v3/merchant/google/sellers/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	请求路径。
`data`	object	与创建任务时传参数一致。
`result`	array	结果数组。

result[] 字段

字段	类型	说明
`product_id`	string	创建任务时传的 `product_id`。
`type`	string	搜索引擎类型。
`se_domain`	string	创建任务时指定的搜索引擎域名。
`location_code`	integer	创建任务时指定的位置编码。
`language_code`	string	创建任务时指定的语言编码。
`check_url`	string	Google Shopping 结果直达链接，可用于人工校验结果准确性。
`datetime`	string	抓取结果时间，UTC 格式：`yyyy-mm-dd hh-mm-ss +00:00`。
`title`	string	商品标题。
`url`	string	商品页 URL。
`image_url`	string	商品图片 URL。
`rating`	object	商品评分信息。
`item_types`	array	当前结果页中识别到的结果类型。可能值：`shops_list`、`buy_on_google`。
`items_count`	integer	`items` 数组中的结果数量。
`items`	array	商家列表结果。

rating 对象说明

该对象既可能用于商品评分，也可能用于店铺评分。

字段	类型	说明
`type`	string	固定为 `rating_element`。
`position`	string	素在结果页中的位置，可能值：`left`、`right`。
`rating_type`	string	评分类型，可为 `Max5`、`Percents`、`CustomMax`。
`value`	integer/float	评分值。
`votes_count`	integer	评价数量。
`rating_max`	integer	当前 `rating_type` 对应的最大分值。

items[] 结果类型

items 数组中的可能为以下两种类型：

shops_list
buy_on_google

`shops_list`素字段

字段	类型	说明
`type`	string	固定为 `shops_list`。
`rank_group`	integer	相同 `type`素组排名。
`rank_absolute`	integer	在整个 Google Shopping 结果页中的绝对排名。
`position`	string	素在结果页中的位置，可能值：`left`、`right`。
`xpath`	string	素的 XPath。
`domain`	string	结果对应域名。
`title`	string	商品标题。
`url`	string	跳转至商家网站商品页的 Google Shopping 跳转链接。
`details`	string	商品或特殊优惠信息；无则为 `null`。
`base_price`	integer/float	未含税、未含运费的商品价格。
`tax`	integer/float	税费金额，返回金额而非百分比。
`shipping_price`	integer/float	运费。
`total_price`	integer/float	含税及运费后的总价。
`currency`	string	货币代码，ISO 4217 格式，如 `USD`。
`price_multiplier`	integer	月付倍数，表示分期月数；无则可能为 `null`。
`displayed_payment_breakdown`	string	结果页展示的分期付款说明；无则可能为 `null`。
`seller_name`	string	商家名称。
`rating`	object	店铺评分信息。
`shop_ad_aclk`	string	广告点击唯一参数，可用于进一步获取广告落地链接，若无则为 `null`。
`product_condition`	string	商品成色。可能值：`Used`、`Refurbished`、`New`、`Pre-owned`、`null`。
`product_annotation`	string	商品标签或促销标记；无则为 `null`。示例：`LOW PRICE`、`SPECIAL OFFER`、`SALE`、`PRICE DROP`。
`product_availability`	string	库存状态。可能值：`in_stock`、`limited_stock`、`out_of_stock`、`backordered`、`pre_order_available`、`on_display_to_order`。

`buy_on_google`素字段

字段	类型	说明
`type`	string	固定为 `buy_on_google`。
`rank_group`	integer	相同 `type`素组排名。
`rank_absolute`	integer	在整个 Google Shopping 结果页中的绝对排名。
`position`	string	素在结果页中的位置，可能值：`left`、`right`。
`xpath`	string	素的 XPath。
`domain`	string	结果对应域名。
`title`	string	商品标题。
`url`	string	跳转至商品页的 Google Shopping 链接。
`details`	string	商品或优惠说明；无则为 `null`。
`base_price`	integer/float	未含税、未含运费的商品价格。
`tax`	integer/float	税费金额，返回金额而非百分比。
`shipping_price`	integer/float	运费。
`total_price`	integer/float	含税及运费后的总价。
`currency`	string	货币代码，ISO 4217 格式。
`seller_name`	string	商家名称。
`rating`	object	店铺评分信息。
`shop_ad_aclk`	string	广告点击唯一参数；此类型下通常为 `null`。
`product_condition`	string	商品成色。可能值：`Used`、`Refurbished`、`New`、`null`。
`product_availability`	string	库存状态。可能值：`in_stock`、`limited_stock`、`out_of_stock`、`backordered`、`pre_order_available`、`on_display_to_order`。

调用方式

通常流程如下：

调用创建任务接口创建 Google Shopping Sellers 任务；
再通过 /v3/merchant/google/sellers/tasks_ready 获取已完成任务；
使用返回的任务 ID 或结果地址调用本接口获取详细结果。

请求示例

cURL

bash

id="04171157-0696-0183-0000-4f63affdd40a"

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

Python

python

import requests

task_id = "04171157-0696-0183-0000-4f63affdd40a"

url = f"https://api.seermartech.cn/v3/merchant/google/sellers/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/sellers/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);
 });

查询已完成任务后再批量获取结果

Python

python

import requests

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

# 1. 获取已完成任务列表
ready_resp = requests.get(
 "https://api.seermartech.cn/v3/merchant/google/sellers/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 item in task_group.get("result", []) or []:
 endpoint = item.get("endpoint_advanced")
 task_id = item.get("id")

 # 2. 通过完整 endpoint 获取
 if endpoint:
 resp = requests.get(
 f"https://api.seermartech.cn{endpoint}",
 headers=headers
 )
 results.append(resp.json)

 # 3. 或通过任务 ID 拼接获取
 # if task_id:
 # resp = requests.get(
 # f"https://api.seermartech.cn/v3/merchant/google/sellers/task_get/advanced/{task_id}",
 # headers=headers
 # )
 # results.append(resp.json)
else:
 print("查询已完成任务失败：", ready_data)

print(results)

响应示例

json

{
 "version": "0.1.20240313",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0713 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "se_type": "shops_list",
 "se": "google",
 "api": "merchant",
 "function": "sellers",
 "language_code": "en",
 "location_code": 2840,
 "product_id": "1113158713975221117",
 "device": "desktop",
 "os": "windows"
 },
 "result": [
 {
 "items_count": 4,
 "items": [
 {
 "type": "shops_list",
 "rank_group": 1,
 "rank_absolute": 1,
 "position": "right",
 "xpath": "/html/body/div/div/div/div/div/table/tbody/tr",
 "domain": "www.ebay.com",
 "title": "Apple iPhone 8 Plus - 64 GB - Gold - T-Mobile - GSM",
 "url": "https://www.ebay.com/itm/355103005673?chn=ps&mkevt=1&mkcid=28",
 "details": "Free delivery by Thu, Apr 11",
 "base_price": 200,
 "tax": 20.5,
 "shipping_price": null,
 "total_price": 220.5,
 "currency": "USD",
 "price_multiplier": null,
 "displayed_payment_breakdown": null,
 "seller_name": "eBay",
 "rating": null,
 "shop_ad_aclk": null,
 "product_condition": null,
 "product_annotation": null,
 "product_availability": "in_stock"
 },
 {
 "type": "shops_list",
 "rank_group": 2,
 "rank_absolute": 2,
 "position": "right",
 "xpath": "/html/body/div/div/div/div/div/table/tbody/tr",
 "domain": "www.backmarket.com",
 "title": "Apple iPhone 8 Plus - 64 GB - Gold - T-Mobile - GSM",
 "url": "https://www.backmarket.com/en-us/p/iphone-8-plus-64-gb-gold-t-mobile/0ad199c7-97a0-45e9-a7b7-f7887ef2ed1e?shopping=gmc&srsltid=AfmBOoq3N-zYX91Q9BWZFXiR2ToM4Ek29tRNP0XDXZfq3wKrdc9ywzePtQ4#l=12",
 "details": "$1.99 delivery by Tue, Apr 9 30 -day returns",
 "base_price": 129,
 "tax": 13.22,
 "shipping_price": 1.99,
 "total_price": 144.21,
 "currency": "USD",
 "price_multiplier": null,
 "displayed_payment_breakdown": null,
 "seller_name": "Back Market",
 "rating": {
 "type": "rating_element",
 "position": "left",
 "rating_type": "Max5",
 "value": 4.6,
 "votes_count": 13600,
 "rating_max": 5
 },
 "shop_ad_aclk": null,
 "product_condition": "Refurbished",
 "product_annotation": null,
 "product_availability": "in_stock"
 },
 {
 "type": "shops_list",
 "rank_group": 3,
 "rank_absolute": 3,
 "position": "right",
 "xpath": "/html/body/div/div/div/div/div/table/tbody/tr",
 "domain": "www.mercari.com",
 "title": "Apple iPhone 8 Plus - 64 GB - Gold - T-Mobile - GSM",
 "url": "https://www.mercari.com/us/item/m24932237054/?srsltid=AfmBOord5-vf9qasvsc8XqPqDGSKl0IE1O9QbVwEzCBStkFRffdwp9AyyeM",
 "details": "Free delivery",
 "base_price": 175,
 "tax": 17.94,
 "shipping_price": null,
 "total_price": 192.94,
 "currency": "USD",
 "price_multiplier": null,
 "displayed_payment_breakdown": null,
 "seller_name": "Mercari",
 "rating": null,
 "shop_ad_aclk": null,
 "product_condition": "Used",
 "product_annotation": null,
 "product_availability": "in_stock"
 },
 {
 "type": "shops_list",
 "rank_group": 4,
 "rank_absolute": 4,
 "position": "right",
 "xpath": "/html/body/div/div/div/div/div/table/tbody/tr",
 "domain": "buy.itsworthmore.com",
 "title": "Apple iPhone 8 Plus - 64 GB - Gold - T-Mobile - GSM",
 "url": "https://buy.itsworthmore.com/products/iphone-8-plus-64gb-t-mobile-gold?variant=15513774915682&currency=USD&utm_medium=product_sync&utm_source=google&utm_content=sag_organic&utm_campaign=sag_organic&srsltid=AfmBOor0Shu1M5cBGZiBdZjlBoGNKhbprIDIcLRc7WojU10eoL_AN5gEsUw",
 "details": "Free delivery by Mon, Apr 8 30 -day returns",
 "base_price": 122.99,
 "tax": 12.61,
 "shipping_price": null,
 "total_price": 135.6,
 "currency": "USD",
 "price_multiplier": null,
 "displayed_payment_breakdown": null,
 "seller_name": "ItsWorthMore",
 "rating": {
 "type": "rating_element",
 "position": "left",
 "rating_type": "Max5",
 "value": 4.5,
 "votes_count": 1600,
 "rating_max": 5
 },
 "shop_ad_aclk": null,
 "product_condition": "Refurbished",
 "product_annotation": null,
 "product_availability": "in_stock"
 }
 ]
 }
 ]
 }
 ]
}

状态码说明

状态码	说明
`20000`	请求成功。
`10000-60000`	任务级状态码范围。请结合 `status_message` 判断结果。
`40000+`	通常表示请求、参数、权限或数据处理错误。建议做好错误重试、告警和底处理。

更多错误含义可参考错误码说明文档。

使用建议

建议通过 /v3/merchant/google/sellers/tasks_ready 轮询已完成任务，再按任务 ID 拉取。
若需要校验抓取结果，可使用返回的 check_url 进行人工抽检。
若你需要获取广告点击跳转地址，可结合 shop_ad_aclk 使用广告 URL 接口进一步解析。
对 details、rating、product_annotation、shipping_price 等字段请按可空值处理。

实用场景

监控竞品卖家分布：按 product_id 获取同款商品在 Google Shopping 中的卖家列表，识别主要竞争对手与渠道覆盖。
分析价格竞争力：基于 base_price、tax、shipping_price、total_price 对比不同商家的真实到手价，制定更有竞争力的定价策略。
识别库存与售卖状态：通过 product_availability 判断竞品是否缺货、预售或库存紧张，及时调整投放和补货节奏。
评估商家口碑优势：结合 seller_name、rating.value、votes_count 分析高排名商家的评分表现，为店铺优化和选品合作提供依据。
发现促销与商品标签机会：利用 details 与 product_annotation 识别“低价”“促销”“降价”等展示特征，优化商品页营销信息和购物广告素材。

获取 Google Shopping 商家列表高级结果 ​

接口说明 ​

计费说明 ​

路径参数 ​

沙箱调试 ​

响应结构 ​

顶层响应字段 ​

tasks[] 字段 ​

result[] 字段 ​

rating 对象说明 ​

items[] 结果类型 ​

shops_list素字段 ​

buy_on_google素字段 ​

调用方式 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

查询已完成任务后再批量获取结果 ​

Python ​

响应示例 ​

状态码说明 ​

使用建议 ​

实用场景 ​

获取 Google Shopping 商家列表高级结果

接口说明

计费说明

路径参数

沙箱调试

响应结构

顶层响应字段

tasks[] 字段

result[] 字段

rating 对象说明

items[] 结果类型

`shops_list`素字段

`buy_on_google`素字段

调用方式

请求示例

cURL

Python

TypeScript

查询已完成任务后再批量获取结果

Python

响应示例

状态码说明

使用建议

实用场景