按任务 ID 获取 Google Shopping 商品高级结果

GET /v3/merchant/google/products/tasks_ready

本接口使用 GET 方法，通过任务 ID 获取 Google Shopping 商品高级结果。

请求方法与路径：

text

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

计费说明

提交任务时会产生费用。任务结果可在提交后的 30 天重复获取，获取结果本身不额外收费。

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

请求参数

参数通过 URL 路径传递。

参数	类型	说明
`id`	string	任务唯一标识，UUID 格式。任务提交成功后，可在 30 天使用该 ID 获取结果。

请求示例

curl

bash

curl --location --request GET \
  "https://api.seermartech.cn/v3/merchant/google/products/task_get/advanced/04171054-0696-0179-0000-e56ea58342c5" \
  --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/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.response?.data || error.message);
  });

Python

python

import requests

task_id = "04171054-0696-0179-0000-e56ea58342c5"
url = (
    "https://api.seermartech.cn/v3/merchant/google/products/"
    f"task_get/advanced/{task_id}"
)

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

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

响应结构

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

顶层字段

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	总体响应状态码。通常 `20000` 表示成功。
`status_message`	string	总体状态说明。
`time`	string	请求执行耗时，例如 `0.1346 sec.`。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`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 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`result_count`	integer	`result` 数组中的数量。
`path`	array	当前请求的 URL 路径信息。
`data`	object	创建任务时提交的参数。
`result`	array	Google Shopping 结果数组。

data 通常以下任务参数：

字段	类型	说明
`se_type`	string	搜索类型，例如 `shopping`。
`se`	string	搜索引擎，例如 `google`。
`api`	string	API 模块，例如 `merchant`。
`function`	string	功能名称，例如 `products`。
`keyword`	string	查询。
`language_code`	string	语言代码。
`location_code`	integer	地理位置代码。
`price_min`	string	商品最低价格筛选条件。
`price_max`	string	商品最高价格筛选条件，如请求时提供。
`device`	string	设备类型，例如 `desktop` 或 `mobile`。
`os`	string	操作系统，例如 `windows` 或 `android`。

`result` 字段

字段	类型	说明
`keyword`	string	POST 请求中的。返回时会对 URL 编码进行解码，`+` 会被解码为空格。
`type`	string	请求中的搜索类型。
`se_domain`	string	请求中的搜索引擎域名。
`location_code`	integer	请求中的地理位置代码。
`language_code`	string	请求中的语言代码。
`check_url`	string	Google Shopping 结果页的直接 URL，可用于核验结果准确性。
`datetime`	string	结果获取时间，UTC 格式，例如 `2019-11-15 12:57:46 +00:00`。
`spell`	object	搜索引擎自动纠错信息。
`item_types`	array	当前 Shopping 搜索结果中的结果类型。
`items_count`	integer	`items` 数组中的数量。
`items`	array	搜索结果数组。

`spell`

当搜索引擎对查询进行了纠正时返回。

字段	类型	说明
`keyword`	string	自动纠正后的，结果将基于该提供。
`type`	string	自动纠错类型。可选值：`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
google_shopping_carousel
related_searches

搜索结果通用字段

以下字段可能出现在 items 中：

字段	类型	说明
`type`	string	结果类型。
`rank_group`	integer	同类型中的组排名。不同类型之间不会连续计算该排名。
`rank_absolute`	integer	在整个 Google Shopping 搜索结果中的绝对排名。
`position`	string	素在搜索结果中的位置，可为 `left` 或 `right`。
`xpath`	string	素在页面中的 XPath。
`title`	string	素或商品标题。
`items`	array	素中的附加商品或；没有时为 `null`。

商品字段

商品主要出现在以下类型中：

google_shopping_sponsored_carousel_element
google_shopping_carousel_element
google_shopping_serp

字段	类型	说明
`title`	string	商品标题。
`tags`	array	商品标签。
`seller`	string	销售该商品的商家名称。
`price`	float	商品价格，例如 `384.99`。
`old_price`	float	商品原价；商品发生降价时返回。
`price_multiplier`	integer	分期付款对应的月数。
`currency`	string	ISO 4217 货币代码，例如 `USD`。
`description`	string	商品描述。
`url`	string	商家网站上的商品 URL。该字段已弃用，通常返回 `null`。
`shopping_url`	string	Google Shopping 商品页 URL。
`product_id`	string	Google Shopping 商品唯一标识。该值由 Google 动态分，无固定完整枚举；无值时返回 `null`。
`data_docid`	string	搜索结果的唯一标识，由 Google 动态分。
`gid`	string	Google Shopping局商品标识。无值时返回 `null`。
`seller`	string	商品对应的销售商名称。
`product_images`	array	商品图片 URL 数组，第一个 URL 为主图。
`shop_ad_aclk`	string	广告点击引用参数。可用于调用 `/v3/merchant/google/sellers/ad_url/` 获取广告 URL。
`reviews_count`	integer	Google Shopping 用户评论数量，无值时返回 `null`。
`is_best_match`	boolean	是否带有“最佳匹”标签，无值时返回 `null`。
`additional_specifications`	object	商品附加参数，可用于调用 Google Shopping 商品规格或商家接口获取更多信息。

additional_specifications 可用于以下接口：

text

POST /v3/merchant/google/products/task_post/
POST /v3/merchant/google/sellers/task_post/

`product_rating` 商品评分

字段	类型	说明
`type`	string	评分类型，通常为 `rating_element`。
`position`	string	评分位置，可为 `left` 或 `right`。
`rating_type`	string	评分类型：`Max5`、`Percents` 或 `CustomMax`。
`value`	string	评分值。
`votes_count`	integer	评分或评论数量。
`rating_max`	integer	当前评分类型的最大值。

`shop_rating` 商家评分

shop_rating 的字段结构与 product_rating 基本一致，用于表示商家基于用户评价计算的评分。

字段	类型	说明
`type`	string	评分类型，通常为 `rating_element`。
`rating_type`	string	评分类型：`Max5`、`Percents` 或 `CustomMax`。
`value`	string	评分值。
`votes_count`	integer	用户评价数量。
`rating_max`	integer	当前评分类型的最大值。
`position`	string	评分位置，可为 `left` 或 `right`。

##送信息

`delivery_info`

字段	类型	说明
`delivery_message`	string	商家展示的说明，例如“”。
`delivery_price`	object	根据请求中指定的地理位置计算的费用。时为 `null`。

`delivery_price`

字段	类型	说明
`current`	float	当前价格。
`regular`	float	未折扣的常规价格。
`max_value`	float	未折扣价格的最大值。
`currency`	string	ISO 4217 货币代码。
`is_price_range`	boolean	是否为价格区间。
`displayed_price`	string	Google Shopping 页面展示的价格文本。

特殊优惠信息

`special_offer_info`

字段	类型	说明
`title`	string	特殊优惠标题。
`sub_title`	string	特殊优惠副标题。
`fixed_discount`	integer	固定金额折扣。
`fixed_discount_currency`	string	固定金额折扣的货币。
`percentage_discount`	integer	折扣百分比。
`coupon_code`	string	优惠券代码。
`coupon_info`	string	优惠券说明。
`url`	string	特殊优惠页面 URL。该字段已弃用，通常返回 `null`。
`domain`	string	特殊优惠页面域名。该字段已弃用，通常返回 `null`。

各类结果

`google_shopping_sponsored_carousel`

表示 Google Shopping 赞助商品轮播模块。该对象通常：

type
rank_group
rank_absolute
position
xpath
title
items

，items 中的类型为 google_shopping_sponsored_carousel_element，商品字段：

xpath
title
tags
seller
price
currency
product_rating
product_images
shop_ad_aclk
delivery_info
special_offer_info

`google_shopping_carousel`

表示 Google Shopping 商品轮播模块。该对象：

type
rank_group
rank_absolute
position
xpath
title
items

，items 中的类型为 google_shopping_carousel_element，除通用商品字段外，还可能：

shopping_url
product_id
data_docid
gid
delivery_info
special_offer_info

`google_shopping_serp`

表示 Google Shopping 常规商品结果。除通用排名字段外，还可能：

domain
title
description
url
shopping_url
tags
price
price_multiplier
old_price
currency
product_id
data_docid
seller
additional_specifications
reviews_count
is_best_match
product_rating
shop_rating
product_images
shop_ad_aclk
delivery_info
stores_count_info
gid

`google_shopping_paid`

表示付费商品或广告结果。

字段	类型	说明
`type`	string	固定为 `google_shopping_paid`。
`rank_group`	integer	同类型中的组排名。
`rank_absolute`	integer	在整个搜索结果中的绝对排名。
`position`	string	结果位置，可为 `left` 或 `right`。
`xpath`	string	页面 XPath。
`domain`	string	搜索结果中的域名。
`title`	string	商品或广告标题。
`description`	string	商品或广告描述。
`url`	string	商家网站 URL。该字段已弃用，通常返回 `null`。
`shop_ad_aclk`	string	广告点击引用参数，可用于获取广告 URL。

`related_searches`

表示搜索词模块。

字段	类型	说明
`type`	string	固定为 `related_searches`。
`rank_group`	integer	同类型中的组排名。
`rank_absolute`	integer	在整个搜索结果中的绝对排名。
`position`	string	结果位置，可为 `left` 或 `right`。
`xpath`	string	页面 XPath。
`items`	array	列表；无结果时为 `null`。

商家数量信息

`stores_count_info`

用于描述提供同一商品的商家数量。

字段	类型	说明
`count`	string	提供该商品的商家数量。
`displayed_text`	string	Google Shopping 页面展示的原始文本。
`count_from_text`	boolean	数量是否从展示文本中提取。若页面 HTML 中存在准确数量，则为 `false`；否则从 `displayed_text` 中提取时为 `true`。

响应示例

json

{
  "version": "0.1.20210617",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.1346 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "04171054-0696-0179-0000-e56ea58342c5",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.1200 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "merchant",
        "google",
        "products",
        "task_get",
        "advanced"
      ],
      "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": [
        {
          "keyword": "buy iphone",
          "type": "shopping",
          "se_domain": "google.com",
          "location_code": 2840,
          "language_code": "en",
          "check_url": "https://www.google.com/search?tbm=shop&q=buy+iphone",
          "datetime": "2019-11-15 12:57:46 +00:00",
          "spell": null,
          "item_types": [
            "google_shopping_serp",
            "google_shopping_carousel",
            "related_searches"
          ],
          "items_count": 160,
          "items": [
            {
              "type": "google_shopping_serp",
              "rank_group": 1,
              "rank_absolute": 3,
              "position": "left",
              "xpath": "/html/body/div/div/div",
              "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",
              "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": "related_searches",
              "rank_group": 223,
              "rank_absolute": 82,
              "position": "right",
              "xpath": "XPath1f2a2c1c-d234-4fb5-ac16-06f7c241b07c",
              "items": [
                "buy iphone online",
                "iphone deals"
              ]
            }
          ]
        }
      ]
    }
  ]
}

状态码与异常处理

请根据以下字段判断请求和任务是否成功：

顶层 status_code
tasks[].status_code
status_message
tasks_error
result

建议在客户端中处理以下：

HTTP 请求失败。
顶层 status_code 非 20000。
单个任务的 status_code 表示错误。
result 为空或为 null。
部分任务成功、部分任务失败。

任务结果获取流程

如需批量获取已完成任务，可调用：

text

GET /v3/merchant/google/products/tasks_ready

随后根据返回的任务结果地址，或直接拼接任务 ID 调用：

text

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

测试接口：

text

https://sandbox.seermartech.cn/v3/merchant/google/products/task_get/advanced/00000000-0000-0000-0000-000000000000

测试环境会返回虚拟数据的完整字段结构，不产生费用。

实用场景

监控商品搜索排名：定期获取商品在 Google Shopping 中的绝对排名和组排名，评估商品与竞争表现。
比较竞品价格与商家数量：分析 price、old_price、seller 和 stores_count_info，识别价格差异和市场供给。
跟踪促销与优惠券：提取 special_offer_info、折扣比例和优惠券代码，监测竞品促销策略并优化自身活动。
评估商品口碑：结合 product_rating、shop_rating 和 reviews_count，筛选高评分商品或分析竞品用户反馈。
分析竞争力：比较 delivery_info 和 delivery_price，评估不同商家的成本、策略及地域竞争优势。

按任务 ID 获取 Google Shopping 商品高级结果 ​

计费说明 ​

请求参数 ​

请求示例 ​

curl ​

TypeScript ​

Python ​

响应结构 ​

顶层字段 ​

tasks素字段 ​

result 字段 ​

spell ​

item_types ​

搜索结果通用字段 ​

商品字段 ​

product_rating 商品评分 ​

shop_rating 商家评分 ​

delivery_info ​

delivery_price ​

特殊优惠信息 ​

special_offer_info ​

各类结果 ​

google_shopping_sponsored_carousel ​

google_shopping_carousel ​

google_shopping_serp ​

google_shopping_paid ​

related_searches ​

商家数量信息 ​

stores_count_info ​

响应示例 ​

状态码与异常处理 ​

按任务 ID 获取 Google Shopping 商品高级结果

计费说明

请求参数

请求示例

curl

TypeScript

Python

响应结构

顶层字段

`tasks`素字段

`result` 字段

`spell`

`item_types`

搜索结果通用字段

商品字段

`product_rating` 商品评分

`shop_rating` 商家评分

`delivery_info`

`delivery_price`

特殊优惠信息

`special_offer_info`

各类结果

`google_shopping_sponsored_carousel`

`google_shopping_carousel`

`google_shopping_serp`

`google_shopping_paid`

`related_searches`

商家数量信息

`stores_count_info`

响应示例

状态码与异常处理