쇼핑몰 20곳의 상품 검색을 지원해요

Amazon, Walmart, 쿠팡, 올리브영, Rakuten, Flipkart, Zalando 등 5개국 쇼핑몰 20곳에서 검색어의 상품 순위를 가격, 평점, 리뷰 수와 함께 같은 형식으로 받아요.

받는 결과

• COMMERCE_SERP: 태스크 하나가 쇼핑몰 하나를 검색합니다. 미국, 한국, 일본, 인도, 독일의 쇼핑몰 20곳 중 하나를 payload.site로 고릅니다.
• products: 검색어에 대한 쇼핑몰의 상품 순위를 최대 40개까지 받습니다. 상품마다 rank, productId, title, url이 담깁니다.
• price는 숫자로, currency와 함께 옵니다. 검색 결과 페이지에 나오면 rating, reviewCount, brand, imageUrl도 함께 옵니다.
• 모든 쇼핑몰이 같은 상품 필드를 씁니다. 파서 하나로 Amazon, 쿠팡, Rakuten, Zalando를 똑같이 읽습니다.

쇼핑몰

• 미국(US): Amazon amazon, Walmart walmart, Target target, eBay ebay, AliExpress aliexpress, Sephora sephora, Ulta ulta
• 한국(KR): 쿠팡 coupang, 올리브영 oliveyoung, 11번가 11st, 롯데ON lotteon, 무신사 musinsa, 컬리 kurly
• 일본(JP): 라쿠텐 rakuten, Yahoo! 쇼핑 yahoo_shopping, Qoo10 qoo10
• 인도(IN): Flipkart flipkart, Myntra myntra, Nykaa nykaa
• 독일(DE): Zalando zalando

동작 방식

태스크마다 그 쇼핑몰의 나라에서 검색어로 나오는 첫 결과 페이지를 읽고, 쇼핑몰의 기본 정렬 순서대로 상품을 돌려줍니다. 쿠팡을 뺀 모든 쇼핑몰에서 광고로 표시된 상품은 빼고, 나머지를 페이지 순서대로 rank로 셉니다.

productId는 쇼핑몰의 상품 ID입니다. Amazon은 ASIN, eBay는 상품 번호, Rakuten은 shop:item입니다. price는 상품 자체의 currency(ISO 4217) 기준 숫자이고, 용량마다 가격이 다르면 가장 낮은 가격입니다. rating은 평점을 보여 주는 쇼핑몰에서 5점 만점으로 받고, 컬리와 Zalando는 가격과 상품명으로 상품을 보여 줍니다.

쇼핑몰이 검색을 다른 페이지로 보내면 그 페이지의 상품을 받습니다. Ulta는 일부 브랜드 이름을 브랜드 페이지로, Target은 일부 검색을 관련 검색어로 보내고, Nykaa는 카테고리 이름을 검색하면 카테고리 페이지를 보여 줍니다. 상품을 하나도 찾지 못한 검색은 실패한 태스크로 끝납니다.

이렇게 활용하세요

• Amazon, Walmart, Target에서 카테고리 검색어로 내 상품이 몇 위인지 매일 추적합니다.
• 내 상품의 가격, 평점, 리뷰 수를 주변 순위 상품과 비교합니다.
• 올리브영, Rakuten, Nykaa, Zalando에서 뷰티나 패션 라인을 같은 요청 형식으로 살펴봅니다.
• 같은 검색어의 쇼핑몰 순위를 ChatGPT나 Google AI Mode 답변과 나란히 놓고, 쇼핑하는 사람이 곳마다 어떤 상품을 만나는지 봅니다.

요청 보내기

API 키를 Authorization 헤더에 넣어 요청을 보냅니다.

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인 태스크가 바로 돌아옵니다. status가 COMPLETED나 FAILED가 될 때까지 GET /v1/async/task/{id}로 조회하거나, 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크레딧이 차감됩니다. 크레딧은 태스크가 완료될 때 차감됩니다.