일단 어떤 방식으로 검색되는지 여기에서 먼저 확인해보세요.
도로명, 건물명, 지번 등을 이용해서 검색할 수 있습니다.

기본 사용법

!
  꼭 읽어주세요!!

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함수의 정의 부분은 이용하시는 각 사이트의 상황에 맞게 적절히 수정하여 적용하시기 바랍니다.

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

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

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


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

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



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

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



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

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



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

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


속성

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

oncomplete

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

버튼을 클릭해서 실제 데이터를 확인해보세요. (모든 데이터는 문자열이며, 값이 없을 경우 공백입니다.)
    oncomplete 반환 인자
    항목 설명
    zonecode 13529 국가기초구역번호. 2015년 8월 1일부터 시행될 새 우편번호.
    address 경기 성남시 분당구 판교역로 166 기본 주소
    (검색 결과에서 첫줄에 나오는 주소, 검색어의 타입(지번/도로명)에 따라 달라집니다.)
    addressEnglish 166, Pangyoyeok-ro, Bundang-gu, Seongnam-si, Gyeonggi-do, 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, Korea 영문 도로명 주소
    jibunAddress 경기 성남시 분당구 백현동 532 지번 주소
    (도로명:지번 주소가 1:N인 경우에는 데이터가 공백으로 들어갈 수 있습니다.
    - 아래 autoJibunAddress의 자세한 설명 참고)
    jibunAddressEnglish 532, Baekhyeon-dong, Bundang-gu, Seongnam-si, Gyeonggi-do, Korea 영문 지번 주소
    autoRoadAddress 경기 성남시 분당구 판교역로 166 '지번주소'에 매핑된 '도로명주소'가 여러개인 경우, 사용자가 '선택안함' 또는 '지번주소'를 클릭했을 때 연관된 도로명 주소 중 임의로 첫번째 매핑 주소를 넣어서 반환합니다.
    (autoMapping을 false로 설정한 경우에는 값이 채워지지 않습니다.)
    autoRoadAddressEnglish 166, Pangyoyeok-ro, Bundang-gu, Seongnam-si, Gyeonggi-do, Korea autoRoadAddress의 영문 도로명 주소
    autoJibunAddress 경기 성남시 분당구 백현동 532 '도로명주소'에 매핑된 '지번주소'가 여러개인 경우, 사용자가 '선택안함' 또는 '도로명주소'를 클릭했을 때 연관된 지번 주소 중 임의로 첫번째 매핑 주소를 넣어서 반환합니다.
    (autoMapping을 false로 설정한 경우에는 값이 채워지지 않습니다.)
    autoJibunAddressEnglish 532, Baekhyeon-dong, Bundang-gu, Seongnam-si, Gyeonggi-do, 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에 대한 추가 설명입니다. 자세히 알아보시겠습니까?

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

    지번-도로명 주소가 1:N 매핑일때 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 브라우저의 닫기 버튼을 통해 화면이 닫혔을 경우
    (레이어모드에서는 발생하지 않습니다.)
    COMPLETE_CLOSE 검색결과를 선택하여 화면이 닫혔을 경우
    (팝업/레이어모드의 기본 동작입니다.)

    onsearch

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

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

    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를 지원합니다.)

    마법사는 데스크탑 환경의 넓은 화면에서 이용가능합니다.
    수동으로 적용하기
    • 바탕 배경색
    • 검색창 배경색
    • 본문 배경색
    • 페이지 배경색
    • 기본 글자색
    • 검색창 글자색
    • 우편번호 글자색
    • 강조 글자색
    • 테두리

    마법사를 통해 색상 선택이 완료되면, 아래의 themeObj변수 부분의 코드를 복사하여 사용하시면 됩니다.

    안내 사항

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

    업데이트에 대한 소식을 받으시려면 카카오톡 친구찾기에서 ID검색으로 @다음우편번호서비스를 추가해주세요. (http://goto.kakao.com/hj697xoo를 클릭하시면 바로 친구추가를 하실 수 있습니다.)

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

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