Google Shopping 产品任务创建

POST /v3/merchant/google/products/task_post

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

/v3/merchant/google/products/task_post

用于为指定创建 Google Shopping 产品抓取任务，返回搜索结果中的产品标题、描述、排名、价格、评论数、评分及所属域名等信息。结果会根据指定的地点和语言返回。

任务支持两种执行优级：

1：普通优级，默认值
2：高优级，执行速度更快，可能产生更高费用

地点和语言可通过对应的列表接口查询：

/v3/merchant/google/locations
/v3/merchant/google/languages

计费与限制

本接口在创建任务时计费。
示例响应中的 cost: 0.001 美，按参考汇率换算后约为 ¥0.0072 / 次。
高优级任务可能产生额外费用。
depth过 40 时，如果返回 40 条结果，可能按额外搜索结果页计费。
实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。
所有请求体使用 UTF-8 编码的 JSON 数组。
每次请求最多提交 100 个任务。平台限流以认证说明中的 30/60/120 次/分钟规则为准。
单次请求 100 个任务时，出部分将返回错误码 40006。
创建任务后，可使用返回的任务 id 查询结果。
也可以通过 postback_url 或 pingback_url 接收任务完成通知。
如果接收服务器在 10 秒未返回响应，连接将因时中断，任务会转移到处理任务列表。

请求参数

请求体是 JSON 数组，每个数组代表一个任务。

参数	类型	填	说明
`keyword`	string	是	搜索，最多 700 个字符。参数中的 `%##` 会被解码，字符 `+` 会被解码为空格。如需在中传递 `%`，请写为 `%25`。
`url`	string	否	搜索查询的完整 URL。平台会从 URL 中解析参数。该方式处理复杂，且在 URL 中明确指定语言和地点，通常不建议使用。
`priority`	integer	否	任务优级：`1` 为普通优级，默认值；`2` 为高优级。
`location_name`	string	条件填	地点称。当未指定 `location_code` 或 `location_coordinate` 时填。示例：`London,England,United Kingdom`。
`location_code`	integer	条件填	地点代码。当未指定 `location_name` 或 `location_coordinate` 时填。示例：`2840`。
`location_coordinate`	string	条件填	地点 GPS 坐标，格式为 `latitude,longitude,radius`。经纬度最多 7 位小数，`radius` 最小值为 `199.9`。示例：`53.476225,-2.243572,200`。
`language_name`	string	条件填	语言称。当未指定 `language_code` 时填。示例：`English`。
`language_code`	string	条件填	语言代码。当未指定 `language_name` 时填。示例：`en`。
`se_domain`	string	否	搜索引擎域名。平台会根据地点和语言自动选择，也可以手动指定，例如 `google.co.uk`、`google.com.au`、`google.de`。
`depth`	integer	否	抓取深度，即需要从 Google Shopping 搜索结果中获取的结果数量。默认值为 `40`，最大值为 `120`。
`max_crawl_pages`	integer	否	最多抓取的搜索结果页数，最大值为 `7`。该参数与 `depth`合使用。
`search_param`	string	否	用于自定义搜索条件、筛选和排序的额外 URL 参数。
`price_min`	integer	否	返回产品的最低价格。指定后将忽略 `search_param`。示例：`5`。
`price_max`	integer	否	返回产品的最高价格。指定后将忽略 `search_param`。示例：`100`。
`sort_by`	string	否	结果排序方式。支持：`review_score`、`price_low_to_high`、`price_high_to_low`。指定后将忽略 `search_param`。
`tag`	string	否	用户自定义任务标识，最多 255 个字符。该值会原样返回在响应的 `data` 对象中。
`postback_url`	string	否	任务完成后，平台通过 POST 请求将结果以 gzip 压缩格式发送到该地址。支持使用 `$id` 和 `$tag` 占位符。
`postback_data`	string	条件填	`postback_url` 的返回数据类型。指定 `postback_url` 时填，可选值：`advanced`、`html`。
`pingback_url`	string	否	任务完成后，平台向该地址发送 GET 请求通知。支持使用 `$id` 和 `$tag` 占位符。

`url` 示例

text

https://www.google.com/search?q=fish&hl=en&gl=US&gws_rd=cr&uule=w+CAIQIFISCQs2MuSEtepUEUK33kOSuTsc

`search_param` 支持的常用参数

参数示例	说明
`&tbs=ppr_min:45`	搜索价格高于 45 的产品
`&tbs=ppr_max:50`	搜索价格低于 50 的产品
`&tbs=p_ord:p`	按价格从低到高排序
`&tbs=p_ord:pd`	按价格从高到低排序
`&tbs=p_ord:rv`	按评论评分排序
`&tbs=ppr_max:50,p_ord:rv`	最高价格为 50，并按评论评分排序
`&udm=28`	使用新版 Google Shopping 结果格式，默认返回 40 条结果；最大 `depth` 为 200。使用该参数时，`url` 中不得同时 `tbm=shop`。
`&shoprs=$value`	使用新版 Shopping 结果格式的高级筛选和排序。`$value` 应替换为 Protobuf Base64 格式字符串。

> 如果请求中指定了 price_min、price_max 或 sort_by，search_param 中的值将被忽略。

回调地址占位符

postback_url 和 pingback_url 支持以下占位符：

$id：任务 ID
$tag：经过 URL 编码的任务标签

示例：

text

https://your-server.com/postbackscript?id=$id&tag=$tag
https://your-server.com/pingscript?id=$id&tag=$tag

回调地址中的特殊字符会进行 URL 编码，例如 # 会编码为 %23。

请求示例

curl

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/merchant/google/products/task_post" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "location_name": "United States",
      "language_name": "English",
      "keyword": "iphone"
    },
    {
      "location_name": "United States",
      "language_name": "English",
      "keyword": "hedonism wines",
      "price_min": 10,
      "sort_by": "price_low_to_high",
      "priority": 2,
      "tag": "some_string_123",
      "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
    },
    {
      "location_name": "United States",
      "language_name": "English",
      "keyword": "iphone",
      "postback_data": "html",
      "postback_url": "https://your-server.com/postbackscript"
    }
  ]'

Python

python

import requests

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

payload = [
    {
        "location_name": "United States",
        "language_name": "English",
        "keyword": "iphone"
    },
    {
        "location_name": "United States",
        "language_name": "English",
        "keyword": "iphone",
        "price_min": 10,
        "sort_by": "price_low_to_high",
        "priority": 2,
        "tag": "some_string_123",
        "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
    },
    {
        "location_name": "United States",
        "language_name": "English",
        "keyword": "iphone",
        "postback_data": "html",
        "postback_url": "https://your-server.com/postbackscript"
    }
]

response = requests.post(
    url,
    headers={
        "Authorization": "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json"
    },
    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",
    keyword: "iphone"
  },
  {
    location_name: "United States",
    language_name: "English",
    keyword: "hedonism wines",
    price_min: 10,
    sort_by: "price_low_to_high",
    priority: 2,
    tag: "some_string_123",
    pingback_url: "https://your-server.com/pingscript?id=$id&tag=$tag"
  },
  {
    location_name: "United States",
    language_name: "English",
    keyword: "iphone",
    postback_data: "html",
    postback_url: "https://your-server.com/postbackscript"
  }
];

axios.post(
  "https://api.seermartech.cn/v3/merchant/google/products/task_post",
  payload,
  {
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json"
    }
  }
)
.then((response) => {
  const result = response.data;

  if (result.status_code === 20000) {
    console.log(result);
  } else {
    console.error(
      `请求失败，错误码：${result.status_code}，消息：${result.status_message}`
    );
  }
})
.catch((error) => {
  console.error(error);
});

响应说明

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

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	请求整体状态码。`20000` 表示成功。
`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 格式。
`tasks[].status_code`	integer	单个任务的状态码，通常在 `10000–60000` 范围。
`tasks[].status_message`	string	单个任务的状态描述。
`tasks[].time`	string	单个任务的执行耗时，单位为秒。
`tasks[].cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks[].result_count`	integer	`result` 数组中的数量。创建任务时通常为 `0`。
`tasks[].path`	array	请求路径信息。
`tasks[].data`	object	创建任务时提交的参数。
`tasks[].result`	array/null	任务结果。创建任务接口返回时通常为 `null`。

响应示例

json

{
  "version": "0.1.20200416",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.0712 sec.",
  "cost": 0.001,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "060 contribuir-example-task-id",
      "status_code": 20100,
      "status_message": "Task Created.",
      "time": "0.0100 sec.",
      "cost": 0.001,
      "result_count": 0,
      "path": [
        "v3",
        "merchant",
        "google",
        "products",
        "task_post"
      ],
      "data": {
        "api": "merchant",
        "function": "products",
        "se": "google",
        "language_code": "en",
        "location_code": 2840,
        "keyword": "iphone",
        "price_min": "5",
        "se_type": "shopping",
        "device": "desktop",
        "os": "windows"
      },
      "result": null
    }
  ]
}

> tasks[].id 为示例值，响应会返回真实任务 ID。

常见状态码

状态码	说明
`20000`	请求成功
`40006`	单次请求提交的任务数量 100 个
`20100`	任务已创建

任务级错误码和通用错误码请参考错误码文档。

实用场景

监控重点的 Google Shopping 产品排名：定期抓取目标的产品排名、价格和域名，评估商品在购物搜索结果中的表现。
比较竞品价格与评分：使用 price_min、price_max 和 sort_by 获取竞品产品列表，为价格策略和商品定位提供依据。
分析不同地区的购物搜索差异：通过 location_name、location_code 或 location_coordinate 对比不同市场的产品、价格和评论表现，支持区域化 SEO 与投放决策。
筛选高评价或低价产品：使用 search_param 或 sort_by 按评论评分、价格升序或降序整理结果，快速识别市场中的高竞争商品。
批量建立商品 SERP 监测任务：一次提交多个，并通过 pingback_url 或 postback_url 接收完成通知，降低批量监测的轮询成本。

Google Shopping 产品任务创建 ​

计费与限制 ​

请求参数 ​

url 示例 ​

search_param 支持的常用参数 ​

回调地址占位符 ​

请求示例 ​

curl ​

Python ​

TypeScript ​

响应说明 ​

响应示例 ​

常见状态码 ​

实用场景 ​