Market Kurly Search
What this skill does
마켓컬리 웹앱이 실제로 사용하는 비로그인 검색/상품 상세 표면을 사용해 아래 흐름을 처리한다.
- 키워드로 상품 후보를 검색한다.
- 현재 가격과 할인 여부를 확인한다.
- 품절 여부와 배송 타입을 확인한다.
- 상품 링크를 함께 반환한다.
- 주문/장바구니 같은 액션은 하지 않는다. 조회형으로만 답한다.
When to use
- "마켓컬리에서 우유 얼마야?"
- "컬리에서 딸기 검색해줘"
- "이 상품 품절인지 보고 링크도 줘"
- "지금 컬리 가격만 빠르게 보고 싶어"
When not to use
- 주문/장바구니/결제까지 자동화해야 하는 경우
- 주소 기반 배송 가능 여부나 회원 전용 가격을 확정해야 하는 경우
- 로그인 세션이 필요한 개인화 추천/찜 정보를 조회해야 하는 경우
Prerequisites
- 인터넷 연결
node18+- 이 저장소의
market-kurly-searchpackage 또는 동일 로직
Required inputs
1. Ask for a product keyword if it is missing
상품명 또는 검색어가 없으면 먼저 물어본다.
- 권장 질문:
찾을 마켓컬리 상품명이나 검색어를 알려주세요. 예: 우유, 딸기, 닭가슴살 - 너무 넓으면:
검색어가 너무 넓어요. 브랜드나 용량까지 같이 알려주시면 가격 후보를 더 정확히 추릴 수 있어요.
2. Confirm which candidate they want when the query is ambiguous
검색 결과가 여러 개면 상위 2~3개만 보여주고 다시 확인받는다.
- 권장 질문:
후보가 여러 개예요. 아래 상품 중 어떤 상품 가격을 볼까요? - 응답에는 상품명 + 현재 가격 + 품절 여부 + 링크를 같이 붙인다.
Official Market Kurly surfaces
- search list:
https://api.kurly.com/search/v4/sites/market/normal-search?keyword=<keyword>&page=1 - search count:
https://api.kurly.com/search/v3/sites/market/normal-search/count?keyword=<keyword>&filters=&allow_replace=true - product detail page:
https://www.kurly.com/goods/<productNo>
Workflow
1. Search by keyword first
const { searchProducts } = require("market-kurly-search")
const result = await searchProducts("우유")
console.log(result.items.slice(0, 3))검색 결과에서는 아래 필드를 우선 본다.
- 상품명
- 현재 가격 (
discountedPrice우선, 없으면salesPrice) - 할인율
- 품절 여부
- 배송 타입
- 상품 링크
2. Use the count endpoint when the result set is broad
const { countProducts } = require("market-kurly-search")
const count = await countProducts("우유")
console.log(count)후보가 너무 많으면 count 를 먼저 보여 주고 검색어를 좁히라고 안내한다.
3. Use the goods page detail as a fallback or follow-up lookup
const { getProductDetail } = require("market-kurly-search")
const detail = await getProductDetail(5063110)
console.log(detail)goods/<productNo> HTML 안의 __NEXT_DATA__ 에서 상품명, 가격, 품절 여부, 배송 타입을 추출한다.
4. Respond conservatively
응답은 짧고 보수적으로 정리한다.
- 상품명
- 현재 가격
- 필요하면 원가/할인가 여부
- 품절 여부 또는 판매 가능 여부
- 상품 링크
- 가격/품절/노출 정보는 시점에 따라 달라질 수 있으니 조회 시각 기준 참고값이라고 분명히 말한다.
Done when
- 상품 키워드를 확인했다.
- 검색 결과에서 후보와 현재 가격을 최소 1개 이상 반환했다.
- 필요하면 상품 상세 페이지로 보조 확인했다.
- 주문/장바구니 같은 범위 밖 액션은 하지 않았다.
Failure modes
- 검색어가 너무 넓으면 후보가 과도하게 많아질 수 있다.
- 가격/품절/배송 문구는 시점에 따라 달라질 수 있다.
- 현재 확인한 표면은 공식 개발자 Open API가 아니라 웹이 쓰는 공개 표면 이므로 스키마가 바뀌면 깨질 수 있다.
- 회원 전용/주소 전용 정보는 비로그인 조회만으로 확정할 수 없다.
Notes
- 조회형 스킬이다.
- 비로그인 공개 표면 우선 원칙을 유지한다.
- 주문/장바구니/로그인 요구 기능은 시도하지 않는다.
