> ## 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, 쿠팡, 올리브영, Rakuten, Flipkart, Zalando 등 쇼핑몰을 task마다 하나씩 검색해, 상품 순위와 가격, 평점, 리뷰 수를 같은 형식으로 받습니다.

쇼핑몰 하나의 상품을 검색하고 순위별 결과를 비동기 task API로 받습니다. `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 } }'
```

task를 제출한 뒤 `GET /v1/async/task/{id}`를 폴링하거나 웹훅으로 받습니다. 참고: [비동기 task](/ko/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`는 쇼핑몰의 기본 정렬 순서입니다. 쿠팡을 제외한 쇼핑몰에서는 광고로 표시된 상품을 건너뜁니다.
* `price`, `rating`, `reviewCount`, `imageUrl`, `brand`는 검색 결과 화면에 있을 때 담습니다. `price`는 상품별 `currency`(ISO 4217) 기준의 숫자입니다. Amazon은 한 검색에서 여러 통화를 보여 줄 수 있습니다. 용량별 가격이 다르면 가장 낮은 가격을 담습니다. Target 가격은 Target 기본 온라인 매장 기준입니다. AliExpress 가격은 로그인하지 않은 미국 구매자에게 보이는 판매가입니다.
* `rating`은 5점 만점입니다. 컬리와 Zalando는 평점을 보여 주지 않고, AliExpress는 평가 수 없이 별점만 보여 줍니다. 999+처럼 줄여 표시한 개수는 담지 않습니다. `brand`는 상품명과 따로 브랜드를 표시하는 Target, Sephora, Ulta, 올리브영, 롯데온, 무신사, Yahoo! Shopping, Qoo10, Flipkart, Myntra, Nykaa, Zalando에서 담습니다.
* `google_shopping`의 `productId`는 Google 상품 ID이고, Google이 상품으로 묶지 않은 판매 목록은 판매 항목(offer) ID입니다. Google 페이지에는 상품이나 판매처 페이지 링크가 없어 `url`은 상품이 노출된 Google Shopping 결과 페이지 끝에 `#product={productId}&title={title}`를 붙인 주소입니다. 이 `url`을 [Commerce Product](/ko/engines/commerce-product.md)에 넣으면 상품의 판매처, 사양, 설명을 읽습니다. `seller`는 Google이 먼저 보여 주는 판매처이고, `reviewCount`는 Google이 정확한 개수를 보여 줄 때(1,000개 미만)만 담습니다.
* 검색마다 쇼핑몰의 첫 결과 페이지에서 상품을 가져옵니다. 이 페이지에는 Yahoo! Shopping이 최대 30개, Myntra가 32개, Zalando가 24개를 보여 줍니다. Flipkart는 40칸, Nykaa는 20칸이며 광고 상품을 포함합니다.
* 쇼핑몰이 검색을 다른 페이지로 보내면 그 페이지의 상품을 돌려줍니다. Ulta는 일부 브랜드 검색을 브랜드 페이지로, Target은 일부 검색을 관련 검색어로 보냅니다. Nykaa는 카테고리 이름으로 검색하면 카테고리 페이지를 보여 줍니다.
* 상품이 하나도 없는 검색은 실패한 task로 끝납니다. 완료된 검색 단위로 과금합니다.

## 관련 문서

* [Commerce Product](/ko/engines/commerce-product.md)
* [엔진 목록](/ko/engines/overview.md)
* [크레딧과 한도](/ko/concepts/credits-and-limits.md)


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