쿠팡 상품 검색

채널 코드 coupang_search · 수집 환경 linux

쿠팡에서 키워드로 상품 리스트를 정렬별(쿠팡 랭킹/낮은가격/높은가격/판매량/최신)로 검색·수집합니다. 로그인 불필요. 수집 서버가 실제 Chrome으로 접근하며, 검색 결과 페이지는 Akamai 보호가 강해 데이터센터 IP는 대부분 막히므로 자동으로 레지덴셜 프록시로 우회합니다(차단 IP/포트는 허브가 쿨다운 중앙관리). 결과는 상품명·가격(할인가)·평점·리뷰수·상품링크·이미지 + 광고 여부(스폰서)·로켓배송 여부입니다. 입력은 키워드 하나면 됩니다. ⚠️ 검색은 차단에 민감하니 호출 간격을 넉넉히 두세요. result_count가 limit보다 적으면 오류가 아니라 가용 상품 부족(페이지 한도) 또는 일시 차단입니다.

요청 파라미터

아래 값들을 POST /api/v1/collect 의 params 객체에 담아 보냅니다.

키	타입	필수	기본	설명
keyword	text	예	—	쿠팡 검색어(예: 로보락)
sort	enum	—	scoreDesc	쿠팡 검색 sorter 파라미터(실측): scoreDesc(랭킹,기본)·salePriceAsc(낮은가격)·salePriceDesc(높은가격)·saleCountDesc(판매량)·latestAsc(최신)
limit	number	—	50	최대 수집 상품 수(페이지당 약 36~60개)
max_pages	number	—	10	검색 결과 페이지 탐색 한도
min_price	number	—	—	이 가격 미만 상품 제외(0/빈값=제한 없음)
max_price	number	—	—	이 가격 초과 상품 제외(0/빈값=제한 없음)
exclude_keywords	text	—	—	이 단어가 상품명에 들어가면 제외. 쉼표로 여러 개, 한 단어 안 띄어쓰기 허용
exclude_ads	bool	—	false	체크하면 광고(스폰서) 상품을 제외하고 수집합니다. 기본은 광고 포함

제외 키워드(exclude_keywords)
이 단어가 들어간 글은 수집 단계에서 걸러집니다. 쉼표(,)로 여러 개를 넣고, 한 단어 안에 띄어쓰기도 쓸 수 있습니다(예: "무료 나눔, 광고" → 무료 나눔·광고 두 개). 대소문자는 구분하지 않고 부분 일치로 판정합니다.

기본은 제목 기준 — 상세 요청을 보내기 전에 걸러서 빠르고, 수집 상한(limit)도 차감하지 않습니다.
비우면 → 제외 없이 전부 수집.

요청 예시

curl -X POST https://scraper.conbus.co.kr/api/v1/collect \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "coupang_search",
    "params": {
        "keyword": "로얄캐닌",
        "sort": "scoreDesc",
        "limit": 50,
        "max_pages": 10,
        "min_price": 10,
        "max_price": 10,
        "exclude_keywords": "광고, 협찬",
        "exclude_ads": false
    }
}'

응답 (202 Accepted)

요청은 즉시 큐에 적재되고 request_id 를 돌려줍니다. 실제 수집은 워커가 비동기로 처리합니다.

{ "success": true, "data": { "request_id": 42, "channel": "coupang_search",
    "status": "pending", "status_url": "https://scraper.conbus.co.kr/api/v1/requests/42" } }

결과 조회 — `GET /requests/{id}`

같은 API 키로 request_id 를 조회합니다. 상태에 따라 응답이 달라집니다.

진행 중 (pending / running)

아직 끝나지 않았으면 progress 로 진행 상황만 옵니다(items 없음).

{
    "success": true,
    "data": {
        "request_id": 42,
        "channel": "coupang_search",
        "status": "running",
        "external_ref": null,
        "result_count": null,
        "started_at": "2026-06-16T09:00:05+09:00",
        "finished_at": null,
        "duration_ms": null,
        "duration_sec": null,
        "created_at": "2026-06-16T09:00:00+09:00",
        "updated_at": "2026-06-16T09:01:30+09:00",
        "progress": {
            "count": 12,
            "phase": "list"
        },
        "elapsed_ms": 85000
    }
}

완료 (done)

status 가 done 이면 data.items[] 에 결과가 담깁니다. 실패 시엔 status: "failed" 와 error 가 옵니다.

{
    "success": true,
    "data": {
        "request_id": 42,
        "channel": "coupang_search",
        "status": "done",
        "external_ref": null,
        "result_count": 1,
        "started_at": "2026-06-16T09:00:05+09:00",
        "finished_at": "2026-06-16T09:02:00+09:00",
        "duration_ms": 115000,
        "duration_sec": 115,
        "created_at": "2026-06-16T09:00:00+09:00",
        "updated_at": "2026-06-16T09:02:00+09:00",
        "items": [
            {
                "post_id": "8596170323_94843948310",
                "url": "https://www.coupang.com/vp/products/8596170323",
                "title": "로얄캐닌 미니 인도어 어덜트 건식사료, 닭, 7.5kg, 1개",
                "author": null,
                "posted_at": null,
                "views": null,
                "comment_count": 18265,
                "recommends": 18265,
                "body": null,
                "source": "쿠팡 / 검색:로얄캐닌",
                "extra": {
                    "rank": 2,
                    "price": 33900,
                    "original_price": 39900,
                    "rating": "4.5",
                    "review_count": 18265,
                    "is_ad": false,
                    "ad_label": "",
                    "is_rocket": true,
                    "image": "https://thumbnail.coupangcdn.com/.../product1.jpg",
                    "vendor_item_id": "94843948310",
                    "keyword": "로얄캐닌",
                    "sort": "scoreDesc",
                    "source_kind": "coupang_search"
                }
            }
        ]
    }
}

실패 (failed)

status 가 failed 면 error 에 사유가 옵니다(items 없음). 일시적 실패는 자동 재시도되며, 위 응답은 마지막 시도 기준입니다.

{
    "success": true,
    "data": {
        "request_id": 42,
        "channel": "coupang_search",
        "status": "failed",
        "external_ref": null,
        "result_count": 0,
        "started_at": "2026-06-16T09:00:05+09:00",
        "finished_at": "2026-06-16T09:00:16+09:00",
        "duration_ms": 11000,
        "duration_sec": 11,
        "created_at": "2026-06-16T09:00:00+09:00",
        "updated_at": "2026-06-16T09:00:16+09:00",
        "error": "수집 실패 — 잠시 후 다시 시도하세요"
    }
}

최상위 data에는 항상 request_id·channel·status·external_ref·result_count·started_at·finished_at·duration_ms·duration_sec·created_at·updated_at이 포함되고, 상태에 따라 items(done)·progress+elapsed_ms(진행 중)·error(failed/cancelled)가 추가됩니다. duration_*는 허브가 잰 수집 소요 시간(시작~종료) — 자세히는 비동기 & 콜백. 요청을 잘못 시작했다면 취소 API로 중단할 수 있습니다.

결과 필드 (`items[]`)

필드	설명
post_id	상품 고유 ID — `productId_vendorItemId`(개별 옵션/SKU 단위). 재수집 중복 제거 키. 같은 상품이라도 옵션·광고/일반이 다르면 다른 ID
url	상품 페이지 URL (`coupang.com/vp/products/{productId}`)
title / body	`title`=상품명 / `body`는 `null` (상품 검색은 본문이 없습니다)
author	`null` — 상품은 작성자 개념이 없습니다
posted_at	작성 시각 (ISO8601, KST) — 상품 검색은 `null`(작성일 개념 없음)
views / comment_count	`views`=`null` / `comment_count`=리뷰 수(표시 일관용, `extra.review_count`와 같은 값)
recommends	리뷰 수 (`comment_count`와 동일 값)
source	`쿠팡 / 검색:{키워드}`
extra.rank	쿠팡 검색 랭킹 순위 — 일반(비광고) 상품에 붙는 1~N위 라벨의 숫자. 광고 상품과 순위 라벨이 없는 일반 상품은 `null`. 정렬이 "쿠팡 랭킹순(scoreDesc)"일 때 가장 의미 있음
extra.price	판매가(할인 적용가, 원)
extra.original_price	정가(할인 전, 원). 할인이 없거나 미표기면 `null`
extra.rating	별점 — `"4.5"` 같은 문자열(없으면 `null`)
extra.review_count	리뷰 수
extra.is_ad	광고(스폰서) 상품이면 `true`
extra.ad_label	광고면 `"광고"`, 일반이면 빈 문자열(`""`)
extra.is_rocket	로켓배송 상품이면 `true`
extra.image	상품 썸네일 이미지 URL(없으면 `null`)
extra.vendor_item_id	판매 옵션 ID(vendorItemId)
extra.keyword	검색 키워드(요청값)
extra.sort	정렬 값(요청값)
extra.source_kind	`coupang_search`

채널 참고

결과 순서 = 쿠팡 검색 페이지에 노출된 그대로입니다(광고·일반 상품이 섞여 나옴, 별도 정렬·분리 안 함). 광고를 빼고 싶으면 exclude_ads: true로 요청하세요.
광고 상품에는 순위(rank)가 없습니다(null). 순위는 일반 상품에 붙는 1~N위 라벨에만 부여됩니다. 광고 여부는 is_ad/ad_label로 구분하세요.
같은 상품(productId)이라도 옵션(용량·구성)이 다르면 각각 다른 순위로 따로 노출되어 별도 항목으로 수집됩니다. 또 한 상품이 광고로도, 일반 순위로도 동시에 노출되면 둘 다 수집됩니다(post_id에 옵션·광고여부가 포함돼 구분).
로그인 불필요. 검색 페이지는 Akamai 보호가 강해 데이터센터 IP가 막히면 자동으로 레지덴셜 프록시로 우회합니다(추가 시간·비용 가능). 검색은 차단에 민감하니 호출 간격을 넉넉히 두세요.
result_count가 요청 limit보다 적으면 오류가 아니라 가용 상품 부족(페이지 한도)이거나 일시 차단입니다.

결과 수신(폴링·콜백) 방식은 비동기 & 콜백을 참고하세요.