> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Commerce Search API (COMMERCE_SERP)

> 每个任务搜索 Amazon、Walmart、eBay、AliExpress、Google Shopping、Sephora、Coupang、Olive Young、Rakuten、Flipkart、Zalando 等商城中的一个，以统一格式获取商品排名、价格、评分和评论数。

搜索一个商城的商品，通过异步任务 API 以 JSON 获取按排名排列的结果。用 `site` 选择商城，所有商城返回相同的商品字段。每次完成的搜索消耗 **3 积分**。

## 请求

```bash theme={"theme":"css-variables"}
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": "amazon", "query": "wireless earbuds", "limit": 20 } }'
```

提交任务后，轮询 `GET /v1/async/task/{id}` 或通过 webhook 接收。参见[异步任务](/zh/concepts/async-tasks.md)。

## 参数

* `site`：必填。从下表中选择要搜索的商城。
* `query`：必填搜索词，1-500 个字符。
* `country`：可选。默认是商城所在国家。其他国家会以 `422 REGION_UNSUPPORTED` 拒绝。
* `limit`：可选整数，范围 1-40，默认 20。

| `site` | 商城 | `country` |
| - | - | - |
| `amazon` | amazon.com | `US` |
| `walmart` | walmart.com | `US` |
| `target` | target.com | `US` |
| `ebay` | ebay.com | `US` |
| `aliexpress` | aliexpress.com | `US` |
| `google_shopping` | shopping.google.com | `US` |
| `sephora` | sephora.com | `US` |
| `ulta` | ulta.com | `US` |
| `coupang` | coupang.com | `KR` |
| `oliveyoung` | oliveyoung.co.kr | `KR` |
| `11st` | 11st.co.kr | `KR` |
| `lotteon` | lotteon.com | `KR` |
| `musinsa` | musinsa.com | `KR` |
| `kurly` | kurly.com | `KR` |
| `rakuten` | rakuten.co.jp | `JP` |
| `yahoo_shopping` | shopping.yahoo.co.jp | `JP` |
| `qoo10` | qoo10.jp | `JP` |
| `flipkart` | flipkart.com | `IN` |
| `myntra` | myntra.com | `IN` |
| `nykaa` | nykaa.com | `IN` |
| `zalando` | zalando.de | `DE` |

## 响应示例

```json theme={"theme":"css-variables"}
{
  "site": "amazon",
  "query": "wireless earbuds",
  "country": "US",
  "returnedCount": 1,
  "products": [
    {
      "rank": 1,
      "productId": "B0CHWRXH8B",
      "title": "Wireless Earbuds, Bluetooth 5.3 Headphones",
      "url": "https://www.amazon.com/dp/B0CHWRXH8B",
      "price": 24.99,
      "currency": "USD",
      "rating": 4.6,
      "reviewCount": 19406
    }
  ]
}
```

## 结果字段

* `site`、`query` 和 `country` 回显请求。`returnedCount` 是 `products` 中的商品数。
* 每个商品包含 `rank`、`productId`、`title` 和 `url`。`productId` 是商城自己的商品 ID（Amazon 上是 ASIN，eBay 上是商品编号，Rakuten 上是 `shop:item`）。`rank` 按商城的默认排序。除 Coupang 外，跳过商城标为广告的商品。
* `price`、`rating`、`reviewCount`、`imageUrl` 和 `brand` 在结果页显示时返回。`price` 是以该商品 `currency`（ISO 4217）计价的数字；Amazon 的一次搜索可能显示多种货币。不同规格价格不同时返回最低价。Target 的价格是其默认线上门店的价格。AliExpress 的价格是未登录的美国买家看到的售价。
* `rating` 为五分制。Kurly 和 Zalando 不显示评分，AliExpress 只显示星级而没有评分人数，999+ 这类缩写的数量不返回。`brand` 来自将品牌与商品名分开显示的 Target、Sephora、Ulta、Olive Young、Lotte ON、Musinsa、Yahoo! Shopping、Qoo10、Flipkart、Myntra、Nykaa 和 Zalando。
* 在 `google_shopping` 上，`productId` 是 Google 的商品 ID；Google 未归入商品的报价使用报价 ID。Google 页面不链接商品页或商家页，因此 `url` 是该商品所在的 Google Shopping 搜索结果页，末尾带有 `#product={productId}&title={title}`。将这个 `url` 传给 [Commerce Product](/zh/engines/commerce-product.md)，即可读取该商品的商家、规格和描述。`seller` 是 Google 首先列出的商家，`reviewCount` 仅在 Google 显示确切数量时（少于 1,000）返回。
* 每次搜索返回商城搜索结果第一页的商品。该页在 Yahoo! Shopping 上最多列出 30 个商品，在 Myntra 上 32 个，在 Zalando 上 24 个。Flipkart 的该页有 40 个位置，Nykaa 有 20 个，均包含广告。
* 商城把搜索转到其他页面时，返回该页面的商品。Ulta 会把部分品牌名搜索转到品牌页，Target 会把部分搜索转到相关搜索词，Nykaa 会对类目名称的搜索显示类目页。
* 没有任何商品的搜索会以失败任务结束。按完成的搜索计费。

## 相关

* [Commerce Product](/zh/engines/commerce-product.md)
* [引擎概览](/zh/engines/overview.md)
* [积分与限制](/zh/concepts/credits-and-limits.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.