공공데이터 API 연동 전략
Status: Current API Strategy
이 문서는 ZIP:ON이 외부 공공데이터 API를 어떤 순서로 붙여야 하는지, data.go.kr만으로 확정하기 어려운 영역은 무엇인지 정리합니다.
Goal
ZIP:ON은 주소를 받자마자 실거래가부터 조회하지 않습니다. 먼저 이 물건이 아파트, 다세대, 다가구, 오피스텔, 상가, 토지, 임야 중 무엇인지 판별해야 합니다.
현재 제품 방향에서는 현재 매물 목록을 제공하지 않습니다. 지역명, 역세권, 유형 키워드가 들어오면 매물을 나열하는 대신, 과거 실거래가와 한국부동산원 R-ONE 통계 지표를 사용해 가격 흐름, 전세·월세 흐름, 수익률, 공실률, 데이터 한계를 분석합니다.
1. 홈 화면 분석/진단 입력 폼에서 사용자 질의응답 시작
-> 2. 사용자 입력 정제
-> 3. 주소·좌표·법정동 코드 변환
-> 4. 물건 정체 판별
-> 5. 건축물·토지 기본정보 조회
-> 6. 시세·실거래가·공시가격 조회
-> 7. 용도지역·지적·토지규제 조회
-> 8. 전세·월세·매매 위험도 계산
-> 9. 목적별 추가 분석
-> 10. 생활·상권·안전·환경 분석
-> 11. 계약 전 확인사항 및 불가능 영역 안내처음부터 모든 API를 붙이면 복잡해집니다. MVP는 필수 코어부터 붙이고, 목적별 고도화와 계약 검증 보조 API를 뒤에 붙입니다.
API Priority
1순위: 필수 코어
아래 API는 물건 정체 판별, 시세 비교, 토지/건축물 기본 위험도까지 연결되는 MVP 기반입니다.
1. 행정안전부 주소 API
2. 법정동코드 API
3. 국토교통부 GIS건물통합정보
4. 국토교통부 건축HUB 건축물대장정보
5. 국토교통부 토지임야정보
6. 국토교통부 지적도
7. 국토교통부 실거래가 API 묶음
8. 공동주택가격/개별공시지가 API
9. 용도지역지구도 API2순위: 목적별 고도화
아래 API는 거주 적합성, 상권 적합성, 임야 리스크를 더 잘 설명하기 위한 확장 후보입니다.
10. 한국부동산원 R-ONE 부동산통계 조회 서비스
11. K-apt 공동주택 기본정보/관리비
12. 소상공인 상가정보 API
13. 생활안전지도 API
14. 교통사고 다발지역 API
15. NEIS 학교기본정보 API
16. 환경공간정보 토지피복지도
17. 홍수위험/도시침수 지도
18. 산사태위험지도3순위: 계약·검증 보조
아래 API는 계약 직전 체크리스트와 자영업 목적 분석에 유용합니다.
19. 지자체 부동산중개업소 현황
20. 국세청 사업자등록 상태조회
21. 부동산중개보수 요율표 데이터
22. 지자체 인허가 데이터Stage Details
1. 사용자 입력 정제
목표는 홈 화면 분석/진단 입력 폼에서 사용자가 답한 부동산 정보를 API 호출 가능한 지역, 유형, 주소, 좌표, 코드로 바꾸는 것입니다. 진단 폼 UI는 입력을 친절하게 나누어 받을 뿐이고, 실제 의도 분류, 주소 정제와 법정동코드 변환 책임은 백엔드 분석/진단 흐름에 남겨 둡니다.
사용자 입력
-> 주소 후보 검색
-> 도로명주소/지번주소 정규화
-> 법정동코드 추출
-> 시군구코드, 법정동코드, 본번, 부번 분리
-> 좌표 변환사용 API 후보:
- 행정안전부 실시간 주소정보 조회 API
- 행정안전부 실시간 상세주소정보 조회 API
- 행정안전부 도로명주소 주소DB
- 국토교통부 법정동코드
- 행정안전부 행정표준코드 법정동코드
2. 물건 정체 판별
목표는 사용자가 말한 “원룸”, “빌라”, “상가”, “시골 땅”을 공부상 물건 유형으로 바꾸는 것입니다.
사용 API 후보:
- 국토교통부 GIS건물통합정보
- 국토교통부 건축HUB 건축물대장정보 서비스
- 국토교통부 토지임야정보
- 국토교통부 지적도
주소/좌표 입력
-> GIS건물통합정보로 건물 존재 여부 확인
-> 건축물대장 표제부 조회
-> 주용도, 대장구분, 대장종류 확인
-> 전유부 존재 여부 확인
-> 토지임야정보로 지목·면적 확인
-> 물건 유형 자동 분류판별 결과 예시는 아래와 같습니다.
사용자 표현: 원룸
공부상 판별: 다가구주택
위험 분석 방향: 건물 전체 선순위 임차인 확인 필요
사용자 표현: 빌라
공부상 판별: 다세대주택
위험 분석 방향: 해당 호실 등기·전유부 중심 확인
사용자 표현: 상가
공부상 판별: 제1종 근린생활시설
위험 분석 방향: 업종 인허가 가능성 확인
사용자 표현: 시골 땅
공부상 판별: 임야
위험 분석 방향: 산지, 도로 접면, 개발 가능성 확인3. 상태 확인
건물은 주용도, 기타용도, 대장구분, 대장종류, 사용승인일, 건축면적, 연면적, 건폐율, 용적률, 층수, 세대수, 가구수, 주차대수, 승강기 수, 구조, 전유부 존재 여부, 폐쇄·말소 이력을 확인합니다.
사용 API 후보:
- 국토교통부 건축HUB 건축물대장정보 서비스
- 국토교통부 건축HUB 건축인허가정보 서비스
- 국토교통부 건축HUB 건축물유지점검정보 서비스
- 국토교통부 건축HUB 폐쇄말소대장정보 서비스
- 국토교통부 건축물연령정보
- 국토교통부 용도별건물정보
4. 시세·실거래가 확인
물건 유형에 따라 실거래가 API를 선택합니다.
아파트
-> 아파트 매매/전월세 실거래가 API
오피스텔
-> 오피스텔 매매/전월세 실거래가 API
상가
-> 상업업무용 부동산 매매 실거래가 API
토지/임야
-> 토지 매매 실거래가 API사용 API 후보:
- 국토교통부 아파트 매매 실거래가 자료
- 국토교통부 아파트 전월세 실거래가 자료
- 국토교통부 연립다세대 매매 실거래가 자료
- 국토교통부 연립다세대 전월세 실거래가 자료
- 국토교통부 단독/다가구 매매 실거래가 자료
- 국토교통부 단독/다가구 전월세 실거래가 자료
- 국토교통부 오피스텔 매매 실거래가 자료
- 국토교통부 오피스텔 전월세 실거래가 자료
- 국토교통부 상업업무용 부동산 매매 실거래가 자료
- 국토교통부 토지 매매 실거래가 자료
- 국토교통부 실거래가 정보
주의할 점은 실거래가가 과거 계약 데이터라는 것입니다. 현재 호가, 급매 여부, 권리관계, 실제 물건 상태는 별도 확인이 필요합니다.
5. 공시가격·공시지가 확인
전세, 매매, 세금, 대출, 보증보험 가능성 판단에는 공시가격도 필요합니다.
사용 API 후보:
- 국토교통부 공동주택가격정보
- 국토교통부 개별주택가격정보
- 국토교통부 개별공시지가정보
- 국토교통부 표준지공시지가정보
- 국토교통부 주택 공시가격 정보
6. 용도지역·지적·토지규제 확인
토지, 임야, 상가, 건물 매매에서는 이용 가능성과 법적 규제 확인이 중요합니다.
필지 경계 확인
-> 지목 확인
-> 용도지역/지구/구역 확인
-> 건폐율·용적률 판단 보조
-> 개발 가능성 1차 판별
-> 위험 문장 생성사용 API 후보:
- 국토교통부 용도지역지구도
- 국토교통부 일별용도지역지구정보
- 국토교통부 지적도
- 국토교통부 토지임야정보
- 국토교통부 일별토지임야정보
- 국토교통부 토지이용현황도
- 국토교통부 지가변동률정보
7. 전세·월세 위험도 판단
전세·월세는 “살기 좋은가”보다 “보증금이 안전한가”가 중요합니다.
7-1. 지역·유형 과거 지표 분석
목표는 현재 매물 목록을 보여주는 것이 아니라, 지역과 유형의 과거 흐름을 이해할 수 있게 하는 것입니다.
사용 API 후보:
- 한국부동산원 R-ONE 부동산통계 OpenAPI
- 유형별 실거래가 월별 집계 후보
사용자 입력: 강남 원룸
-> 현재 매물 목록 미제공
-> 원룸 후보 유형 분해: 오피스텔, 연립/다세대, 단독/다가구
-> R-ONE 가격지수/전세가격지수/월세가격지수/오피스텔 수익률 후보 조회
-> 과거 지표 추세, 변동성, 데이터 한계 설명사용자 입력: 상가 월세
-> 현재 상가 매물 목록 미제공
-> R-ONE 상가 임대가격지수, 임대료, 공실률 후보 조회
-> 창업 전 참고 지표와 현장 확인 항목 생성주의할 점은 R-ONE 통계가 현재 호가나 현재 매물 feed가 아니라는 것입니다. 지표 상승, 하락, 공실률은 지역 시장을 이해하는 보조 근거이며, 개별 물건의 계약 가능성이나 수익성을 확정하지 않습니다.
전세보증금 입력
-> 같은 유형 전월세 실거래가 조회
-> 매매 실거래가 또는 공시가격 조회
-> 건물 유형 확인
-> 다가구/다세대/오피스텔 여부 분기
-> 보증금 위험도 계산위험도 계산 예시는 아래와 같습니다.
전세가율 높음
+ 최근 매매 실거래 부족
+ 다가구주택
+ 건물 전체 선순위 보증금 미확인
= 전세 위험도 높음8. 매매 위험도 판단
매매는 소유권 이전과 가격 적정성이 핵심입니다.
매매가 입력
-> 같은 유형 실거래가 조회
-> 공시가격/공시지가 조회
-> 지역 부동산 통계 조회
-> 건축물 노후도 확인
-> 용도지역 확인
-> 매매 위험도 계산9. 자영업·상가 분석
상가나 자영업 목적은 주거용과 다르게 봐야 합니다.
사용자 업종 입력
-> 주변 동일/유사업종 밀집도 조회
-> 폐업/영업 상태 데이터 확인
-> 상업업무용 실거래가 조회
-> 건축물대장상 용도 확인
-> 인허가 가능성 체크리스트 생성주의할 점은 “이 자리에서 장사가 잘 된다”고 확정하면 안 된다는 것입니다. 주변 업소 분포, 인허가, 용도 가능성을 1차로 안내하고 실제 매출, 권리금, 유동인구 체감은 별도 조사로 분리합니다.
10. 생활 인프라·거주 적합성 분석
거주 목적에서는 생활 편의성과 안전이 중요합니다.
사용 API 후보:
- 교육부 NEIS 초중등 학교기본정보
- 국토교통부 공동주택 기본 정보제공 서비스
- 공동주택 관리비 데이터
- 행정안전부 생활안전지도 치안안전시설
- 행정안전부 생활안전지도 범죄주의구간
- 한국도로교통공단 보행자 교통사고 다발지역
- 한국도로교통공단 자전거 교통사고 다발지역
11. 임야·토지·개발 가능성 분석
토지와 임야는 싸냐 비싸냐보다 쓸 수 있는 땅인지가 먼저입니다.
토지/임야 판별
-> 지목 확인
-> 필지 경계 확인
-> 용도지역 확인
-> 공시지가 확인
-> 산림·토양·산사태 위험 확인
-> 개발 가능성 체크리스트 생성API만으로 확정하기 어려운 부분:
- 실제 진입로 사용 권리
- 사도 통행 동의 여부
- 분묘 존재 여부
- 현장 경사·배수 상태
- 전기·수도 인입 비용
- 실제 개발행위허가 가능 여부
12. 환경·재난 리스크 분석
토지, 임야, 저지대 주택, 해안가 물건은 환경·재난 데이터를 보조로 확인합니다.
사용 API 후보:
- 기후에너지환경부 환경공간정보 토지피복지도 맵 서비스
- 한강홍수통제소 권역별 빈도별 도시침수지도
- 전국 빈도별 지방하천 하천범람 지도 침수심 통계 조회 서비스
- 행정안전부 생활안전지도 열분포도
- 행정안전부 생활안전지도 지진실내구호소
- 행정안전부 생활안전지도 산사태위험지도
13. 계약 상대방·중개사 확인
물건뿐 아니라 사람과 업체도 확인해야 합니다.
중개사무소명/주소 입력
-> 지자체 중개업소 데이터 조회
-> 등록 여부 확인
-> 행정처분 여부 확인
-> 사업자 상태조회 보조
-> 중개보수 예상 계산전국 통합 중개업소 API가 깔끔하게 하나로 제공되지 않을 수 있으므로 지자체별 데이터, 원천 확인, 사용자 입력 검증 구조가 필요합니다.
Areas data.go.kr Cannot Fully Solve
1. 등기부등본 권리분석
자동으로 확정하기 어려운 항목:
- 소유자 실시간 확인
- 근저당권
- 가압류
- 압류
- 신탁등기
- 전세권
- 가등기
- 경매개시결정
대안:
사용자에게 등기부등본 PDF 업로드 요청
-> OCR/문서 파싱
-> 권리관계 요약
-> 위험 문장 생성2. 선순위 임차인 보증금
다가구주택 전세에서 매우 중요하지만 API로 자동 확인하기 어렵습니다.
대안:
- 임대인에게 선순위 임대차 내역 요청
- 중개대상물 확인설명서 확인
- 확정일자 부여현황 확인 안내
- 사용자가 받은 자료 업로드 후 분석
3. 실제 하자
API로 알기 어려운 항목:
- 누수
- 곰팡이
- 층간소음
- 악취
- 수압
- 채광
- 결로
- 이웃 문제
대안은 현장 방문 체크리스트 제공입니다.
4. 실제 영업 가능성
API로 알기 어려운 항목:
- 실제 유동인구 체감
- 권리금 적정성
- 건물주 성향
- 관리단 업종 제한
- 배달 동선
- 간판 시인성
상권 API는 1차 분석으로 쓰고, 현장조사와 임대차계약서 확인은 별도 단계로 분리합니다.
Scenario-Based API Flows
원룸 전세 안전 진단
핵심은 다가구인지 다세대인지 먼저 구분하는 것입니다.
1. 주소 API
2. 법정동코드 API
3. GIS건물통합정보
4. 건축HUB 건축물대장정보
5. 전유부/표제부/층별개요 조회
6. 연립다세대·오피스텔·단독다가구 전월세 실거래가 API
7. 매매 실거래가 API
8. 공동주택가격/개별주택가격 API
9. 생활안전지도/교통사고/학교 정보 API
10. 등기부등본은 사용자 업로드 또는 직접 열람 안내상가 카페 가능성 진단
핵심은 건물 용도, 업종 인허가, 주변 경쟁업소입니다.
1. 주소 API
2. 건축HUB 건축물대장정보
3. 주용도/기타용도 확인
4. 용도지역지구도 API
5. 상업업무용 실거래가 API
6. 소상공인 상가정보 API
7. 음식점·휴게음식점 인허가 데이터
8. 사업자등록 상태조회 API
9. 현장 확인 항목 생성임야 매수 가능성 진단
핵심은 싸냐 비싸냐보다 쓸 수 있는 땅인지입니다.
1. 주소/지번 정제
2. 토지임야정보
3. 지적도
4. 용도지역지구도
5. 토지이용현황도
6. 개별공시지가정보
7. 산림입지도
8. 임상도
9. 산사태위험지도
10. 도시침수/하천범람 지도
11. 개발행위 가능성은 지자체 문의 안내작은 건물 매매 진단
핵심은 건물 자체가 아니라 임대수익 구조를 사는 것이라는 점입니다.
1. 주소 API
2. GIS건물통합정보
3. 건축HUB 건축물대장정보
4. 건축물연령정보
5. 건축인허가정보
6. 상업업무용/단독다가구/토지 실거래가 API
7. 공시가격/공시지가 API
8. 용도지역지구도
9. 한국부동산원 부동산통계 API
10. 등기·임대차 현황은 사용자 자료 입력 또는 업로드Design Tradeoffs
외부 API를 많이 붙일수록 서비스가 똑똑해 보일 수 있지만, 호출 순서와 해석 기준이 없으면 사용자는 더 혼란스러워집니다. ZIP:ON은 “물건 정체 판별 → 목적별 API 선택 → 위험 문장 → 체크리스트” 순서를 유지해야 합니다.
확정할 수 없는 영역을 자동 판정처럼 보여주면 제품 신뢰도가 떨어집니다. 따라서 권리관계, 선순위 임차인, 실제 하자, 영업 가능성은 반드시 “추가 확인 필요” 또는 “사용자 자료 업로드 필요”로 분리합니다.
Related Documents
Learning Path
- First read:
Goal과API Priority - Then inspect:
Stage Details의 1~7단계 - Then run: 실제 구현 전에는 루트
README.md의 실행 명령으로 현재 앱 상태부터 확인 - Then debug:
Areas data.go.kr Cannot Fully Solve를 보고 자동 판정 금지 영역을 분리 - Key concept to understand: 외부 API 연동은 기술 문제가 아니라 서비스 질문을 데이터 조회 순서로 번역하는 일