设置 Google Shopping 商品任务

POST /v3/merchant/google/product_info/task_post

本接口使用 POST 方法，路径为：

POST https://api.seermartech.cn/v3/merchant/google/product_info/task_post

用于提交 Google Shopping 商品查询任务。任务完成后，可获取商品描述、图片、评分、变体、规格及卖家等信息。提交任务时，至少指定以下字段之一：product_id、data_docid 或 gid。

计费说明

提交任务即产生费用，无论后续是否通过轮询或回调获取结果。

参考价约 ¥0.0072 / 次。高优级任务（priority=2）会产生额外费用。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

所有 POST 请求体使用 UTF-8 编码的 JSON 格式，并且顶层结构为数组：

json

[
  {
    "location_name": "United States",
    "language_name": "English",
    "product_id": "1113158713975221117"
  }
]

调用限制：

平台限流以认证说明中的 30/60/120 次/分钟规则为准。

每次 POST 请求最多 100 个任务。 -过 100 个任务的部分将返回错误码 40006。
任务提交成功后，可使用返回的任务 id 获取结果。
也可以在提交任务时指定 postback_url 或 pingback_url，由本平台在任务完成后发送通知。

如果回调服务器在 10 秒未返回响应，连接将因时中断，任务会转任务就绪列表。错误码和错误消息取决于回调服务器。

请求参数

每个任务对象支持以下字段。

参数	类型	说明
`product_id`	string	Google Shopping 商品唯一标识。未指定 `data_docid` 和 `gid` 时填。建议与 `data_docid`、`gid` 一起提交，以获得更稳定的结果。可通过 `/v3/merchant/google/products/task_post` 获取。示例：`4485466949985702538`
`data_docid`	string	SERP 数据的唯一标识。未指定 `product_id` 和 `gid` 时填。建议与 `product_id`、`gid` 一起提交。可通过 `/v3/merchant/google/products/task_post` 获取。示例：`13071766526042404278`
`gid`	string	Google Shopping局商品标识。未指定 `product_id` 和 `data_docid` 时填。建议与 `product_id`、`data_docid` 一起提交。可通过 `/v3/merchant/google/products/task_post` 获取。示例：`4702526954592161872`
`priority`	integer	任务优级。可选值：`1`：普通优级，默认值；`2`：高优级。高优级任务会额外计费。
`location_name`	string	地理位置完整名称。未指定 `location_code` 或 `location_coordinate` 时填。使用此字段后，无需再提交另外两个位置字段。可通过 `GET https://api.seermartech.cn/v3/merchant/google/locations` 获取可用位置名称。示例：`London,England,United Kingdom`
`location_code`	integer	地理位置代码。未指定 `location_name` 或 `location_coordinate` 时填。使用此字段后，无需再提交另外两个位置字段。可通过 `GET https://api.seermartech.cn/v3/merchant/google/locations` 获取。示例：`2840`
`location_coordinate`	string	地理位置 GPS 坐标，格式为 `"纬度,经度,半径"`。纬度和经度最多支持 7 位小数，半径最小值为 `199.9`。使用此字段后，无需再提交 `location_name` 或 `location_code`。示例：`53.476225,-2.243572,200`
`language_name`	string	语言完整名称。未指定 `language_code` 时填。使用此字段后，无需再提交 `language_code`。可通过 `GET https://api.seermartech.cn/v3/merchant/google/languages` 获取。示例：`English`
`language_code`	string	语言代码。未指定 `language_name` 时填。使用此字段后，无需再提交 `language_name`。可通过 `GET https://api.seermartech.cn/v3/merchant/google/languages` 获取。示例：`en`
`se_domain`	string	搜索引擎域名。可选。平台会根据位置和语言自动选择域名，也可以手动指定，例如：`google.co.uk`、`google.com.au`、`google.de`。
`tag`	string	用户自定义任务标识。可选，最大长度为 255 个字符。可用于任务与结果，提交的值会在响应的 `data` 对象中返回。
`postback_url`	string	任务结果接收地址。可选。任务完成后，本平台将以 POST 方式向该地址发送 gzip 压缩后的结果。URL 中可以使用 `$id` 和 `$tag` 占位符，平台发送请求前会替换为任务 ID 和经过 URL 编码的标签值。示例：`https://your-server.com/postbackscript?id=$id&tag=$tag`
`postback_data`	string	`postback_url` 的数据类型。可选。目前支持：`advanced`。
`pingback_url`	string	任务完成通知地址。可选。任务完成后，本平台将通过 GET 请求访问该地址。URL 中可以使用 `$id` 和 `$tag` 占位符。示例：`https://your-server.com/pingscript?id=$id&tag=$tag`

> postback_url 和 pingback_url 中的特殊字符会进行 URL 编码，例如 # 会被编码为 %23。

商品标识字段要求

product_id、data_docid、gid 三至少需要指定一个。为获得最佳结果，建议同时提交三个字段。商品标识可通过以下接口获取：

POST https://api.seermartech.cn/v3/merchant/google/products/task_post

位置字段要求

以下三个字段只能选择一个：

location_name
location_code
location_coordinate

如果同时未指定这三个字段，任务提交将失败。

语言字段要求

以下两个字段只能选择一个：

language_name
language_code

如果同时未指定这两个字段，任务提交将失败。

请求示例

curl

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/merchant/google/product_info/task_post" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "location_name": "United States",
      "language_name": "English",
      "product_id": "1113158713975221117"
    },
    {
      "location_name": "United States",
      "language_name": "English",
      "product_id": "1113158713975221117",
      "priority": 2,
      "tag": "some_string_123",
      "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
    },
    {
      "location_name": "United States",
      "language_name": "English",
      "product_id": "1113158713975221117",
      "postback_url": "https://your-server.com/postbackscript"
    }
  ]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/merchant/google/product_info/task_post"

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

payload = [
    {
        "location_name": "United States",
        "language_name": "English",
        "product_id": "1113158713975221117",
    },
    {
        "location_name": "United States",
        "language_name": "English",
        "product_id": "1113158713975221117",
        "priority": 2,
        "tag": "some_string_123",
        "pingback_url": (
            "https://your-server.com/pingscript"
            "?id=$id&tag=$tag"
        ),
    },
    {
        "location_name": "United States",
        "language_name": "English",
        "product_id": "1113158713975221117",
        "postback_url": "https://your-server.com/postbackscript",
    },
]

response = requests.post(url, headers=headers, json=payload)
result = response.json()

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        "请求失败。错误码：%s，消息：%s"
        % (result.get("status_code"), result.get("status_message"))
    )

TypeScript

typescript

import axios from "axios";

const payload = [
  {
    location_name: "United States",
    language_name: "English",
    product_id: "1113158713975221117",
  },
  {
    location_name: "United States",
    language_name: "English",
    product_id: "1113158713975221117",
    priority: 2,
    tag: "some_string_123",
    pingback_url:
      "https://your-server.com/pingscript?id=$id&tag=$tag",
  },
  {
    location_name: "United States",
    language_name: "English",
    product_id: "1113158713975221117",
    postback_url: "https://your-server.com/postbackscript",
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/merchant/google/product_info/task_post",
    payload,
    {
      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);
  });

响应说明

接口返回 JSON 数据 tasks 数组本次提交的任务信息。

顶层响应字段

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	通用状态码。成功时通常为 `20000`。完整错误码请参考 `/v3/appendix/errors`。
`status_message`	string	通用状态消息。
`time`	string	请求执行耗时，单位为秒。
`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` 数组中的数量。任务提交接口通常为 `0`。
`path`	array	请求路径信息。
`data`	object	提交任务时使用的参数。
`result`	array	任务结果数组。对于任务提交接口，该字段为 `null`。

响应示例

json

{
  "version": "0.1.20220627",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.0632 sec.",
  "cost": 0.0072,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "0829d9f5-7c7a-4c4d-9a3a-123456789abc",
      "status_code": 20100,
      "status_message": "Task Created.",
      "time": "0.0100 sec.",
      "cost": 0.0072,
      "result_count": 0,
      "path": [
        "v3",
        "merchant",
        "google",
        "product_info",
        "task_post"
      ],
      "data": {
        "api": "merchant",
        "function": "product_info",
        "se": "google",
        "language_code": "en",
        "location_code": 2840,
        "product_id": "1113158713975221117",
        "se_type": "product_info",
        "device": "desktop",
        "os": "windows"
      },
      "result": null
    }
  ]
}

任务提交成功后，可使用返回的 id 调用对应的任务结果接口，或 postback_url、pingback_url 回调通知。

错误处理

建议客户端根据顶层 status_code、任务级 status_code 和 status_message 分别处理请求错误与单任务错误。

常见：

请求体不是 JSON 数组。
单次请求 100 个任务，出部分返回 40006。
未提供 product_id、data_docid、gid 中的任何一个。
未提供有效的位置字段。
未提供有效的语言字段。
高优级任务参数或回调地址不正确。

完整错误码列表请参考 /v3/appendix/errors。

实用场景

采集竞品商品：批量提交竞品商品 ID，获取商品描述、图片、评分和规格，为竞品监测与选品决策提供数据。
监控 Google Shopping 卖家：定期查询同一商品的卖家信息，比较卖家覆盖与商品供应状态，支持价格和渠道分析。
分析商品变体表现：获取商品的颜色、尺寸等变体信息，识别不同变体的展示，优化商品目录结构。
构建商品数据资产：将商品结果与 SKU、品牌和类目数据，统一维护跨市场商品信息。
跟踪商品评分与变化：通过任务回调持续接收商品信息，发现评分、图片或描述变化，及时调整 SEO 和电商运营策略。

设置 Google Shopping 商品任务 ​

计费说明 ​

请求参数 ​

商品标识字段要求 ​

位置字段要求 ​

语言字段要求 ​

请求示例 ​

curl ​

Python ​

TypeScript ​

响应说明 ​

顶层响应字段 ​

tasks 数组字段 ​

响应示例 ​

错误处理 ​

实用场景 ​