> ## 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 Product API (COMMERCE_PRODUCT)

> 读取 Amazon、Walmart、Target、Sephora、Ulta、Olive Young、11st、Musinsa、Kurly、Rakuten、Flipkart、Zalando 等商城的一个商品页面，以同一格式获取价格、库存、卖家、评分、图片、规格和选项。

读取一个商城商品页面，通过异步任务 API 以 JSON 获取商品信息。传入页面的 `url`，按 URL 选择商城，所有商城返回相同的字段。每次完成的读取消耗 **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_PRODUCT", "payload": { "url": "https://www.amazon.com/dp/B00TTD9BRC" } }'
```

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

## 参数

* `url`：必填。下表商城的商品页面，最多 2,048 个字符。[Commerce Search](/zh/engines/commerce-serp.md) 为这些商城返回的商品 `url` 可直接使用，但 Yahoo! Shopping 的 LOHACO 页面（`lohaco.yahoo.co.jp`）除外。跟踪代码等不影响结果的参数会在读取前去掉。
* `country`：可选。默认是商城所在国家。其他国家会以 `422 REGION_UNSUPPORTED` 拒绝。

| `site` | 商品页面 | `country` |
| - | - | - |
| `amazon` | `amazon.com/dp/{ASIN}` | `US` |
| `walmart` | `walmart.com/ip/{name}/{id}` | `US` |
| `target` | `target.com/p/{name}/-/A-{TCIN}` | `US` |
| `sephora` | `sephora.com/product/{name}-P{id}` | `US` |
| `ulta` | `ulta.com/p/{name}-{id}` | `US` |
| `11st` | `11st.co.kr/products/{id}` | `KR` |
| `lotteon` | `lotteon.com/p/product/{id}` | `KR` |
| `musinsa` | `musinsa.com/products/{id}` | `KR` |
| `kurly` | `kurly.com/goods/{id}` | `KR` |
| `oliveyoung` | `oliveyoung.co.kr/store/goods/getGoodsDetail.do?goodsNo={id}` | `KR` |
| `rakuten` | `item.rakuten.co.jp/{shop}/{item}/` | `JP` |
| `yahoo_shopping` | `store.shopping.yahoo.co.jp/{store}/{item}.html` | `JP` |
| `qoo10` | `qoo10.jp/g/{id}` | `JP` |
| `flipkart` | `flipkart.com/{name}/p/{itm}?pid={pid}` | `IN` |
| `myntra` | `myntra.com/{category}/{brand}/{name}/{id}/buy` | `IN` |
| `nykaa` | `nykaa.com/{name}/p/{id}` | `IN` |
| `zalando` | `zalando.de/{name}-{sku}.html` | `DE` |
| `google_shopping` | `google.com/search?q={query}&udm=28#product={productId}&title={title}` | `US` |

同一页面的其他地址也可以使用，例如 Amazon 的 `/gp/product/{ASIN}` 和 11st 的移动版页面。

## 响应示例

```json theme={"theme":"css-variables"}
{
  "site": "amazon",
  "country": "US",
  "url": "https://www.amazon.com/dp/B00TTD9BRC",
  "productId": "B00TTD9BRC",
  "title": "CeraVe Moisturizing Cream, Face & Body Moisturizer for Dry Skin, 19oz",
  "brand": "CeraVe",
  "price": 16.77,
  "listPrice": 18.96,
  "currency": "USD",
  "inStock": true,
  "seller": "Amazon.com",
  "rating": 4.7,
  "reviewCount": 149149,
  "images": ["https://m.media-amazon.com/images/I/61EidjXUBrL._SL1000_.jpg"],
  "description": "[ HYALURONIC ACID MOISTURIZER ] With hyaluronic acid, ceramides and MVE technology for 24 hour hydration.",
  "descriptionImages": ["https://m.media-amazon.com/images/S/aplus-media-library-service-media/8c56d081-e316-4b57-9731-fcf4eda0821f.__CR0,0,1464,600_PT0_SX1464_V1___.jpg"],
  "specs": [
    { "name": "Item Form", "value": "Cream" },
    { "name": "Skin Type", "value": "All, Dry, Sensitive" }
  ],
  "options": [{ "name": "Size", "values": ["8 Ounce", "16 Ounce (Pack of 1)", "19 Ounce (Pack of 1)"] }],
  "categories": ["Beauty & Personal Care", "Skin Care", "Face", "Creams & Moisturizers", "Face Moisturizers"]
}
```

## 结果字段

* `site`、`country`、`url` 和 `productId` 标识所读取的页面。`url` 是实际读取的页面。`productId` 是商城自己的商品 ID，例如 Amazon 的 ASIN 或 Rakuten 的 `shop:item`，与 Commerce Search 返回的相同。例外是 Nykaa 上有色号或规格选项的商品：Commerce Search 返回其中一个选项的 ID，本次读取返回商品页面的 ID。
* `title` 始终存在。其他字段在页面显示时返回，各字段由哪些商城返回见下表。
* `price` 是按页面最初显示的商品，在优惠券和运费之前的购买价格，币种为 `currency`（ISO 4217）。`listPrice` 是页面划线显示的原价，高于 `price` 时返回。`inStock` 是该商品的库存状态，`seller` 是卖家。
* `rating` 为五分制，保留两位小数。`reviewCount` 是评价数。
* `images` 按页面顺序列出商品图库中最多 30 张照片的 URL。11st 和 Lotte ON 只返回主图，Sephora 最多返回 2 张；Rakuten 和 Yahoo! Shopping 的卖家放进图库的横幅或公告图片也会一并返回。`description` 是每段一行的纯文本，最多 10,000 个字符，不包含只出现在图片中的文字。
* `descriptionImages` 按页面顺序列出商品说明区域中最多 300 张图片的 URL，例如卖家的详情页或 Amazon 的 A+ 内容。卖家放进说明的横幅和公告图片也会一并返回，不识别图片中的文字。
* `specs` 列出商品详情中最多 100 个 `{ name, value }` 对。`options` 列出最多 20 个尺寸、颜色等选项，每个选项最多 100 个 `values`；其他字段对应页面默认打开的选项。`categories` 从最宽的类目到最窄的类目，最多 10 级。`gtin` 是页面列出的 UPC、EAN 或 JAN。
* `google_shopping` 读取 [Commerce Search](/zh/engines/commerce-serp.md) 返回的商品：其 `url` 带有搜索词、Google 商品 ID 和商品名称。读取时会用该搜索词重新搜索 Google Shopping，若该搜索词下不再列出该商品，则改用商品名称搜索，然后打开商品面板，因此比其他商城耗时更长。`offers` 是 Google 为该商品列出的商家，Google 标为最低价的商家排在第一位，每个商家包含 `seller`、`title`（商家的商品名称）、`url`（商家的商品页）、`price`、`listPrice`、`currency` 和 `inStock`。商品的 `price`、`listPrice`、`seller` 和 `inStock` 取自第一个商家。`reviewCount` 仅在 Google 显示确切数量时（少于 1,000）返回。如果搜索词和商品名称下都没有列出该商品，任务以 `PAGE_UNAVAILABLE` 结束。
* 商城以 404 或 410 响应的页面（例如已下架的商品）会以 `PAGE_UNAVAILABLE` 结束任务，消息中带有商城的响应。其他读取失败为 `ENGINE_NO_RESULT`。按完成的读取计费。

| 字段 | 返回该字段的商城 |
| - | - |
| `title`, `price`, `currency`, `images` | 全部 |
| `brand` | 除 Rakuten 外全部 |
| `inStock` | 除 Target、Sephora 外全部 |
| `rating` | 除 Lotte ON、Kurly、Zalando 外全部 |
| `reviewCount` | 除 Lotte ON、Zalando 外全部 |
| `categories` | 除 Sephora、Qoo10、Flipkart、Google Shopping 外全部 |
| `description` | 除 11st、Qoo10 外全部。Lotte ON、Musinsa 和 Olive Young 的商品说明大多以图片展示，只有少数页面有。Flipkart 和 Zalando 返回其为搜索引擎发布的简短摘要。 |
| `descriptionImages` | Amazon、Ulta、11st、Lotte ON、Musinsa、Kurly、Olive Young、Rakuten、Yahoo! Shopping、Qoo10 |
| `specs` | Amazon、Walmart、Target、Ulta、Lotte ON、Musinsa、Kurly、Myntra、Nykaa、Google Shopping |
| `options` | Amazon、Walmart、Ulta、Musinsa、Kurly、Olive Young、Rakuten、Myntra、Nykaa、Zalando |
| `seller` | Amazon、Walmart、Lotte ON、Kurly、Rakuten、Myntra、Nykaa、Google Shopping |
| `listPrice` | Amazon、Walmart、Target、Sephora、Musinsa、Kurly、Olive Young、Qoo10、Myntra、Nykaa、Google Shopping |
| `offers` | Google Shopping |
| `gtin` | Amazon、Walmart、Target、Ulta、Olive Young、Rakuten、Yahoo! Shopping |

## 相关

* [Commerce Search](/zh/engines/commerce-serp.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.