동블

그래프 뷰

juso-address-search-api

6 min read

Juso 주소검색 팝업/검색 API 명세

Status: Source spec preserved

이 문서는 행정안전부 도로명주소 주소기반산업지원서비스 Juso 팝업 API와 직접 주소검색 API를 ZIP:ON 구현 기준으로 보존한 명세입니다. 실제 승인키는 이 문서에 남기지 않고 JUSO_ADDRESS_CONFIRM_KEY, JUSO_ADDRESS_SEARCH_KEY 같은 환경변수로만 관리합니다.

1. 팝업 API

호출방식구분요청 URL출력결과
POST / GET웹https://business.juso.go.kr/addrlink/addrLinkUrl.do파라미터

요청 변수

요청변수명타입필수여부설명
confmKeyStringY신청 시 발급받은 승인키
returnUrlStringY주소 검색 결과를 리턴받을 URL
resultTypeStringN도로명주소 검색결과 화면 출력유형. 1: 도로명, 2: 도로명 + 지번, 3: 도로명 + 상세 건물명, 4: 도로명 + 지번 + 상세 건물명
useDetailAddrStringN상세주소 동/층/호 정보 제공 여부. Y: 제공, N: 미제공/직접 입력

출력 변수

출력변수명타입필수여부설명
roadFullAddrStringY전체 도로명
roadAddrPart1StringY도로명주소, 참고항목 제외
roadAddrPart2StringN도로명주소 참고 항목
jibunAddrStringY지번주소
engAddrStringY도로명 영문
zipNoStringY우편번호
addrDetailStringN고객 입력 상세 주소
admCdStringY행정구역코드
rnMgtSnStringY도로명코드
bdMgtSnStringY건물관리번호
detBdNmListStringN상세건물명
bdNmStringN건물명
bdKdcdStringY공동주택 여부. 1: 공동주택, 0: 비공동주택
siNmStringY시도명
sggNmStringY시군구명
emdNmStringY읍면동명
liNmStringN법정리명
rnStringY도로명
udrtYnStringY지하여부. 0: 지상, 1: 지하
buldMnnmNumberY건물본번
buldSlnoNumberY건물부번
mtYnStringY산여부. 0: 대지, 1: 산
lnbrMnnmNumberY지번본번, 번지
lnbrSlnoNumberY지번부번, 호
emdNoStringY읍면동일련번호

2. 직접 주소검색 API

구분요청 URL출력결과
JSONP/XML/JSONhttps://business.juso.go.kr/addrlink/addrLinkApiJsonp.do주소 후보
XML/JSONhttps://business.juso.go.kr/addrlink/addrLinkApi.do주소 후보

ZIP:ON 구현은 백엔드 JusoAddressSearchApiClient에서 addrLinkApi.do를 resultType=json으로 호출한다. 프론트엔드는 Juso URL을 직접 호출하지 않고 GET /api/address-search/juso를 호출한다.

요청 변수

요청변수명타입필수여부기본값설명
confmKeyStringY없음신청 시 발급받은 주소검색용 승인키
currentPageStringY1현재 페이지 번호
countPerPageStringY10페이지당 출력 개수
keywordStringY없음주소 검색어
resultTypeStringNxmlZIP:ON은 json으로 고정
hstryYnStringNN변동이력 주소 포함 여부
firstSortStringNnone정렬. none, road, location
addInfoYnStringNN추가정보 제공 여부

응답 변수

영역출력변수명설명
commontotalCount총 검색 결과 수
commoncurrentPage현재 페이지 번호
commoncountPerPage페이지당 출력 개수
commonerrorCode결과 코드
commonerrorMessage결과 메시지
jusoroadAddr전체 도로명주소
jusoroadAddrPart1도로명주소, 참고항목 제외
jusoroadAddrPart2도로명주소 참고 항목
jusojibunAddr지번주소
jusoengAddr영문주소
jusozipNo우편번호
jusoadmCd행정구역코드
jusornMgtSn도로명코드
jusobdMgtSn건물관리번호
jusodetBdNmList상세건물명
jusobdNm건물명
jusobdKdcd공동주택 여부
jusosiNm, sggNm, emdNm, liNm시도/시군구/읍면동/법정리명
jusorn도로명
jusoudrtYn지하여부
jusobuldMnnm, buldSlno건물본번/부번
jusomtYn산여부
jusolnbrMnnm, lnbrSlno지번본번/부번
jusohstryYn변동이력 여부
jusorelJibun관련 지번
jusohemdNm행정동명

오류 코드

코드메시지/상황ZIP:ON 처리
0정상SUCCESS 또는 결과 0건이면 EMPTY
-999시스템에러ERROR
E0001승인되지 않은 KEYUNAVAILABLE
E0005검색어 없음INVALID_REQUEST
E0006주소가 상세하지 않음INVALID_REQUEST
E0008검색어 두 글자 미만INVALID_REQUEST
E0009문자와 숫자가 같이 입력되어야 함INVALID_REQUEST
E0010검색어가 너무 김INVALID_REQUEST
E0011너무 긴 숫자 포함INVALID_REQUEST
E0012특수문자 + 숫자만으로 검색INVALID_REQUEST
E0013SQL 예약어 또는 금지 특수문자 포함INVALID_REQUEST
E0014개발승인키 기간 만료UNAVAILABLE
E0015검색 범위 초과INVALID_REQUEST

ZIP:ON 구현 메모

  • 팝업용 키와 검색용 키는 서로 다르므로 JUSO_ADDRESS_CONFIRM_KEY, JUSO_ADDRESS_SEARCH_KEY를 분리한다.
  • JusoAddressSearchApiClient의 운영 로그 requestSummary에는 confmKey와 원문 검색어를 저장하지 않고 keywordHash만 남긴다.
  • 주소검색 결과는 현재 DB에 저장하지 않는다. 위험진단 이력에는 사용자가 선택해 제출한 주소 snapshot만 저장한다.
  • countPerPage는 Juso 원문 명세에 최대값이 명시되어 있지 않지만, ZIP:ON 백엔드는 과도한 요청을 막기 위해 1~100으로 제한한다.

관련 문서