Daum Postcode Service User Guide

기본 사용법

!

꼭 읽어주세요!!

JS API의 최신화는 업데이트시마다 자동으로 되고 있습니다.
JS API호출시 도메인 뒤에 특정 파라미터의 경우엔 가이드페이지(아래 기본사용법)에서 정의하고 있는 특정 파라미터 외엔 허용하지 않습니다.
이외 더미 파라미터와 같은 데이터를 붙혀서 로딩하실 경우, 스크립트 호출이 거부 될수 있으니 삭제 부탁드립니다.
ex) ?_=XXXXXX, ?t=5469821879 등등

- 허용하는 파라미터
1. 통합로딩방식 : 없음
2. (구)로딩방식 : autoload=false
ㄴ ex) https://ssl.daumcdn.net/dmaps/map_js_init/postcode.v2.js?autoload=false
ㄴ ex) http://dmaps.daum.net/map_js_init/postcode.v2.js?autoload=false

허용하는 파라미터는 위와 같으며,
이외 다른 파라미터를 붙혀서 이용하시는 경우 스크립트 호출이 거부 될수 있으니 반드시 삭제 바랍니다.
아래 제약사항 적용 일정을 참고 하시어, 만약 더미 파라미터 또는 불필요한 파라미터를 붙혀서 사용하신다면 아래 일정 안에 제거해 주시기 바랍니다.
단, 기본 사용법에 따라 정상적으로 사용하고 계신 분들의 경우 아무런 조치가 필요 없으니 참고 바랍니다.

제약사항 적용 일정
- 2020년 12월 17일 : 개발자도구 콘솔창에 error 로그 표출 (우편번호 서비스 팝업 또는 레이어가 동작할때마다 표출)
- 2021년 1월 28일 : error 로그 + alert(경고창)으로 가이드 강화
- 2021년 3월 31일 : API 사용 제한(스크립트 요청은 가능하나 서비스 이용은 중지 됩니다.)

Daum 우편번호 서비스를 이용하려면,
우편번호 검색 팝업창을 띄우고자 하는 페이지에 아래와 같은 방식으로 코드를 넣으면 됩니다.

통합 로딩 방식 : postcode.v2.js 라는 이름의 파일 로딩을 통해 우편번호 서비스를 이용하실 수 있습니다.

예제

!

꼭 읽어주세요!!

아래 제작된 5개의 예제는 저희 API를 이용함에 있어 이해를 돕기위해 제작된 것입니다.
코드를 실제 서비스에 적용시, 예제에 정의된 HTML Tag구조와 style 값, 그리고 oncomplete함수의 정의 부분은 이용하시는 각 사이트의 상황에 맞게 적절히 수정하여 적용하시기 바랍니다.

도로명 주소의 구성 및 표기하는 방법은 법령을 통해 정하고 있으며, 해당 사항은 도로명주소법 시행령 제6조(도로명주소의 구성 및 표기 방법) 부분을 참고해 주시기 바랍니다.

팝업을 이용하여 도로명 주소와 지번 주소 모두 보여주기

기본적인 팝업을 이용하여 사용자가 선택한 주소의 도로명 주소와 지번 주소를 모두 보여주는 방식입니다. 아래 '우편번호 찾기' 버튼을 클릭해서 바로 확인해보세요. (몇몇 Webview기반 브라우저의 window.open 미대응으로 인하여, Webview기반 서비스에 적용시 embed()를 이용한 레이어모드를 추천합니다.)
예제 코드보기

// 도로명 주소의 노출 규칙에 따라 주소를 표시한다.
                // 내려오는 변수가 값이 없는 경우엔 공백('')값을 가지므로, 이를 참고하여 분기 한다.
                var roadAddr = data.roadAddress; // 도로명 주소 변수
                var extraRoadAddr = ''; // 참고 항목 변수

// 법정동명이 있을 경우 추가한다. (법정리는 제외)
                // 법정동의 경우 마지막 문자가 "동/로/가"로 끝난다.
                if(data.bname !== '' && /[동|로|가]$/g.test(data.bname)){
                    extraRoadAddr += data.bname;
                }
                // 건물명이 있고, 공동주택일 경우 추가한다.
                if(data.buildingName !== '' && data.apartment === 'Y'){
                   extraRoadAddr += (extraRoadAddr !== '' ? ', ' + data.buildingName : data.buildingName);
                }
                // 표시할 참고항목이 있을 경우, 괄호까지 추가한 최종 문자열을 만든다.
                if(extraRoadAddr !== ''){
                    extraRoadAddr = ' (' + extraRoadAddr + ')';
                }

// 우편번호와 주소 정보를 해당 필드에 넣는다.
                document.getElementById('sample4_postcode').value = data.zonecode;
                document.getElementById("sample4_roadAddress").value = roadAddr;
                document.getElementById("sample4_jibunAddress").value = data.jibunAddress;
                
                // 참고항목 문자열이 있을 경우 해당 필드에 넣는다.
                if(roadAddr !== ''){
                    document.getElementById("sample4_extraAddress").value = extraRoadAddr;
                } else {
                    document.getElementById("sample4_extraAddress").value = '';
                }

var guideTextBox = document.getElementById("guide");
                // 사용자가 '선택 안함'을 클릭한 경우, 예상 주소라는 표시를 해준다.
                if(data.autoRoadAddress) {
                    var expRoadAddr = data.autoRoadAddress + extraRoadAddr;
                    guideTextBox.innerHTML = '(예상 도로명 주소 : ' + expRoadAddr + ')';
                    guideTextBox.style.display = 'block';

} else if(data.autoJibunAddress) {
                    var expJibunAddr = data.autoJibunAddress;
                    guideTextBox.innerHTML = '(예상 지번 주소 : ' + expJibunAddr + ')';
                    guideTextBox.style.display = 'block';
                } else {
                    guideTextBox.innerHTML = '';
                    guideTextBox.style.display = 'none';
                }
            }
        }).open();
    }
</script>

사용자가 선택한 값 이용하기

우편번호와 주소필드에 사용자가 선택한 주소 값을 채워 넣는 방식입니다.
단, 사용자가 선택한 값을 이용할 경우 영문주소와 정확히 매칭되지 않을 수 있습니다. 영문주소는 기본주소(address)에 해당하는 영문 주소가 내려갑니다. 예제 코드보기

// 각 주소의 노출 규칙에 따라 주소를 조합한다.
                // 내려오는 변수가 값이 없는 경우엔 공백('')값을 가지므로, 이를 참고하여 분기 한다.
                var addr = ''; // 주소 변수
                var extraAddr = ''; // 참고항목 변수

//사용자가 선택한 주소 타입에 따라 해당 주소 값을 가져온다.
                if (data.userSelectedType === 'R') { // 사용자가 도로명 주소를 선택했을 경우
                    addr = data.roadAddress;
                } else { // 사용자가 지번 주소를 선택했을 경우(J)
                    addr = data.jibunAddress;
                }

// 사용자가 선택한 주소가 도로명 타입일때 참고항목을 조합한다.
                if(data.userSelectedType === 'R'){
                    // 법정동명이 있을 경우 추가한다. (법정리는 제외)
                    // 법정동의 경우 마지막 문자가 "동/로/가"로 끝난다.
                    if(data.bname !== '' && /[동|로|가]$/g.test(data.bname)){
                        extraAddr += data.bname;
                    }
                    // 건물명이 있고, 공동주택일 경우 추가한다.
                    if(data.buildingName !== '' && data.apartment === 'Y'){
                        extraAddr += (extraAddr !== '' ? ', ' + data.buildingName : data.buildingName);
                    }
                    // 표시할 참고항목이 있을 경우, 괄호까지 추가한 최종 문자열을 만든다.
                    if(extraAddr !== ''){
                        extraAddr = ' (' + extraAddr + ')';
                    }
                    // 조합된 참고항목을 해당 필드에 넣는다.
                    document.getElementById("sample6_extraAddress").value = extraAddr;
                
                } else {
                    document.getElementById("sample6_extraAddress").value = '';
                }

// 우편번호와 주소 정보를 해당 필드에 넣는다.
                document.getElementById('sample6_postcode').value = data.zonecode;
                document.getElementById("sample6_address").value = addr;
                // 커서를 상세주소 필드로 이동한다.
                document.getElementById("sample6_detailAddress").focus();
            }
        }).open();
    }
</script>

iframe을 이용하여 레이어 띄우기

모바일웹에서는 팝업을 띄우는게 부담스러울 수도 있으니, 아래 코드와 같이 특정 element에 크기를 지정하여 iframe으로 끼워넣는 방식을 이용할 수도 있습니다. 아래 '우편번호 찾기' 버튼을 클릭해서 바로 확인해보세요.
(현재 iOS 8.x 이상, Safari, webview 브라우저에서 position:fixed, inner-scroll 이용시 가상키보드 터치 불량 및 스크롤이 멈추는 현상이 간혈적으로 발생하고 있습니다. 이점 참고해 주시기 바라며, 모바일 환경에서는 가급적 아래의 "페이지에 끼워넣기" 예제를 참고하시는 것을 추천드립니다.)
예제 코드보기

<div id="layer" style="display:none;position:fixed;overflow:hidden;z-index:1;-webkit-overflow-scrolling:touch;">
<img src="//t1.daumcdn.net/postcode/resource/images/close.png" id="btnCloseLayer" style="cursor:pointer;position:absolute;right:-3px;top:-3px;z-index:1" onclick="closeDaumPostcode()" alt="닫기 버튼">
</div>

function closeDaumPostcode() {
        // iframe을 넣은 element를 안보이게 한다.
        element_layer.style.display = 'none';
    }

function sample2_execDaumPostcode() {
        new daum.Postcode({
            oncomplete: function(data) {
                // 검색결과 항목을 클릭했을때 실행할 코드를 작성하는 부분.

// 각 주소의 노출 규칙에 따라 주소를 조합한다.
                // 내려오는 변수가 값이 없는 경우엔 공백('')값을 가지므로, 이를 참고하여 분기 한다.
                var addr = ''; // 주소 변수
                var extraAddr = ''; // 참고항목 변수

//사용자가 선택한 주소 타입에 따라 해당 주소 값을 가져온다.
                if (data.userSelectedType === 'R') { // 사용자가 도로명 주소를 선택했을 경우
                    addr = data.roadAddress;
                } else { // 사용자가 지번 주소를 선택했을 경우(J)
                    addr = data.jibunAddress;
                }

// 사용자가 선택한 주소가 도로명 타입일때 참고항목을 조합한다.
                if(data.userSelectedType === 'R'){
                    // 법정동명이 있을 경우 추가한다. (법정리는 제외)
                    // 법정동의 경우 마지막 문자가 "동/로/가"로 끝난다.
                    if(data.bname !== '' && /[동|로|가]$/g.test(data.bname)){
                        extraAddr += data.bname;
                    }
                    // 건물명이 있고, 공동주택일 경우 추가한다.
                    if(data.buildingName !== '' && data.apartment === 'Y'){
                        extraAddr += (extraAddr !== '' ? ', ' + data.buildingName : data.buildingName);
                    }
                    // 표시할 참고항목이 있을 경우, 괄호까지 추가한 최종 문자열을 만든다.
                    if(extraAddr !== ''){
                        extraAddr = ' (' + extraAddr + ')';
                    }
                    // 조합된 참고항목을 해당 필드에 넣는다.
                    document.getElementById("sample2_extraAddress").value = extraAddr;
                
                } else {
                    document.getElementById("sample2_extraAddress").value = '';
                }

// 우편번호와 주소 정보를 해당 필드에 넣는다.
                document.getElementById('sample2_postcode').value = data.zonecode;
                document.getElementById("sample2_address").value = addr;
                // 커서를 상세주소 필드로 이동한다.
                document.getElementById("sample2_detailAddress").focus();

// iframe을 넣은 element를 안보이게 한다.
                // (autoClose:false 기능을 이용한다면, 아래 코드를 제거해야 화면에서 사라지지 않는다.)
                element_layer.style.display = 'none';
            },
            width : '100%',
            height : '100%',
            maxSuggestItems : 5
        }).embed(element_layer);

// iframe을 넣은 element를 보이게 한다.
        element_layer.style.display = 'block';

// iframe을 넣은 element의 위치를 화면의 가운데로 이동시킨다.
        initLayerPosition();
    }

// 브라우저의 크기 변경에 따라 레이어를 가운데로 이동시키고자 하실때에는
    // resize이벤트나, orientationchange이벤트를 이용하여 값이 변경될때마다 아래 함수를 실행 시켜 주시거나,
    // 직접 element_layer의 top,left값을 수정해 주시면 됩니다.
    function initLayerPosition(){
        var width = 300; //우편번호서비스가 들어갈 element의 width
        var height = 400; //우편번호서비스가 들어갈 element의 height
        var borderWidth = 5; //샘플에서 사용하는 border의 두께

// 위에서 선언한 값들을 실제 element에 넣는다.
        element_layer.style.width = width + 'px';
        element_layer.style.height = height + 'px';
        element_layer.style.border = borderWidth + 'px solid';
        // 실행되는 순간의 화면 너비와 높이 값을 가져와서 중앙에 뜰 수 있도록 위치를 계산한다.
        element_layer.style.left = (((window.innerWidth || document.documentElement.clientWidth) - width)/2 - borderWidth) + 'px';
        element_layer.style.top = (((window.innerHeight || document.documentElement.clientHeight) - height)/2 - borderWidth) + 'px';
    }
</script>

iframe을 이용하여 페이지에 끼워 넣기

화면내에 끼워넣는 방식일 경우, 내부 스크롤이 거슬릴수도 있습니다. 이때 onresize 속성을 추가해서 iframe 높이를 조절하면 스크롤이 생기지 않습니다. 아래 '우편번호 찾기' 버튼을 클릭해서 바로 확인해보세요. 예제 코드보기

function foldDaumPostcode() {
        // iframe을 넣은 element를 안보이게 한다.
        element_wrap.style.display = 'none';
    }

function sample3_execDaumPostcode() {
        // 현재 scroll 위치를 저장해놓는다.
        var currentScroll = Math.max(document.body.scrollTop, document.documentElement.scrollTop);
        new daum.Postcode({
            oncomplete: function(data) {
                // 검색결과 항목을 클릭했을때 실행할 코드를 작성하는 부분.

// 각 주소의 노출 규칙에 따라 주소를 조합한다.
                // 내려오는 변수가 값이 없는 경우엔 공백('')값을 가지므로, 이를 참고하여 분기 한다.
                var addr = ''; // 주소 변수
                var extraAddr = ''; // 참고항목 변수

//사용자가 선택한 주소 타입에 따라 해당 주소 값을 가져온다.
                if (data.userSelectedType === 'R') { // 사용자가 도로명 주소를 선택했을 경우
                    addr = data.roadAddress;
                } else { // 사용자가 지번 주소를 선택했을 경우(J)
                    addr = data.jibunAddress;
                }

// 사용자가 선택한 주소가 도로명 타입일때 참고항목을 조합한다.
                if(data.userSelectedType === 'R'){
                    // 법정동명이 있을 경우 추가한다. (법정리는 제외)
                    // 법정동의 경우 마지막 문자가 "동/로/가"로 끝난다.
                    if(data.bname !== '' && /[동|로|가]$/g.test(data.bname)){
                        extraAddr += data.bname;
                    }
                    // 건물명이 있고, 공동주택일 경우 추가한다.
                    if(data.buildingName !== '' && data.apartment === 'Y'){
                        extraAddr += (extraAddr !== '' ? ', ' + data.buildingName : data.buildingName);
                    }
                    // 표시할 참고항목이 있을 경우, 괄호까지 추가한 최종 문자열을 만든다.
                    if(extraAddr !== ''){
                        extraAddr = ' (' + extraAddr + ')';
                    }
                    // 조합된 참고항목을 해당 필드에 넣는다.
                    document.getElementById("sample3_extraAddress").value = extraAddr;
                
                } else {
                    document.getElementById("sample3_extraAddress").value = '';
                }

// 우편번호와 주소 정보를 해당 필드에 넣는다.
                document.getElementById('sample3_postcode').value = data.zonecode;
                document.getElementById("sample3_address").value = addr;
                // 커서를 상세주소 필드로 이동한다.
                document.getElementById("sample3_detailAddress").focus();

// iframe을 넣은 element를 안보이게 한다.
                // (autoClose:false 기능을 이용한다면, 아래 코드를 제거해야 화면에서 사라지지 않는다.)
                element_wrap.style.display = 'none';

// 우편번호 찾기 화면이 보이기 이전으로 scroll 위치를 되돌린다.
                document.body.scrollTop = currentScroll;
            },
            // 우편번호 찾기 화면 크기가 조정되었을때 실행할 코드를 작성하는 부분. iframe을 넣은 element의 높이값을 조정한다.
            onresize : function(size) {
                element_wrap.style.height = size.height+'px';
            },
            width : '100%',
            height : '100%'
        }).embed(element_wrap);

// iframe을 넣은 element를 보이게 한다.
        element_wrap.style.display = 'block';
    }
</script>

주소를 선택하면 지도도 함께 보여주기

다음 지도 API를 함께 활용하여 선택한 주소에 대한 좌표를 가져와서 지도에 표시하는 예제입니다. 아래 '주소 검색' 버튼을 클릭해서 바로 확인해보세요.
다음 지도 API를 이용하시려면 https://developers.kakao.com에서 API Key를 발급받으셔야 합니다. 예제 코드보기

//지도를 미리 생성
    var map = new daum.maps.Map(mapContainer, mapOption);
    //주소-좌표 변환 객체를 생성
    var geocoder = new daum.maps.services.Geocoder();
    //마커를 미리 생성
    var marker = new daum.maps.Marker({
        position: new daum.maps.LatLng(37.537187, 127.005476),
        map: map
    });

function sample5_execDaumPostcode() {
        new daum.Postcode({
            oncomplete: function(data) {
                var addr = data.address; // 최종 주소 변수

// 주소 정보를 해당 필드에 넣는다.
                document.getElementById("sample5_address").value = addr;
                // 주소로 상세 정보를 검색
                geocoder.addressSearch(data.address, function(results, status) {
                    // 정상적으로 검색이 완료됐으면
                    if (status === daum.maps.services.Status.OK) {

var result = results[0]; //첫번째 결과의 값을 활용

// 해당 주소에 대한 좌표를 받아서
                        var coords = new daum.maps.LatLng(result.y, result.x);
                        // 지도를 보여준다.
                        mapContainer.style.display = "block";
                        map.relayout();
                        // 지도 중심을 변경한다.
                        map.setCenter(coords);
                        // 마커를 결과값으로 받은 위치로 옮긴다.
                        marker.setPosition(coords)
                    }
                });
            }
        }).open();
    }
</script>

속성

daum.Postcode의 생성자 속성들은 아래와 같습니다.

oncomplete

우편번호 검색 결과 목록에서 특정 항목을 클릭한 경우, 해당 정보를 받아서 처리할 콜백 함수를 정의하는 부분입니다.(null값 또는 정의하지 않을 시에 검색은 가능하지만, 결과 항목을 클릭하면 아무 일도 일어나지 않습니다.)
이 함수를 정의할때 넣는 인자에는 우편번호 검색 결과 목록에서 사용자가 클릭한 주소 정보가 들어가게 됩니다.

버튼을 클릭해서 실제 데이터를 확인해보세요. (모든 데이터는 문자열이며, 값이 없을 경우 공백입니다.)

oncomplete 반환 인자
항목	값	설명
`zonecode`	13529	국가기초구역번호. 2015년 8월 1일부터 시행될 새 우편번호.
`address`	경기 성남시 분당구 판교역로 166	기본 주소 (검색 결과에서 첫줄에 나오는 주소, 검색어의 타입(지번/도로명)에 따라 달라집니다.)
`addressEnglish`	166 Pangyoyeok-ro, Bundang-gu, Seongnam-si, Gyeonggi-do, Republic of Korea	기본 영문 주소
`addressType`	R/J	검색된 기본 주소 타입: R(도로명), J(지번)
`userSelectedType`	R/J	검색 결과에서 사용자가 선택한 주소의 타입
`noSelected`	Y/N	연관 주소에서 "선택 안함" 부분을 선택했을때를 구분할 수 있는 상태변수
`userLanguageType`	K/E	검색 결과에서 사용자가 선택한 주소의 언어 타입: K(한글주소), E(영문주소)
`roadAddress`	경기 성남시 분당구 판교역로 166	도로명 주소 (지번:도로명 주소가 1:N인 경우에는 데이터가 공백으로 들어갈 수 있습니다. - 아래 autoRoadAddress의 자세한 설명 참고)
`roadAddressEnglish`	166 Pangyoyeok-ro, Bundang-gu, Seongnam-si, Gyeonggi-do, Republic of Korea	영문 도로명 주소
`jibunAddress`	경기 성남시 분당구 백현동 532	지번 주소 (도로명:지번 주소가 1:N인 경우에는 데이터가 공백으로 들어갈 수 있습니다. - 아래 autoJibunAddress의 자세한 설명 참고)
`jibunAddressEnglish`	532 Baekhyeon-dong, Bundang-gu, Seongnam-si, Gyeonggi-do, Republic of Korea	영문 지번 주소
`autoRoadAddress`	경기 성남시 분당구 판교역로 166	'지번주소'에 매핑된 '도로명주소'가 여러개인 경우, 사용자가 '선택안함' 또는 '지번주소'를 클릭했을 때 연관된 도로명 주소 중 임의로 첫번째 매핑 주소를 넣어서 반환합니다. (autoMapping을 false로 설정한 경우에는 값이 채워지지 않습니다.)
`autoRoadAddressEnglish`	166 Pangyoyeok-ro, Bundang-gu, Seongnam-si, Gyeonggi-do, Republic of Korea	autoRoadAddress의 영문 도로명 주소
`autoJibunAddress`	경기 성남시 분당구 백현동 532	'도로명주소'에 매핑된 '지번주소'가 여러개인 경우, 사용자가 '선택안함' 또는 '도로명주소'를 클릭했을 때 연관된 지번 주소 중 임의로 첫번째 매핑 주소를 넣어서 반환합니다. (autoMapping을 false로 설정한 경우에는 값이 채워지지 않습니다.)
`autoJibunAddressEnglish`	532 Baekhyeon-dong, Bundang-gu, Seongnam-si, Gyeonggi-do, Republic of Korea	autoJibunAddress의 영문 지번 주소
`buildingCode`	4113511000105320000000002	건물관리번호
`buildingName`	카카오 판교 아지트	건물명
`apartment`	Y/N	공동주택 여부 (아파트,연립주택,다세대주택 등)
`sido`	경기	도/시 이름
`sidoEnglish`	Gyeonggi-do	도/시 이름의 영문
`sigungu`	성남시 분당구	시/군/구 이름
`sigunguEnglish`	Bundang-gu Seongnam-si	시/군/구 이름의 영문
`sigunguCode`	41135	시/군/구 코드 (5자리 구성된 시/군/구 코드입니다.)
`roadnameCode`	3179025	도로명 코드, 7자리로 구성된 도로명 코드입니다. 추후 7자리 이상으로 늘어날 수 있습니다.
`bcode`	4113511000	법정동/법정리 코드
`roadname`	판교역로	도로명 값, 검색 결과 중 선택한 도로명주소의 "도로명" 값이 들어갑니다.(건물번호 제외)
`roadnameEnglish`	Pangyoyeok-ro	도로명 값, 검색 결과 중 선택한 도로명주소의 "도로명의 영문" 값이 들어갑니다.(건물번호 제외)
`bname`	백현동	법정동/법정리 이름
`bnameEnglish`	Baekhyeon-dong	법정동/법정리 이름의 영문
`bname1`		법정리의 읍/면 이름 ("동"지역일 경우에는 공백, "리"지역일 경우에는 "읍" 또는 "면" 정보가 들어갑니다.)
`bname1English`		법정리의 읍/면 이름의 영문 ("동"지역일 경우에는 공백, "리"지역일 경우에는 "읍" 또는 "면" 정보가 들어갑니다.)
`bname2`	백현동	법정동/법정리 이름
`bname2English`	Baekhyeon-dong	법정동/법정리 이름의 영문
`hname`	-	행정동 이름, 검색어를 행정동으로 검색하고, 검색결과의 법정동과 검색어에 입력한 행정동과 다른 경우에 표시하고, 데이터를 내립니다.
`query`	판교역로 166	사용자가 입력한 검색어
`postcode`	-	구 우편번호 (2020년 3월 9일 이후로는 데이터가 내려가지 않습니다.)
`postcode1`	-	구 우편번호 앞 3자리 (2020년 3월 9일 이후로는 데이터가 내려가지 않습니다.)
`postcode2`	-	구 우편번호 뒤 3자리 (2020년 3월 9일 이후로는 데이터가 내려가지 않습니다.)
`postcodeSeq`	-	구 우편번호 일련번호 (2020년 3월 9일 이후로는 데이터가 내려가지 않습니다.)

address, addressType, roadAddress, jibunAddress, userSelectedType에 대한 추가 설명입니다. 자세히 알아보시겠습니까?

검색 결과 항목은 일반적으로 도로명 주소와 매핑된 지번 주소 각각 1개씩 나옵니다.
대부분 도로명주소가 윗줄에 나오지만, '한남동 714'와 같이 명확한 지번 주소로 검색했을 경우에는 지번 주소가 윗줄에 나오게 되지요. 또는 어떤 주소는 지번 주소만 나오는 경우도 있습니다. 매핑된 도로명 주소가 없는 경우이지요.
이때, 둘 중 어떤 주소를 선택해도 roadAddress/jibunAddress는 각각 도로명주소/지번주소가 고정되어 들어가지만, address는 둘 중 첫번째 줄에 나온 항목이 들어갑니다. address에 어떠한 타입의 주소가 들어갔는지는 addressType으로 구분할 수 있습니다. 그리고 그중 사용자가 클릭한 주소 타입은 userSelectedType로 확인할 수 있지요.

판교역로 166

13494

도로명

경기 성남시 분당구 판교역로 166 (카카오 판교 아지트)

지 번

경기 성남시 분당구 백현동 532

address : "경기 성남시 분당구 판교역로 166"
addressEnglish : "166 Pangyoyeok-ro, Bundang-gu, Seongnam-si, Gyeonggi-do, Republic of Korea"
addressType : "R"
userSelectedType : "R"
roadAddress : "경기 성남시 분당구 판교역로 166"
roadAddressEnglish : "166 Pangyoyeok-ro, Bundang-gu, Seongnam-si, Gyeonggi-do, Republic of Korea"
jibunAddress : "경기 성남시 분당구 백현동 532"
jibunAddressEnglish : "532 Baekhyeon-dong, Bundang-gu, Seongnam-si, Gyeonggi-do, Republic of Korea"
buildingName : "에이치스퀘어 엔동"

백현동 532

13494

지 번

경기 성남시 분당구 백현동 532

도로명

경기 성남시 분당구 판교역로 166 (카카오 판교 아지트)

address : "경기 성남시 분당구 백현동 532"
addressEnglish : "532 Baekhyeon-dong, Bundang-gu, Seongnam-si, Gyeonggi-do, Republic of Korea"
addressType : "J"
userSelectedType : "R"
roadAddress : "경기 성남시 분당구 판교역로 166"
roadAddressEnglish : "166 Pangyoyeok-ro, Bundang-gu, Seongnam-si, Gyeonggi-do, Republic of Korea"
jibunAddress : "경기 성남시 분당구 백현동 532"
jibunAddressEnglish : "532 Baekhyeon-dong, Bundang-gu, Seongnam-si, Gyeonggi-do, Republic of Korea"
buildingName : "에이치스퀘어 엔동"

이렇게 약간은 복잡해보이는 구조로 제작된 이유는, 도로명주소와 지번주소가 1:1 관계가 아니기 때문입니다.

판교역로14번길 16

13536

도로명

경기 성남시 분당구 판교역로14번길 16

지 번

경기 성남시 분당구 백현동 578-1

외 지번주소 1건
더보기

백현동 578-2

13536

지 번

경기 성남시 분당구 백현동 578-2

도로명

경기 성남시 분당구 판교역로14번길 16

위 예시를 보면, '백현동 578-1'과 '백현동 578-2'는 모두 '판교역로14번길 16'에 속해있습니다. 도로명 기준으로만 검색하면 '백현동 578-2'는 결과 화면에서 보이지 않을 수도 있습니다. 그러므로, 명확한 지번 주소를 검색한 경우에는 지번 주소를 윗 줄에 보여줌으로써 사용자가 쉽게 찾을 수 있도록 하고 있습니다.

autoRoadAddress, autoJibunAddress에 대한 추가 설명입니다. 자세히 알아보시겠습니까?

특정 주소에는 매핑된 주소가 여러개인 경우가 있습니다. 이때 사용자는 그 중에서 선택을 해야 하는데요, 매핑된 주소를 정확히 모르는 경우도 있을겁니다. 이런 이유로 '선택 안함'이라는 항목이 추가로 나오게 되어 있으며, 이를 클릭한 경우에는 여러개 주소 중 첫번째 매핑 주소값을 autoRoadAddress, autoJibunAddress에 내려주게 됩니다. 당연히 정확한 주소는 아니겠지만 부득이하게 도로명 주소와 지번 주소를 반드시 받아야 하는 경우에는 이 값을 이용해볼 수도 있지요.

아라동 1

63243

지 번

제주특별자치도 제주시 아라1동 1 (행정동:아라동)

도로명

아래 목록에서 정확한 도로명 주소를 선택해주세요. 잘 모르시는 경우는 '선택 안함'을 클릭하시면 됩니다. 도로명 주소 선택 안함 제주특별자치도 제주시 제주대학로 102 (제주대학교) 제주특별자치도 제주시 제주대학로 124 (기사식당) 제주특별자치도 제주시 제주대학로 64-29 (아라인빌아파트)

address : "제주특별자치도 제주시 아라일동 1"
addressEnglish : "1 Ara 1(il)-dong, Jeju-si, Jeju-do, Republic of Korea"
addressType : "J"
userSelectedType : "J"
roadAddress : ""
roadAddressEnglish : ""
jibunAddress : "제주특별자치도 제주시 아라일동 1"
jibunAddressEnglish : "1 Ara 1(il)-dong, Jeju-si, Jeju-do, Republic of Korea"
autoRoadAddress : "제주특별자치도 제주시 제주대학로 102"
autoRoadAddressEnglish : "102 Jejudaehak-ro, Jeju-si, Jeju-do, Republic of Korea"
autoJibunAddress : ""
autoJibunAddressEnglish : ""
buildingName : "제주대학교"

아란서길 164

63240

도로명

제주특별자치도 제주시 아란서길 164

지 번

아래 목록에서 정확한 지번 주소를 선택해주세요. 잘 모르시는 경우는 '선택 안함'을 클릭하시면 됩니다. 지번 주소 선택 안함 제주특별자치도 제주시 오등동 137 제주특별자치도 제주시 오등동 132 제주특별자치도 제주시 오등동 138 제주특별자치도 제주시 오등동 143

address : "제주특별자치도 제주시 아란서길 164"
addressEnglish : "164 Aranseo-gil, Jeju-si, Jeju-do, Republic of Korea"
addressType : "R"
userSelectedType : "R"
roadAddress : "제주특별자치도 제주시 아란서길 164"
roadAddressEnglish : "164 Aranseo-gil, Jeju-si, Jeju-do, Republic of Korea"
jibunAddress : ""
jibunAddressEnglish : ""
autoRoadAddress : ""
autoRoadAddressEnglish : ""
autoJibunAddress : "제주특별자치도 제주시 오등동 137"
autoJibunAddressEnglish : "137 Odeung-dong, Jeju-si, Jeju-do, Republic of Korea"
buildingName : ""

하지만, 이 값을 ('선택 안함'을 클릭한) 사용자에게 보여줄 경우 당혹스러울 수도 있으니, 가급적 노출하지 않고 시스템 내부적으로만 사용하거나, '예상 값'이라는 표시를 해주는 것이 좋을 것 같습니다. '도로명 주소와 지번 주소 모두 보여주기' 예제에서 '아라동 1'을 검색하여 '선택 안함'을 클릭했을 때의 방식을 참고해보세요.

무조건 정확한 도로명 또는 지번주소를 받아야한다면, autoMappingRoad/autoMappingJibun을 false로 하면 '선택 안함'이라는 항목이 노출되지 않고, 사용자가 반드시 매핑된 주소들 중 하나를 선택하도록 할 수도 있습니다. 하지만, 매핑된 주소를 정확히 모르는 사용자에게는 불편을 줄 수 있고, 1:N, N:N 관계의 주소에서는 메인주소가 선택이 되지 않기 때문에, 가급적 사용하지 않기를 권장합니다.

지번-도로명 주소가 1:N 매핑일때 zonecode에 대한 추가 설명입니다. 자세히 알아보시겠습니까?

지번으로 검색시, 하나의 지번에 여러개의 도로명 주소가 매핑되어 있을 수 있습니다. 이 경우, 지번 주소에 매핑된 몇몇 도로명 주소의 우편번호가 다른 경우가 있는데요. 이럴 경우 연관된 도로명 주소의 앞부분에 해당 주소의 우편번호 값을 넣어서 표시하고, 이 도로명 주소를 선택하면 선택한 주소에 해당하는 값을 내리고 있습니다.

아래 예제를 참고해 주세요.

사당동 105

06998

지 번

서울 동작구 사당동 105

도로명

아래 목록에서 정확한 도로명 주소를 선택해주세요. 잘 모르시는 경우는 '선택 안함'을 클릭하시면 됩니다. 도로명 주소 선택 안함 서울 동작구 동작대로29길 110 (신동아아파트) 06990 서울 동작구 동작대로29길 115 (사당우성아파트) 06990 서울 동작구 동작대로29길 119 (극동아파트) 06999 서울 동작구 동작대로29길 91 (사당우성아파트)

zonecode : "06998"
roadAddress : "서울 동작구 동작대로29길 110"
roadAddressEnglish : "110 Dongjak-daero 29-gil, Dongjak-gu, Seoul, Republic of Korea"

사당동 105

06998

지 번

서울 동작구 사당동 105

도로명

아래 목록에서 정확한 도로명 주소를 선택해주세요. 잘 모르시는 경우는 '선택 안함'을 클릭하시면 됩니다. 도로명 주소 선택 안함 서울 동작구 동작대로29길 110 (신동아아파트) 06990 서울 동작구 동작대로29길 115 (사당우성아파트) 06990 서울 동작구 동작대로29길 119 (극동아파트) 06999 서울 동작구 동작대로29길 91 (사당우성아파트)

zonecode : "06990"
roadAddress : "서울 동작구 동작대로29길 119"
roadAddressEnglish : "119 Dongjak-daero 29-gil, Dongjak-gu, Seoul, Republic of Korea"

"사당동 105"의 경우 지번과 도로명주소가 1:N 매핑이 되면서, 연관된 도로명 주소의 우편번호가 지번 주소와 다른 경우인데요. 보시는 것과 같이 각각의 연관주소 앞부분에 해당 주소의 우편번호를 표시하고 있습니다. 또한 노란색으로 표시된 주소를 선택할 경우 내려가는 데이터도 다르다는 것을 알 수 있습니다.

왼쪽의 예제처럼 주소 앞부분(노란색으료 표시된 주소)에 추가적인 우편번호가 없다면 상단에 표시된 대표 우편번호(06998)가 내려가게 되고, 오른쪽 예제의 경우 내려가는 데이터 중 zonecode가 선택한 주소의 데이터로 변경되어 내려가게 됩니다.

onresize

검색 결과로 인해 우편번호 서비스의 화면 크기가 변한 경우, 화면 크기 정보를 받아서 처리할 콜백 함수를 정의하는 부분입니다.
size 파라미터의 width의 경우 외부 wrapper DOM의 크기에 영향을 받기 때문에, 최초 렌더링 값으로 유지되며, height 값은 수시로 변하기 때문에 이 height 값을 이용하고자 할때 사용하시는 것을 추천드립니다.(open() 함수를 이용한 팝업모드에서는 지원하지 않습니다.)

만약 임의로 우편번호서비스의 크기를 변하게 하고 싶으실 경우엔 해당 콜백함수보다 직접 정의한 함수를 통하거나 외부 resize/orientation 이벤트를 통해 wrapper DOM의 크기를 직접 변경 하시는 것을 추천드립니다.

onresize 반환 인자
항목	값(number)	설명
`width`	500	검색 결과 화면 넓이
`height`	772	검색 결과 화면 높이

onclose

우편번호 찾기 화면을 팝업으로 띄운 후, 검색 결과를 선택하거나, 브라우저의 닫기버튼을 통해 닫았을 때 발생하는 콜백 함수를 정의하는 부분입니다. 이 중 검색결과를 선택한 경우에는 onComplete콜백함수가 완료된 후에 실행되게 됩니다.
이 함수를 정의할때 넣는 인자에는 우편번호 찾기 화면이 어떻게 닫혔는지에 대한 상태 변수가 들어가게 됩니다.
(embed() 함수를 이용한 레이어모드에서는 "검색결과를 선택하여 닫힌 경우"에만 실행됩니다.)

onclose 반환 인자
항목	값(string)	설명
`state`	FORCE_CLOSE	브라우저의 닫기 버튼을 통해 화면이 닫혔을 경우 (레이어모드에서는 발생하지 않습니다.)
`state`	COMPLETE_CLOSE	검색결과를 선택하여 화면이 닫혔을 경우 (팝업/레이어모드의 기본 동작입니다.)

onsearch

주소를 검색할 경우에 실행되는 콜백함수입니다. onresize콜백보다 먼저 실행되며, 검색어와 검색결과에 대한 간단한 정보가 콜백함수의 인자로 넘어가게 됩니다.

onsearch 반환 인자
항목	값(number)	설명
`q`	판교역로 166	검색창에 입력된 검색어
`count`	1	검색결과의 총 갯수

minWidth

우편번호 찾기 iframe(레이어모드)의 최소 너비를 지정합니다. 기본값은 300이며, 숫자만 입력가능합니다. 단위는 자동으로 'px'로 고정됩니다. 0과 기본값인 300사이로 설정가능합니다.
ex. minWidth: 200

width

우편번호 찾기 팝업 또는 iframe의 고정 너비를 지정합니다. 기본값은 500이며 iframe으로 띄울 경우 비율(%)로도 입력이 가능합니다. 최소값은 300이며 이보다 작은 값을 넣으면 무시됩니다.

height

우편번호 찾기 팝업 또는 iframe의 고정 높이를 지정합니다. 기본값은 500이며 iframe으로 띄울 경우 비율(%)로도 입력이 가능합니다. 최소값은 400이며 이보다 작은 값을 넣으면 무시됩니다.

animation

우편번호 찾기 화면에서 애니메이션 효과를 줍니다. 기본값은 false로 설정되어 있습니다.

focusInput

우편번호 찾기가 실행된 후 검색어 입력박스에 focus를 줍니다. 단, PC 플랫폼에서만 동작하며 Mobile 플랫폼은 지원하지 않습니다. (기본값 true)
추가로 focus의 경우 여러 환경적 요인으로 제대로 동작하지 않을 수도 있으니 참고 부탁드립니다.

autoMappingRoad, autoMappingJibun

각각의 기본값은 true로 설정되어 있으며, 매핑된 주소가 여러개일 경우 사용자가 '선택 안함'을 클릭할 수 있도록 합니다. 또한 연관주소를 선택하지 않고 메인주소를 선택하더라도 연관주소 중 첫번째 항목이 자동으로 데이터에 들어가게 됩니다. 데이터는 oncomplete 인자 중 autoRoadAddress 또는 autoJibunAddress 항목에 첫번째 매핑 주소가 들어갑니다.
false로 설정을 하면 '선택 안함'이라는 항목이 노출되지 않고, 사용자가 반드시 매핑된 주소들 중 하나를 선택하도록 할 수도 있습니다. 하지만, 매핑된 주소를 정확히 모르는 사용자에게는 불편을 줄 수 있고, 1:N, M:N 관계의 주소에서는 메인주소가 선택이 되지 않기 때문에, 가급적 사용하지 않기를 권장합니다.
(위 두 옵션을 같은 값으로 설정하는 방법은 각각의 옵션값을 직접 명시하거나 또는 autoMapping: true/false 로 셋팅하면 두 옵션을 같은 값으로 설정 가능합니다.)

shorthand

검색된 주소와 내려가는 데이터의 '시','도' 부분을 축약 표시합니다(한글 주소만 해당). 기본값은 true로 설정되어 있습니다.
(서울특별시 -> 서울, 광주광역시 -> 광주, 단, '세종특별자치시','제주특별자치도','강원특별자치도','전북특별자치도'는 지자체의 요청에 의해 제외)

pleaseReadGuide

검색결과가 많을시 검색바 아래의 가이드 영역을 강조시켜 주는 기능입니다. 기본값은 0(비활성)입니다.
가이드 문구는 첫화면의 가이드 문구와 동일하며, 조합방식과 예시를 설명하여 사용자에게 재검색을 유도할 수 있도록 하는 기능입니다.
입력값으로는 페이지 넘버가 들어가게 되며, 3~20까지 입력 가능합니다.
(ex. '5' 입력시 검색결과가 5페이지 이상일 경우 무조건 가이드 문구를 강조하게 됩니다. 그 이하에서는 아무런 변화 없습니다.)

pleaseReadGuideTimer

pleaseReadGuide 옵션과 같이 사용되는 옵션으로 선택사항입니다. 기본값은 1.5(1.5초간 강조)이며 입력하지 않으면 기본값으로 동작합니다.
입력값 설정 단위는 '초'단위로 설정할 수 있으며, 0.1~60까지 입력 가능합니다.
(너무 높은 값을 설정하면, 해당 시간이 지나기 전까지 검색결과 영역을 조작할 수 없으니 유의하시기 바랍니다.)

maxSuggestItems

검색어 입력시 검색바 아래에 뜨는 서제스트의 최대 검색 갯수를 조절할 수 있는 옵션입니다. 기본값은 10개이며 입력하지 않거나 1~10을 벗어나는 수를 입력시 기본값으로 셋팅됩니다.

showMoreHName

기본값은 false이며 기존보다 행정동 정보를 좀 더 많이 보여주게 하는 옵션입니다.
해당 기능을 활성화 하면 검색 결과의 행정동과 법정동이 다른 경우 무조건 표시를 하고 데이터를 내리게 됩니다. 그래서 법정동과 행정동이 같은 경우에는 표시하지 않으며, 데이터 또한 내리지 않습니다.
추가적으로, 행정동 표시의 기본 로직은 "검색어를 행정동으로 검색하고, 검색결과의 법정동과 검색어에 입력한 행정동과 다른 경우에 표시하고, 데이터를 내립니다."

hideMapBtn, hideEngBtn

기본값은 둘다 false이며 검색 결과의 "영문보기", "지도" 버튼을 가릴 수 있는 옵션입니다. 다만, 해당 기능은 자신의 주소에 익숙하지 못한 사용자들에 도움을 주는 기능으로, app에 임베딩을 해야되는 상황이거나 버튼이 눌러지면 안되는 상황일때 선택적으로 이용하시는 것을 권장합니다.
hideMapBtn의 경우 true로 셋팅을 하면 검색결과가 없을때 나오는 안내(Tip) 페이지내의 지도 이동 링크도 같이 사라집니다.

alwaysShowEngAddr

기본값은 false이며 검색 결과의 한글과 영문 주소를 동시에 볼 수 있게 해주는 기능입니다, 해당 기능 활성화시 "영문보기" 버튼은 감춰집니다.
(hideEngBtn 속성의 설정 값보다 우선시 됩니다.)

submitMode

기본값은 true이며 "form submit" 방식을 사용합니다. false로 설정 시 "location replace" 방식을 사용하게 됩니다. 우편번호 서비스로 인해 history 관련 제어가 어려우실 경우 false로 설정하여 이용하시기 바랍니다.

useBannerLink

기본값은 true이며 하단 배너에 "가이드페이지"로 이동하는 링크를 활성화 시킵니다. 링크로 인해 사용성이 저하된다고 생각하신다면 false로 설정하여 이용하시기 바랍니다.

zonecodeOnly (2020년 3월 9일 이후 삭제)

기본값은 true이며 검색 결과에서 구우편번호(6자리)를 모두 보이지 않게 합니다. 구우편번호가 더이상 업데이트가 되지 않기 때문에, 추후 완전히 제거가 되기전까지 구우편번호를 가리고 싶으신 분들만 사용하시면 됩니다.
(주소 선택시 내려가는 데이터는 변동사항이 없으며, 해당 옵션은 추후 기본값이 변경될 수 있습니다.)

theme

우편번호 찾기 화면의 색상 테마를 변경할 수 있습니다. 기본값은 null이며 자세한 사용법은 아래 "테마 변경 마법사"를 참고해 주세요.

함수

daum.Postcode의 함수는 아래와 같습니다.

open({q: '검색어', left: '팝업위치 x값', top: '팝업위치 y값', popupTitle: '팝업창의 타이틀', popupKey: '팝업창 구분값', autoClose: '자동 닫힘 유무'})

우편번호 찾기 화면을 팝업으로 띄웁니다.
특정 검색어를 넘겨 바로 실행할 수 있으며, 팝업의 위치를 지정할 수 있습니다.
또한 팝업의 이름을 설정하여, 여러개의 팝업이 뜨는 것을 방지할 수 있습니다.(IE7이하 에서는 동작하지 않습니다.)
우편번호 서비스의 기본동작은 검색결과 선택 후 자동 닫힘이나 autoClose옵션을 통해 이를 제어할 수 있습니다.

embed( element, {q: '검색어', autoClose: '자동닫힘유무'} )

우편번호 찾기 화면을 iframe으로 삽입합니다. 이때 iframe을 삽입할 element를 첫번째 매개변수로 넘겨주어야 합니다.
특정 검색어를 넘겨 바로 실행할 수도 있습니다.
우편번호 서비스의 기본동작은 검색결과 선택 후 자동 닫힘이나 autoClose옵션을 통해 이를 제어할 수 있습니다.

테마 변경 마법사

다음 우편번호 서비스 화면의 색상 테마를 변경하여 자신의 사이트 스타일에 맞게 수정 가능 합니다.
기본 테마를 제외한 3개의 테마 중에 선택하실 수도 있으며, 직접 color값 코드를 입력하시거나, 색상팔레트를 이용해 선택 하실 수도 있습니다.
(테마 변경 기능은 IE7부터 지원되며, 최신버전의 IE,Chrome,Safari,Firefox,Opera를 지원합니다.)

마법사는 데스크탑 환경의 넓은 화면에서 이용가능합니다.

테마 프리셋 설정하기

수동으로 적용하기

바탕 배경색
검색창 배경색
본문 배경색
페이지 배경색
기본 글자색
검색창 글자색
우편번호 글자색
강조 글자색
테두리

안내 사항

더 나은 검색결과를 제공하기 위해, 사용처 도메인(referrer) 정보와 검색된 결과들을 log로 남기고 있습니다. 사용자의 개인정보는 전혀 수집하지 않으므로 안심하셔도 됩니다.

Daum 우편번호 서비스는 행정안전부의 주소DB를 사용한 검색 기능을 제공하고 있으며, Daum 우편번호 서비스를 사용함으로 인하여 발생하는 문제에 대하여 kakao는 어떠한 책임도 부담하지 않습니다.

문의사항이 있으신 경우, 우편번호 서비스 Q&A에 Issue를 남겨주세요. 최대한 빠르게 답변하겠습니다.