경매 물건 조건 검색
realty_search_auctionsRead-onlyIdempotent
법원경매 물건을 지역·종류·감정가·유찰횟수로 필터링해 조회한다.
**이 축의 자리** — 조건을 **값으로 아는** 검색이 이 도구다. 사용자의 자연어 한 줄밖에
없으면 `search`가 먼저다(질의에서 조건을 뽑아 준다). 개별 사건의 상세는 여기가 아니라
`realty_get_auction_case`(사건번호+법원명)·`fetch`(search가 준 id)다.
**이 도구는 법원경매(민사집행법·각급 법원)만 조회한다 — 공매는 여기가 아니다.**
공매(국세징수법·국유재산법 등, 한국자산관리공사 온비드)는 **이 서버에 따로 있다**:
물건은 `realty_search_onbid`, 낙찰가율은 `realty_onbid_sale_rate`
(2026-08-22 적재 — 물건 25,669개 · 최근 3개월 개찰 결과 113,673행).
여기서 안 나온다고 "그런 물건 없다"고 답하지 말고 **공매 도구로 다시 걸어라.**
구분 신호는 번호 형식이다 — 법원 사건번호는 `2025타경1234`, 공매 물건관리번호는
`2026-0600-031235`(하이픈 세 토막·'타경' 없음)다.
**두 원장을 합쳐 세거나 낙찰가율을 섞어 평균내지 마라** — 근거법·주관기관·권리 인수
규칙·저감 방식이 다르다.
감정가(min_price_10k/max_price_10k)는 **만원** 단위다 — 5억은 50000.
유찰이 많을수록 최저입찰가가 감정가 대비 낮아진다(`min_bid_rate`가 그 비율).
⚠️ **이 목록에는 매각기일이 이미 지난 행이 섞여 있다**(백엔드가 기일로 걸러주지
않는다 — 인천 아파트 3억 이하 실측 48건 중 43건이 지난 기일). 지난 기일 행에는
`past_auction_note`가 붙고 응답의 `past_auction_count`가 그 페이지의 건수다.
"지금 살 수 있어?"류 질문이면 `exclude_past=true`로 걸러라 — 지난 기일 물건은
매각·취하됐거나 다음 기일이 아직 반영되지 않은 것이라 현재 매물로 인용하면 오답이다.
⚠️ **`sort=date_asc`(기일 임박 순)는 지난 기일이 목록 앞쪽을 통째로 차지한다**
(2026-08-21 실측 94,279건 중 앞 57,241건=60.7%). `exclude_past=true`면 서버가 그
접두를 건너뛰고 읽으므로 첫 호출부터 실물이 온다 — 건너뛴 행 수는
`meta.past_prefix_skipped`, 실제로 읽은 자리는 응답의 `offset`(요청값은
`requested_offset`)이다. **items가 비어도 `has_more`가 true면 '조건에 맞는 물건이
없다'는 뜻이 아니다** — 그 창이 전부 지난 기일이었을 뿐이니 `next_offset`으로
이어서 호출하라. note가 둘 중 어느 쪽인지 매번 말한다.
⚠️ **최저입찰가는 출처를 반드시 확인해라** — 건별 `min_bid_source`가 붙는다.
· `court_schedule` — 법원 기일표 정본이다. 그대로 믿어도 된다(활성의 28.8%).
· `item_list` — 물건목록값이다. 유찰이 있으면 **저감 한 단계만큼 낡아 실제보다
높을 수 있다**(2026-08-04 실측: 유찰 1회 이상에서 정본과 3%만 일치, 25~43% 과대).
이 경우 `min_bid_note`가 함께 온다. 사용자에게 단정적으로 말하지 말고 그 한계를
전해라. 저감률로 역산해 추정하지 마라 — 재감정으로 최저가가 **오르는** 사건도 있다.
응답의 `min_bid_stale_risk_count`가 그 페이지에서 낡았을 수 있는 건수다.
회차별 정확한 가격은 realty_auction_history의 court_schedule에 있다.
목록에는 요약 필드만 담긴다. 특정 물건의 전체 정보(면적·법원 계·주소 상세 등)는
돌아온 id로 realty_get_auction_case를 호출해 받아라.
"유찰 많이 돼 싸진 물건 찾아줘"류 발굴 질문은 realty_auction_alerts가 지름길이다
(min_fail_count로 여기서 걸러도 같은 축 — 결과를 합쳐 세지 마라).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sido | No | 시도. '서울'처럼 줄여 써도 되고 '서울특별시'도 된다. ⚠️ '광주'는 광주광역시와 경기도 광주시 둘 다라 **한쪽으로 읽지 않고 거절한다**(error='sido_ambiguous') — 광역시면 '광주광역시', 경기도 광주시면 sido='경기도'·sigungu='광주시'로 갈라 넣어라. | |
| sort | No | 정렬 기준 | date_desc |
| limit | No | 반환 개수 (최대 50) (허용 범위 1~50) | |
| offset | No | 페이지 오프셋. has_more가 true면 next_offset으로 다시 호출하라. | |
| sigungu | No | 시군구 (예: 강남구, 성남시) ⚠️ 시도 없이 시군구만 주면 **합치지 않고 거절한다**(error='region_ambiguous') — '중구'처럼 여러 시도에 같은 이름이 있으면 합친 값은 어느 지역의 것도 아니다. sido와 갈라 넣어라(예: sido='서울특별시'·sigungu='중구'). 거절 응답이 후보를 준다. | |
| usage_name | No | 물건 종류 — 원장 값 예: 아파트·오피스텔·다세대·연립주택·단독주택·다가구주택·근린시설·상가·대지·임야·전답. 부분일치라 '빌라'는 '연립주택,다세대,빌라' 행에 걸린다. **'토지'는 이 원장에 없는 이름이다** — 대지·임야·전답으로 나뉘어 있어 그대로 넣으면 서버가 사유와 유효값 목록을 들어 거절한다. 비우면 전 종류 | |
| exclude_past | No | 매각기일이 이미 지난 행 제외 여부. 기본 False(전체 반환 — 지난 기일 행에는 past_auction_note 플래그가 붙는다). '지금 입찰 가능한 물건' 질문이면 True로 호출하라 — 오늘 이후 기일(기일 미정 포함)만 남는다. | |
| max_price_10k | No | 최대 감정가, **만원** 단위 | |
| min_bid_count | No | 최소 유찰 횟수. 유찰이 쌓일수록 최저입찰가가 내려간다. (허용 범위 0~100) | |
| min_price_10k | No | 최소 감정가, **만원** 단위 (5억이면 50000) |