[둥지] 깡통전세/보증보험 판정을 위한 시세조회 흐름 정리
둥지 프로젝트의 시세조회 흐름을 정리합니다. 주택유형별 Waterfall 로직, 각 데이터 소스의 기술적 접근 방식, 깡통전세·보증보험 판정 계산식을 다룹니다.
깡통전세 위험도와 보증보험 가입 가능 여부를 판정하려면 해당 주택의 시세가 필요합니다. 문제는 주택 유형마다 신뢰할 수 있는 시세 출처가 다르고, 특정 출처에서 데이터를 가져오지 못하는 경우도 있다는 점입니다. 둥지는 이를 Waterfall 방식으로 해결합니다.
전체 흐름
깡통전세·보증보험 분석 API가 호출되면 공통 파이프라인을 거칩니다.
1
2
3
4
5
6
7
API 요청 (깡통전세 또는 보증보험)
│
├─ Redis 쿨다운·레이트리밋 체크
├─ 주소 정규화 → PNU 코드, 법정동코드 등 획득
├─ 시세 조회 (Waterfall)
├─ 등기부등본 OCR 파싱 → 선순위채권 추출
└─ 위험도/가입 가능 여부 판정 → DB 저장 → 결과 반환
동일 주소에 대한 반복 조회를 막기 위해 Redis로 쿨다운과 레이트리밋을 관리하며, 시세 결과는 PostgreSQL에 일정 기간 캐시합니다.
시세 조회: Waterfall 로직
주택유형별로 우선순위가 높은 데이터 소스부터 순서대로 시도해 첫 번째 성공한 결과를 사용합니다. PNU 코드 기준으로 캐시된 결과가 있으면 외부 조회 없이 재사용합니다.
| 주택유형 | 1순위 | 2순위 | 3순위 | 4순위 | 5순위 | Fallback |
|---|---|---|---|---|---|---|
| 아파트 | R-Tech 시세 | 공동주택공시가격×140% | 안심전세참고시세 | 실거래가 | 분양가×90%¹ | 수동 확인² |
| 오피스텔 | R-Tech 시세 | 국세청기준시가×140% | 안심전세참고시세 | 실거래가 | 분양가×90%¹ | 수동 확인² |
| 연립다세대 | 공동주택공시가격×140% | 안심전세참고시세 | 실거래가 | — | — | 수동 확인² |
| 단독/다가구 | 개별단독주택공시가격×140% | 실거래가 | — | — | — | 수동 확인² |
¹ 준공 후 1년 미경과 주택에만 적용
² 토지공시지가는 API로 조회하나 건물시가표준액은 수동 확인이 필요해,price=0 / requires_manual_input=True로 반환
아파트 R-Tech 시세는 층수에 따라 다르게 적용합니다.
- 1~2층(최저층): 하한가
- 그 외: (상한가 + 하한가) 산술평균
- 오피스텔: 항상 하한가
데이터 소스별 기술 접근
시세 데이터를 가져오는 방식은 소스마다 다릅니다. 공개 API가 있는 곳은 직접 호출하고, 없는 곳은 세션 크롤링으로 내부 API를 활용합니다. Selenium은 사용하지 않으며, 모든 HTTP 통신은 httpx.AsyncClient로 비동기 처리합니다.
세션 크롤링이란?
웹사이트의 프론트엔드가 내부적으로 사용하는 비공개 API를 직접 호출하는 방식입니다. 브라우저가 첫 페이지 요청 시 서버로부터 세션 쿠키를 받아 이후 요청에 함께 보내는 원리를 그대로 구현합니다. Selenium처럼 브라우저 렌더링 엔진을 구동하지 않아 속도가 빠르고 자원 소모가 적습니다.
R-Tech (부동산테크)
아파트·오피스텔 시세 1순위 소스입니다. 세션 쿠키를 획득한 뒤 내부 API를 순서대로 호출해 단지 목록 조회 → 면적 매핑 → 하한가/상한가 조회 순으로 진행합니다. 건물명은 텍스트 매칭(정확일치 → 부분일치 순)으로 찾습니다. 세션이 불안정한 경우 리셋 후 재시도합니다.
안심전세참고시세
연립다세대·빌라 등 소규모 단지를 대상으로 하며, 동일한 부동산테크 서버를 사용합니다. R-Tech와 다른 점은 주소 대신 좌표 기반 bounding box로 단지를 검색한다는 것입니다. 주소에서 얻은 좌표를 pyproj로 좌표계 변환(UTM-K/WGS84 → TM) 후 반경 내 단지 목록을 조회합니다.
공시가격 알리미
공동주택공시가격(아파트·연립·오피스텔)과 개별단독주택공시가격(단독·다가구)을 제공하는 공공 데이터 API입니다. PNU 코드 기반으로 단지 → 동 → 호 순으로 단계별 조회하며, 전용면적이 가장 근접한 항목을 선택합니다. 당해 연도 데이터가 없으면 전년도로 재시도합니다.
국세청 기준시가
오피스텔 전용 소스입니다. 홈택스 WebSquare 기반 내부 API를 역추적해 활용하며, 건물번호 → 동 → 층 → 호 순으로 단계별 조회해 원/㎡ 단위 기준시가를 얻습니다. 서비스 레이어에서 전용면적을 곱하고 140% 배율을 적용해 최종 시세를 산출합니다.
실거래가
국토교통부 공개 API를 사용합니다. 주택유형별로 전용 엔드포인트가 있으며, 최근 12개월을 최신부터 역순으로 순회해 주소와 전용면적(±3㎡ 허용)이 일치하는 거래 건을 찾습니다.
분양가
HUG 공개 API로 총 분양금액과 총 세대수를 받아 세대당 평균 분양가를 산출하고 90% 배율을 적용합니다. 준공 후 1년이 지난 주택에는 적용하지 않습니다.
깡통전세 판정
시세, 보증금, 선순위채권(등기부등본 OCR)을 조합해 위험등급을 산출합니다.
1
2
gap_ratio = (시세 - 보증금) / 시세 × 100 ← 위험등급 기준
risk_ratio = (선순위채권 + 보증금) / 시세 ← 참고 지표
| 등급 | 조건 |
|---|---|
| SAFE (안전) | gap_ratio ≥ 30% |
| CAUTION (주의) | 20% ≤ gap_ratio < 30% |
| DANGER (위험) | 0% < gap_ratio < 20% |
| CRITICAL (깡통전세) | gap_ratio ≤ 0% |
다가구 주택의 경우, 사용자가 직접 입력한 선순위임차인 보증금 합계를 선순위채권에 포함합니다.
깡통전세 위험도 분석 결과
보증보험 판정
HUG 전세보증금반환보증 요건을 기준으로 가입 가능 여부를 체크합니다.
| 체크 항목 | 기준 | 데이터 출처 |
|---|---|---|
| 전세보증금 한도 | 수도권 7억 / 기타 5억 이하 | 보증금, 주소 |
| 담보인정비율 | (선순위채권 + 보증금) / 시세 ≤ 90% | 시세 + OCR |
| 선순위채권비율 | 선순위채권 / 시세 ≤ 60% | 시세 + OCR |
| 위반건축물 여부 | 위반이면 불가 (아파트 제외) | 건축물대장 발급 결과 |
| 권리침해 여부 | 경매·압류·가압류·가처분·가등기 이면 불가 | 등기부등본 OCR |
판정 결과는 세 가지입니다.
ELIGIBLE: 모든 요건 충족INELIGIBLE: 미충족 사유 1개 이상, 사유 목록 반환PENDING: 시세 미조회·OCR 미존재 등 판정에 필요한 데이터가 부족한 상태
보증보험 가입 가능 여부 분석 결과