更新日志新功能

Commerce Search 和 Commerce Product 现已支持 Google Shopping

API
带有 COMMERCE_SERP 和 COMMERCE_PRODUCT 标签的 Google Shopping，cerave moisturizing cream 搜索的前三个商品及其价格、评分和商家，以及第一个商品的四个商家价格（从 Target 的 4.19 美元到 CVS Pharmacy 的 7.49 美元）

用 Commerce Search 搜索美国 Google 购物标签页，再用 Commerce Product 读取商品，获得 Google 列出的每个商家的价格、库存和商品页面。

获得的结果

  • COMMERCE_SERP 中的 site: "google_shopping"：一个任务搜索美国的 Google 购物标签页，按 Google 的顺序返回最多 40 个商品，每个商品带有 rank、productId、title、price 和 url。
  • seller：商品卡片上显示的商家，例如 Target、Ulta Beauty 或 Walmart；卡片显示时还有 rating、reviewCount 和 imageUrl。
  • COMMERCE_PRODUCT 通过搜索结果中的 url 读取商品，返回 title、price、seller、inStock、rating、images 和 specs。
  • offers：Google 为该商品列出的全部商家，每个商家带有 seller、title、price、currency、inStock 以及该商家商品页面的 url。

工作原理

每次搜索读取 Google 在美国为该查询显示的购物标签页，即 google.com/search?udm=28 页面。商品 url 打开该搜索结果页，并在 # 后带有商品 ID 和标题，COMMERCE_PRODUCT 靠它再次找到同一商品。

读取商品时，任务打开搜索结果页，点击该商品，读取 Google 显示的面板：商家、描述、规格和照片。商品的 price、listPrice、seller 和 inStock 来自第一个商家，即 Google 标为最低价的商家。Google 会在一天内调整宽泛查询的结果，因此任务先按查询、再按标题查找商品。

reviewCount 带有 Google 显示的精确数量，最多到 1,000；更多时 Google 会写成 17K 这样的简写。

应用场景

  • 查看哪个商家拿下了你的商品在 Google 上的最低价，以及其他商家贵出多少。
  • 每天追踪 Google Shopping 在品类查询中排名靠前的商品，并与同一查询在 Amazon、Walmart 和 Target 的排名并排比较。
  • 一次收集销售某个商品的所有商家页面，再用 Commerce Product 读取 Target、Walmart 或 Ulta 的页面。

发送请求

在 Authorization 请求头中带上 API 密钥发送请求。

curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taskType": "COMMERCE_SERP",
    "payload": {
      "site": "google_shopping",
      "query": "cerave moisturizing cream",
      "limit": 10
    }
  }'

请求字段

taskTypestring必填
要运行的引擎，例如 CHATGPT 或 GOOGLE。
payload.sitestring必填
要搜索的电商平台，例如 amazon、coupang 或 rakuten。21 个取值列在引擎说明中。
payload.querystring必填
按购物者在平台搜索框中输入的方式写的搜索词，1 到 500 个字符。
payload.countrystring
平台所在的国家，例如 amazon 为 US，coupang 为 KR。省略时也使用此值。
payload.limitinteger
返回的商品数，1 到 40，默认 20。
webhook.urlstring
你服务器上的 HTTPS 地址。任务完成后立即把结果推送到这里。

响应

完成的任务如下所示，已截取部分内容。

JSON
{
  "success": true,
  "task": {
    "id": "b02ec42c-2ea1-4a6f-ba70-1b3099b8ceff",
    "taskType": "COMMERCE_SERP",
    "status": "COMPLETED",
    "createdAt": "2026-10-23T01:32:45.682Z"
  },
  "credits": { "creditsToCharge": 3, "creditsCharged": 3 },
  "response": {
    "site": "google_shopping",
    "query": "cerave moisturizing cream",
    "country": "US",
    "returnedCount": 10,
    "products": [
      {
        "rank": 1,
        "productId": "16245040360969784676",
        "title": "CeraVe Moisturizing Cream",
        "url": "https://www.google.com/search?q=cerave+moisturizing+cream&udm=28&gl=us&hl=en#product=16245040360969784676&title=CeraVe+Moisturizing+Cream",
        "price": 4.19,
        "currency": "USD",
        "seller": "Target",
        "rating": 4.7
      },
      {
        "rank": 2,
        "productId": "5074307725217910967",
        "title": "CeraVe Moisturizing Cream Pump",
        "url": "https://www.google.com/search?q=cerave+moisturizing+cream&udm=28&gl=us&hl=en#product=5074307725217910967&title=CeraVe+Moisturizing+Cream+Pump",
        "price": 17.99,
        "currency": "USD",
        "seller": "Target",
        "rating": 4.7
      },
      "…"
    ]
  }
}
task.statusstring
依次为 QUEUED、PROCESSING，最终为附带回答的 COMPLETED 或附带 error 的 FAILED。
credits.creditsChargedinteger
已完成任务扣除的积分。失败的任务为 0。
response.returnedCountinteger
products 中的商品数量。
response.productsarray
按 Google 顺序排列的商品：rank、productId、title、url、price、currency 和 seller；商品卡片显示时，还有 rating、reviewCount 和 imageUrl。

获取结果

请求会立即返回 status 为 QUEUED 的任务。用 GET /v1/async/task/{id} 轮询，直到 status 变为 COMPLETED 或 FAILED；或者加上 webhook.url，在服务器上接收同样的 task、credits 和 response。任务结束后，结果保留 24 小时供查询。

curl https://api.querying.ai/v1/async/task/$TASK_ID \
  -H "Authorization: Bearer $QUERYING_API_KEY"

读取商品

把搜索结果中的商品 url 传给 COMMERCE_PRODUCT。下面是读取上面第一个商品的结果，已截短。

curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taskType": "COMMERCE_PRODUCT",
    "payload": {
      "url": "https://www.google.com/search?q=cerave+moisturizing+cream&udm=28&gl=us&hl=en#product=16245040360969784676&title=CeraVe+Moisturizing+Cream"
    }
  }'
taskTypestring必填
要运行的引擎，例如 CHATGPT 或 GOOGLE。
payload.urlstring必填
来自 google_shopping Commerce Search 结果的商品 url。它打开搜索结果页，并在 # 后带有商品 ID 和标题。
JSON
{
  "success": true,
  "task": {
    "id": "9ee619d2-c87f-47ab-93cd-215ef3671734",
    "taskType": "COMMERCE_PRODUCT",
    "status": "COMPLETED",
    "createdAt": "2026-10-23T01:36:00.797Z"
  },
  "credits": { "creditsToCharge": 3, "creditsCharged": 3 },
  "response": {
    "site": "google_shopping",
    "country": "US",
    "url": "https://www.google.com/search?q=cerave+moisturizing+cream&udm=28&gl=us&hl=en#product=16245040360969784676&title=CeraVe+Moisturizing+Cream",
    "productId": "16245040360969784676",
    "title": "CeraVe Moisturizing Cream",
    "price": 4.19,
    "currency": "USD",
    "inStock": true,
    "seller": "Target",
    "rating": 4.7,
    "images": [
      "https://encrypted-tbn3.gstatic.com/shopping?q=tbn:ANd9GcTdoC3RoTxQCkmpSUypL2HqkAR300eBZ_E3W2NCfz2MP4541LroFfQ8ZzNM2XIpm_xS_3c4dZU4_LMYtqQjE89N-Z8wH4Y_gA",
      "…"
    ],
    "specs": [
      { "name": "Benefit", "value": "Moisturizing" },
      { "name": "Form", "value": "Cream" },
      "…"
    ],
    "offers": [
      {
        "seller": "Target",
        "title": "CeraVe Moisturizing Face & Body Cream for Normal to Dry Skin – 1.89 fl oz",
        "url": "https://www.target.com/p/cerave-moisturizing-face-38-body-cream-for-normal-to-dry-skin-8211-1-89-fl-oz/-/A-86467779",
        "price": 4.19,
        "currency": "USD",
        "inStock": true
      },
      {
        "seller": "Ulta Beauty",
        "title": "CeraVe Moisturizing Cream Body and Face Moisturizer - 1.8 oz",
        "url": "https://www.ulta.com/p/moisturizing-cream-body-face-moisturizer-xlsImpprod3530069?sku=2532670",
        "price": 6.99,
        "currency": "USD",
        "inStock": true
      },
      "…"
    ]
  }
}
response.pricenumber
页面首先展示的商品在优惠券和运费之前的价格，单位为 currency（ISO 4217）。listPrice 是高于 price 时页面划线显示的原价。
response.offersarray
Google 为该商品列出的商家，按 Google 顺序：seller、title、price、currency 和商家商品页面的 url；商家行显示时，还有 listPrice 和 inStock。第一个商家是 Google 的最低价。

错误

VALIDATION_ERRORHTTP 422
site 不在 21 家平台之内、query 为空或超过 500 个字符、limit 不在 1 到 40 之间，或 payload 带有其他字段。details 会指明该字段。
VALIDATION_ERRORHTTP 422
缺少 url、超过 2,048 个字符或不是 18 家平台的商品页面，或 payload 带有 url 和 country 以外的字段。details 会指明该字段。
REGION_UNSUPPORTEDHTTP 422
country 与平台所在国家不同，例如 amazon 配 KR。
MISSING_API_KEYHTTP 401
缺少 Authorization 请求头，或密钥有误、已过期或已吊销。
INSUFFICIENT_CREDITSHTTP 402
余额低于任务价格。充值积分或升级套餐后再发送。

价格

每次完成的搜索和每次完成的商品读取都使用 3 个积分，与其他电商平台相同。积分在任务完成时扣除。

更多更新

接收最新消息

通过邮件接收产品更新。

RSS 订阅