现已支持 20 家电商平台的商品搜索

在 Amazon、Walmart、Coupang、Olive Young、Rakuten、Flipkart、Zalando 等 5 个国家的 20 家电商平台搜索，以同一格式获取各平台的商品排名，以及价格、评分和评论数。

获得的结果

• COMMERCE_SERP：一个任务搜索一家平台，用 payload.site 从美国、韩国、日本、印度和德国的 20 家平台中选择。
• products：平台针对搜索词给出的商品排名，最多 40 个商品，每个商品都有 rank、productId、title 和 url。
• price 为数字，并附带 currency；搜索结果页显示时，还会返回 rating、reviewCount、brand 和 imageUrl。
• 所有平台使用相同的商品字段，一个解析器即可读取 Amazon、Coupang、Rakuten 和 Zalando。

支持的平台

• 美国（US）：Amazon amazon、Walmart walmart、Target target、eBay ebay、AliExpress aliexpress、Sephora sephora、Ulta ulta
• 韩国（KR）：Coupang coupang、Olive Young oliveyoung、11st 11st、Lotte ON lotteon、Musinsa musinsa、Kurly kurly
• 日本（JP）：Rakuten rakuten、Yahoo! Shopping yahoo_shopping、Qoo10 qoo10
• 印度（IN）：Flipkart flipkart、Myntra myntra、Nykaa nykaa
• 德国（DE）：Zalando zalando

工作原理

每个任务读取该平台所在国家针对搜索词显示的第一页搜索结果，并按平台的默认排序返回商品。除 Coupang 外，所有平台都会去掉标为广告的商品，其余商品按页面顺序计入 rank。

productId 是平台自己的商品 ID：Amazon 为 ASIN，eBay 为商品编号，Rakuten 为 shop:item。price 是以商品自身 currency（ISO 4217）表示的数字，不同规格价格不同时取最低价。显示评分的平台以五分制返回 rating；Kurly 和 Zalando 以价格和商品名称展示商品。

平台把搜索转到其他页面时，返回该页面的商品：Ulta 会把部分品牌名转到品牌页，Target 会把部分搜索转到相关搜索词，Nykaa 在搜索类目名称时显示类目页。没有找到任何商品的搜索以失败任务结束。

应用场景

• 每天追踪自家商品在 Amazon、Walmart 和 Target 品类搜索中的排名。
• 把自家商品的价格、评分和评论数与排名相近的商品比较。
• 用同一种请求格式，在 Olive Young、Rakuten、Nykaa 和 Zalando 上跟踪美妆或时尚产品线。
• 把同一搜索词的平台排名与 ChatGPT 或 Google AI Mode 的回答放在一起，查看购物者在各处看到哪些商品。

发送请求

在 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": "target", "query": "sunscreen", "limit": 10 }
  }'

请求字段

taskTypestring必填

要运行的引擎，例如 CHATGPT 或 GOOGLE。

payload.sitestring必填

要搜索的电商平台，例如 amazon、coupang 或 rakuten。20 个取值列在引擎说明中。

payload.querystring必填

按购物者在平台搜索框中输入的方式写的搜索词，1 到 500 个字符。

payload.countrystring

平台所在的国家，例如 amazon 为 US，coupang 为 KR。省略时也使用此值。

payload.limitinteger

返回的商品数，1 到 40，默认 20。

webhook.urlstring

你服务器上的 HTTPS 地址。任务完成后立即把结果推送到这里。

响应

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

{
  "success": true,
  "task": {
    "id": "fa04f93f-babe-4d50-9549-8b7100261fee",
    "taskType": "COMMERCE_SERP",
    "status": "COMPLETED",
    "createdAt": "2026-10-22T00:05:55.416Z"
  },
  "credits": { "creditsToCharge": 3, "creditsCharged": 3 },
  "response": {
    "site": "target",
    "query": "sunscreen",
    "country": "US",
    "returnedCount": 10,
    "products": [
      {
        "rank": 1,
        "productId": "76545827",
        "title": "La Roche Posay Anthelios Melt in Milk Sunscreen Lotion - SPF 100 - 3.0 fl oz",
        "brand": "La Roche Posay",
        "url": "https://www.target.com/p/la-roche-posay-anthelios-melt-in-milk-sunscreen-lotion-spf-100-3-0-fl-oz/-/A-76545827",
        "price": 20.99,
        "currency": "USD",
        "rating": 4.54,
        "reviewCount": 995
      },
      {
        "rank": 2,
        "productId": "80839020",
        "title": "Neutrogena Beach Defense Sunscreen Lotion - SPF 70 - 1 fl oz",
        "brand": "Neutrogena",
        "url": "https://www.target.com/p/neutrogena-beach-defense-sunscreen-lotion-spf-70-1-fl-oz/-/A-80839020",
        "price": 1.99,
        "currency": "USD",
        "rating": 4.59,
        "reviewCount": 1580
      },
      "…"
    ]
  }
}

task.statusstring

依次为 QUEUED、PROCESSING，最终为附带回答的 COMPLETED 或附带 error 的 FAILED。

credits.creditsChargedinteger

已完成任务扣除的积分。失败的任务为 0。

response.returnedCountinteger

products 中的商品数量。

response.productsarray

按平台顺序排列的商品：rank、productId、title 和 url；搜索结果页显示时，还有 price、currency、rating、reviewCount、imageUrl 和 brand。

获取结果

请求会立即返回 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"

错误

VALIDATION_ERRORHTTP 422

site 不在 20 家平台之内、query 为空或超过 500 个字符、limit 不在 1 到 40 之间，或 payload 带有其他字段。details 会指明该字段。

REGION_UNSUPPORTEDHTTP 422

country 与平台所在国家不同，例如 amazon 配 KR。

MISSING_API_KEYHTTP 401

缺少 Authorization 请求头，或密钥有误、已过期或已吊销。

INSUFFICIENT_CREDITSHTTP 402

余额低于任务价格。充值积分或升级套餐后再发送。

价格

所有平台每完成一次搜索消耗 3 积分。积分在任务完成时扣除。