nomadamas__k-skill/docs/features/building-register-search.md

건축물대장 표제부 조회 가이드

개요

building-register-search는 공공데이터포털 데이터셋 15134735의 국토교통부 건축물대장정보 서비스 getBrTitleInfo를 조회한다. 공식 XML 응답을 k-skill-proxy가 파싱해 표제부 항목과 pagination/source metadata를 JSON으로 반환한다.

건축물대장은 건축물의 용도, 면적, 층수, 사용승인일 같은 행정대장 정보다. 소유권, 근저당, 가압류 등 등기 권리관계는 포함하지 않는다. 권리관계 확인은 등기부등본 자동화 가이드를 별도로 사용한다.

입력 경로

주소는 proxy mode에서 /v1/kakao-local/geocode?q=...&limit=2를 먼저 호출한다. 정확히 하나의 Kakao address 문서에서 10자리 법정동 b_code, mountain_yn, main_address_no, sub_address_no를 읽고 건축물대장 API의 개별 필드로 /v1/building-register/title을 호출한다. 모호한 결과, 키워드 장소 결과, 법정동 코드/본번 누락은 명시적으로 중단한다.

npx -y @nomadamas/k-skill@0 exec building-register-search scripts/building_register.py -- title --address '서울 강남구 역삼동 123-4'
npx -y @nomadamas/k-skill@0 exec building-register-search scripts/building_register.py -- title --pnu 1168010100101230004
npx -y @nomadamas/k-skill@0 exec building-register-search scripts/building_register.py -- title \
  --sigungu-cd 11680 --bjdong-cd 10100 --plat-gb-cd 0 --bun 123 --ji 4

PNU는 sigunguCd(5) + bjdongCd(5) + 토지구분(1) + bun(4) + ji(4)의 19자리다. PNU 토지구분 1(일반 토지)은 건축물대장 API platGbCd=0, 2(산)는 platGbCd=1로 변환한다. 개별 입력의 --plat-gb-cd는 PNU 숫자가 아니라 건축물대장 API 값이다. bun과 ji는 각각 4자리로 zero-padding되고 ji 생략 시 0000이다. pageNo=1, numOfRows=10이 기본이며 numOfRows 최대값은 100이다.

Hosted와 direct

hosted proxy는 사용자 키가 필요 없다. route는 caller의 serviceKey를 거부하고 서버의 DATA_GO_KR_API_KEY만 upstream에 주입한다.

npx -y @nomadamas/k-skill@0 exec building-register-search scripts/building_register.py -- title --pnu 1168010100101230004 --direct

direct mode는 PNU 또는 개별 코드/필지만 지원하고 주소 geocoding은 지원하지 않는다. 키 우선순위는 KSKILL_BUILDING_REGISTER_API_KEY -> DATA_GO_KR_API_KEY -> ~/.config/k-skill/secrets.env다. --dry-run은 키를 REDACTED로 표시한다.

self-host 운영자와 direct 사용자는 공공데이터포털에서 키를 발급받은 뒤 데이터셋 15134735의 활용신청을 별도로 완료해야 한다. 자동승인 대상이어도 서비스 활성화 전에는 401/403 또는 인증 오류 XML이 반환될 수 있다.

출력과 fallback

기본은 한국어 요약, --json은 normalized JSON이다. mainPurpsCdNm, totArea, grndFlrCnt, ugrndFlrCnt, useAprDay, platPlc, newPlatPlc, mgmBldrgstPk와 API의 유용한 원문 필드를 보존한다.

접근 순서는 PNU 직접 조회, 법정동 코드+필지 정규화, proxy 주소 geocode 순이다. 주소가 모호하거나 필지가 빠지면 더 정확한 지번/PNU를 요청한다. official API 인증, 쿼터, 장애 시 비공식 화면 scraping으로 우회하지 않는다.

실패 모드

• 결과 0건: 해당 필지에 표제부가 없거나 입력 필지가 다름
• 주소 모호/필지 누락: 법정동 b_code와 본번을 확정하지 못함
• 503 upstream_not_configured: self-host proxy 서버 키 누락
• 502 upstream_forbidden: 401/403, gateway auth XML, semantic auth result code
• quota/service error: 이용량 또는 공공데이터포털 서비스 상태 확인
• 빈 응답/잘못된 XML: upstream invalid response, 캐시하지 않음
• proxy down: 재시도 또는 운영자 확인