获取 Google Shopping 卖家结果（按任务 ID）

GET /v3/merchant/google/sellers/tasks_ready

本接口使用 GET 方法，请求路径为：

/v3/merchant/google/sellers/task_get/advanced/$id

根据任务 ID 获取 Google Shopping 卖家结果。任务提交成功后，可在 30 天重复获取结果，获取任务结果不额外收费。费用在提交任务时产生，扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数

请求路径中的 $id 为任务唯一标识符。

参数	类型	说明
`id`	string	任务唯一标识符，UUID 格式。任务提交后 30 天可使用该 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"

TypeScript

typescript

import axios from "axios";

const taskId = "02231453-2604-0066-2000-64d39c6677d4";

axios
  .get(
    `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.response?.data || error.message);
  });

Python

python

import requests

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

url = (
    "https://api.seermartech.cn"
    f"/v3/merchant/google/sellers/task_get/advanced/{task_id}"
)

response = requests.get(
    url,
    headers={
        "Authorization": "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
    },
)

if response.ok:
    result = response.json()
    print(result)
else:
    print(f"请求失败：HTTP {response.status_code}")
    print(response.text)

响应说明

接口返回 JSON 数据，顶层 tasks 数组。每个任务对象任务状态、请求参数和 Google Shopping 卖家结果。

顶层响应字段

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	通用响应状态码。通常 `20000` 表示成功。
`status_message`	string	通用状态说明。
`time`	string	接口执行耗时，例如 `0.0713 sec.`。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务数量。
`tasks_error`	integer	`tasks` 数组中返回错误的任务数量。
`tasks`	array	任务结果数组。

任务字段

字段	类型	说明
`id`	string	任务唯一标识符，UUID 格式。
`status_code`	integer	任务状态码，通常在 `10000` 至 `60000` 范围。
`status_message`	string	任务状态说明。
`time`	string	任务执行耗时。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`result_count`	integer	`result` 数组中的数量。
`path`	array	请求 URL 路径信息。
`data`	object	提交任务时使用的请求参数。
`result`	array	任务结果数组。

`data` 字段

data 中通常会返回提交任务时使用的主要参数，例如：

字段	类型	说明
`se_type`	string	Google Shopping 结果类型，例如 `shops_list`。
`se`	string	搜索引擎类型，例如 `google`。
`api`	string	API 类型，例如 `merchant`。
`function`	string	功能名称，例如 `sellers`。
`language_code`	string	搜索语言代码。
`location_code`	integer	搜索地域代码。
`product_id`	string	Google Shopping 商品 ID。
`device`	string	设备类型，例如 `desktop`。
`os`	string	操作系统类型，例如 `windows`。

`result` 字段

结果基础字段

字段	类型	说明
`product_id`	string	提交任务时使用的商品 ID。
`type`	string	搜索引擎结果类型。
`se_domain`	string	提交任务时使用的搜索引擎域名。
`location_code`	integer	提交任务时使用的地域代码。
`language_code`	string	提交任务时使用的语言代码。
`check_url`	string	Google Shopping 结果页的直接 URL，可用于核验结果准确性。
`datetime`	string	获取结果的时间，UTC 格式：`yyyy-mm-dd hh-mm-ss +00:00`。例如：`2019-11-15 12:57:46 +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	评分值。
`votes_count`	integer	评价数量。
`rating_max`	integer	当前评分类型对应的最大值。

`items` 数组

items 数组中的根据 type 不同分为以下两类：

shops_list：卖家列表结果。
buy_on_google：站购买结果。

通用排名字段

字段	类型	说明
`type`	string	结果类型。
`rank_group`	integer	同类型结果中的组排名。不同类型之间不会连续计算该字段。
`rank_absolute`	integer	在整个 Google Shopping 结果页中的绝对排名。
`position`	string	素在结果页中的位置，可选值：`left`、`right`。
`xpath`	string	素在结果页中的 XPath。
`domain`	string	结果中的域名。
`title`	string	商品标题。
`url`	string	跳转至卖家商品页的 Shopping URL。
`details`	string	商品及特殊优惠；无时为 `null`。
`base_price`	integer	不含税费和运费的商品价格。
`tax`	integer	税费金额，不是百分比。
`shipping_price`	integer	运费。
`total_price`	integer	含税费和运费的商品总价。
`currency`	string	ISO 4217 货币代码，例如 `USD`。
`seller_name`	string	卖家名称。
`rating`	object	卖家评分信息。
`product_condition`	string	商品成色。可能值：`Used`、`Refurbished`、`New`、`Pre-owned`、`null`。
`product_availability`	string	商品库存状态。
`shop_ad_aclk`	string	广告点击跳转参数。可用于通过卖家广告 URL 接口获取广告落地页 URL。
`product_annotation`	string	商品标注或优惠徽章，例如 `LOW PRICE`、`SPECIAL OFFER`、`SALE`、`PRICE DROP`；无标注时为 `null`。

`shops_list` 专有字段

当 type 为 shops_list 时，除通用字段外，还可能：

字段	类型	说明
`price_multiplier`	integer	月付价格覆盖的月数。
`displayed_payment_breakdown`	string	结果页展示的分期付款说明。
`shop_ad_aclk`	string	卖家广告点击参数。

`buy_on_google` 专有字段

当 type 为 buy_on_google 时，字段结构与 shops_list 基本一致，但以下字段通常特定表现：

字段	类型	说明
`type`	string	固定为 `buy_on_google`。
`shop_ad_aclk`	string	该类型结果通常为 `null`。
`product_condition`	string	商品成色，可能值：`Used`、`Refurbished`、`New`、`null`。
`product_availability`	string	商品库存状态。

商品库存状态

product_availability 可能返回以下值：

值	说明
`in_stock`	有库存
`limited_stock`	库存有限
`out_of_stock`	无库存
`backordered`	缺货补
`pre_order_available`	支持预订
`on_display_to_order`	可展示并下单

卖家评分字段

items[].rating 用于表示卖家店铺评分，字段如下：

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

响应示例

json

{
  "version": "0.1.20240313",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.0713 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "04171157-0696-0183-0000-4f63affdd40a",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.0581 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "merchant",
        "google",
        "sellers",
        "task_get",
        "advanced"
      ],
      "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": [
        {
          "product_id": "1113158713975221117",
          "type": "shops_list",
          "se_domain": "google.com",
          "location_code": 2840,
          "language_code": "en",
          "check_url": "https://www.google.com/shopping",
          "datetime": "2024-04-08 12:57:46 +00:00",
          "title": "Apple iPhone 8 Plus - 64 GB - Gold - T-Mobile - GSM",
          "url": "https://www.example.com/product/iphone-8-plus",
          "image_url": "https://www.example.com/images/iphone-8-plus.jpg",
          "rating": null,
          "item_types": [
            "shops_list"
          ],
          "items_count": 1,
          "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.example.com",
              "title": "Apple iPhone 8 Plus - 64 GB - Gold - T-Mobile - GSM",
              "url": "https://www.example.com/product/iphone-8-plus",
              "details": "Free delivery",
              "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": "Example Seller",
              "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"
            }
          ]
        }
      ]
    }
  ]
}

错误处理

请同时检查顶层响应和任务对象中的状态字段：

顶层 status_code：判断本次 API 请求是否成功。
tasks[].status_code：判断任务是否成功。
status_message：获取错误或状态说明。
tasks_error：统计返回错误的任务数量。
当 tasks[].result 为空或任务状态码表示错误时，不应继续读取结果字段。

获取已完成任务

在批量任务场景中，可以调用以下接口获取已完成任务列表，再根据返回的任务 ID 获取详细结果：

GET /v3/merchant/google/sellers/tasks_ready

随后逐个调用：

GET /v3/merchant/google/sellers/task_get/advanced/$id

建议在任务状态码达到成功状态后再读取 result，并为时、任务不存在、任务失败和结果为空等设计重试及异常处理机制。

沙盒测试

可使用本平台提供的沙盒接口查看该端点支持的完整字段结构。沙盒响应中的字段值为模拟数据，不会产生费用。沙盒请求路径为：

/v3/merchant/google/sellers/task_get/advanced/00000000-0000-0000-0000-000000000000

实用场景

监控商品卖家排名：按商品 ID 定期获取 Google Shopping 卖家列表，比较不同卖家的排名变化，评估商品在购物结果中的表现。
对比竞品价格：汇总 base_price、tax、shipping_price 和 total_price，识别竞品的真实到手价，为定价策略和促销活动提供依据。
分析卖家库存状态：根据 product_availability 统计有货、低库存和缺货卖家，判断市场供给和补货优级。
评估卖家口碑：结合 rating 与 votes_count 分析卖家评分及评价规模，筛选高信誉渠道并支持渠道合作决策。
识别商品促销信息：读取 details 和 product_annotation 中的优惠、降价及信息，追踪竞品促销策略和价格变化。

获取 Google Shopping 卖家结果（按任务 ID） ​

请求参数 ​

请求示例 ​

cURL ​

TypeScript ​

Python ​

响应说明 ​

顶层响应字段 ​

任务字段 ​

data 字段 ​

result 字段 ​

结果基础字段 ​

rating 商品评分字段 ​

items 数组 ​

通用排名字段 ​

shops_list 专有字段 ​

buy_on_google 专有字段 ​

商品库存状态 ​

卖家评分字段 ​

响应示例 ​

错误处理 ​

获取已完成任务 ​

沙盒测试 ​

实用场景 ​