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

기본 사용법

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

또는 스크립트를 동적으로 로딩해야 하는 경우, 아래와 같이 이용하실 수 있습니다.

예제

!
  꼭 읽어주세요!!

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

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

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


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

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


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

모바일웹에서는 팝업을 띄우는게 부담스러울 수도 있으니, 아래 코드와 같이 특정 element에 크기를 지정하여 iframe으로 끼워넣는 방식을 이용할 수도 있습니다. 아래 '우편번호 찾기' 버튼을 클릭해서 바로 확인해보세요.
(현재 iOS 8.x ~ 9.x, Safari, webview 브라우저에서 input필드를 터치하면(키보드 또는 액션시트가 올라올때) position:fixed된 엘리먼트가 페이지의 최상단으로 올라가는 버그가 있습니다. 해당 샘플 코드를 이용하시는 분들께서는 자신의 페이지에 맞게 위치값을 조정하여 사용하시길 권장합니다.)
예제 코드보기


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

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


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

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


속성

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

oncomplete

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

버튼을 클릭해서 실제 데이터를 확인해보세요. (모든 데이터는 문자열이며, 값이 없을 경우 공백입니다.)
    oncomplete 반환 인자
    항목 설명
    zonecode 13494 국가기초구역번호. 2015년 8월 1일부터 시행될 새 우편번호.
    address 경기 성남시 분당구 판교역로 235 기본 주소
    (검색 결과에서 첫줄에 나오는 주소, 검색어의 타입(지번/도로명)에 따라 달라집니다.)
    addressEnglish 235 Pangyoyeok-ro, Bundang-gu, Seongnam-si, Gyeonggi-do, korea 기본 영문 주소
    addressType R/J 검색된 기본 주소 타입: R(도로명), J(지번)
    userSelectedType R/J 검색 결과에서 사용자가 선택한 주소의 타입
    userLanguageType K/E 검색 결과에서 사용자가 선택한 주소의 언어 타입: K(한글주소), E(영문주소)
    roadAddress 경기 성남시 분당구 판교역로 235 도로명 주소
    (지번:도로명 주소가 1:N인 경우에는 데이터가 공백으로 들어갈 수 있습니다.
    - 아래 autoRoadAddress의 자세한 설명 참고)
    roadAddressEnglish 235, Pangyoyeok-ro, Bundang-gu, Seongnam-si, Gyeonggi-do, Korea 영문 도로명 주소
    jibunAddress 경기 성남시 분당구 삼평동 681 지번 주소
    (도로명:지번 주소가 1:N인 경우에는 데이터가 공백으로 들어갈 수 있습니다.
    - 아래 autoJibunAddress의 자세한 설명 참고)
    jibunAddressEnglish 681, Sampyeong-dong, Bundang-gu, Seongnam-si, Gyeonggi-do, Korea 영문 지번 주소
    autoRoadAddress 경기 성남시 분당구 판교역로 235 '지번주소'에 매핑된 '도로명주소'가 여러개인 경우, 사용자가 '선택안함' 또는 '지번주소'를 클릭했을 때 연관된 도로명 주소 중 임의로 첫번째 매핑 주소를 넣어서 반환합니다.
    (autoMapping을 false로 설정한 경우에는 값이 채워지지 않습니다.)
    autoRoadAddressEnglish 235, Pangyoyeok-ro, Bundang-gu, Seongnam-si, Gyeonggi-do, Korea autoRoadAddress의 영문 도로명 주소
    autoJibunAddress 경기 성남시 분당구 삼평동 681 '도로명주소'에 매핑된 '지번주소'가 여러개인 경우, 사용자가 '선택안함' 또는 '도로명주소'를 클릭했을 때 연관된 지번 주소 중 임의로 첫번째 매핑 주소를 넣어서 반환합니다.
    (autoMapping을 false로 설정한 경우에는 값이 채워지지 않습니다.)
    autoJibunAddressEnglish 681, Sampyeong-dong, Bundang-gu, Seongnam-si, Gyeonggi-do, Korea autoJibunAddress의 영문 지번 주소
    buildingCode 4113510900106810000000001 건물관리번호
    buildingName 에이치스퀘어 엔동 건물명
    apartment N 공동주택 여부(Y/N)
    (아파트,연립주택,다세대주택 등)
    sido 경기 도/시 이름
    sigungu 성남시 분당구 시/군/구 이름
    sigunguCode 41135 시/군/구 코드
    (5자리 구성된 시/군/구 코드입니다.)
    roadnameCode 3179025 도로명 코드
    (7자리로 구성된 도로명 코드입니다. 도로명주소로 검색시에만 내려가며 추후 7자리 이상으로 늘어날 수 있습니다.)
    bcode 4113510900 법정동/법정리 코드
    bname 삼평동 법정동/법정리 이름
    hname - 행정동 이름
    (선택된 도로명/지번주소의 법정동과 행정동이 다를 경우에만 내려갑니다.)
    query 판교역로 235 사용자가 입력한 검색어
    postcode 463-400 구 우편번호 (2015년 8월 1일 이후에는 업데이트가 되지 않습니다.)
    postcode1 463 구 우편번호 앞 3자리 (2015년 8월 1일 이후에는 업데이트가 되지 않습니다.)
    postcode2 400 구 우편번호 뒤 3자리 (2015년 8월 1일 이후에는 업데이트가 되지 않습니다.)
    postcodeSeq 001 구 우편번호 일련번호 (2015년 8월 1일 이후에는 업데이트가 되지 않습니다.)

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

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

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

    onresize

    검색 결과로 인해 우편번호 찾기 화면 크기가 변한 경우, 화면 크기 정보를 받아서 처리할 콜백 함수를 정의하는 부분입니다. 우편번호 찾기를 iframe으로 넣은 경우에 이 크기 정보값을 이용해서 iframe을 감싸고 있는 element의 크기(주로 높이값)를 조절하고자 할때 사용하면 됩니다.
    이 함수를 정의할때 넣는 인자에는 우편번호 찾기 화면 크기 정보가 객체로 들어가게 됩니다.
    (open() 함수를 이용한 팝업모드에서는 지원하지 않습니다.)

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

    onclose

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

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

    width

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

    height

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

    animation

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

    shorthand

    검색된 주소와 내려가는 데이터의 '시','도' 부분을 축약 표시합니다(한글 주소만 해당). 기본값은 true로 설정되어 있습니다.
    (서울특별시 -> 서울, 광주광역시 -> 광주, 전라북도 -> 전북)

    pleaseReadGuide

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

    pleaseReadGuideTimer

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

    autoMapping

    기본값은 true로 설정되어 있으며, 매핑된 주소가 여러개일 경우 사용자가 '선택 안함'을 클릭할 수 있도록 합니다. 이때 oncomplete 인자 중 autoRoadAddress 또는 autoJibunAddress 항목에 첫번째 매핑 주소가 들어갑니다.
    false로 설정하는 경우, 사용자는 매핑된 주소 목록 중 무조건 1개를 선택해야 하므로, 사이트 관리자 입장에서는 정확한 매핑 주소를 알 수 있게 되지만, 사용자가 매핑된 주소를 정확히 알지 못하는 경우에는 불편함을 줄 수 있습니다. 가급적 사용하지 않기를 권장합니다.

    theme

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

    함수

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

    open({q: '검색어', left: '팝업위치 x값', top: '팝업위치 y값', popupName: '팝업이름', autoClose: '자동닫힘유무'})

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

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

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

    테마 변경 마법사

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

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

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

    이전 버전에서 옮기기

    이전 버전의 우편번호 서비스를 사용하고 계시다면, 새로운 버전으로 변경해주세요.
    신규 우편번호 서비스는 새우편번호가 적용된 주소 Data를 매일 업데이트하고 있어 정확한 주소 검색이 가능합니다.

    새로운 버전으로 변경하는 방법

    js 파일명만 변경하면 신규 버전을 이용하실 수 있습니다.

    단, 클릭된 주소값을 받아오는 부분에서 우편번호, 주소값을 담은 변수들을 적절히 변경해주어야 합니다.
    변경된 항목은 아래와 같습니다. 기본 예제 코드를 함께 보시면 도움이 되실겁니다.

    변경된 사항

    oncomplete 콜백 함수의 인자로 전달되는 항목 중 변경된 사항은 아래 표와 같습니다.

    이전 버전과 신규 버전의 차이점
    항목 이전 버전 신규 버전 설명
    zonecode 13494 2015년 8월 1일부터 시행되고 있는 새우편번호
    postcode 463-400 463-400 2015년 8월 1일 이후에는 업데이트가 되지 않습니다.
    postcode1 463 463 2015년 8월 1일 이후에는 업데이트가 되지 않습니다.
    postcode2 400 400 2015년 8월 1일 이후에는 업데이트가 되지 않습니다.
    address 경기도 성남시 분당구 판교역로 235 (삼평동 681,에이치스퀘어 엔동) 경기 성남시 분당구 판교역로 235 도로명 주소인 경우 매핑된 지번 주소와 건물명은 address 값에 포함되지 않습니다.
    addressEnglish 235 Pangyoyeok-ro, Bundang-gu, Seongnam-si, Gyeonggi-do, korea 235 Pangyoyeok-ro, Bundang-gu, Seongnam-si, Gyeonggi-do, korea 동일 제공
    address1 경기도 성남시 분당구 판교역로 235 제공 안함
    address2 (삼평동 681,에이치스퀘어 엔동) 제공 안함
    relatedAddress 경기도 성남시 분당구 삼평동 681 제공 안함
    addressType R/N R/J address에 들어간 주소 타입을 의미합니다.
    기존에는 지번주소를 'N'으로 표기하였으나, 변수명과의 연관 관계를 이해하기 쉽도록 'J'로 변경하였습니다.
    userSelectedType R/J 검색 결과에서 사용자가 선택한 주소의 타입
    userLanguageType K/E 영문주소/한글주소 선택 유무
    roadAddress 경기 성남시 분당구 판교역로 235 도로명 주소
    roadAddressEnglish 235, Pangyoyeok-ro, Bundang-gu, Seongnam-si, Gyeonggi-do, Korea 영문 도로명 주소
    jibunAddress 경기 성남시 분당구 삼평동 681 지번 주소
    jibunAddressEnglish 681, Sampyeong-dong, Bundang-gu, Seongnam-si, Gyeonggi-do, Korea 영문 지번 주소
    autoRoadAddress 경기 성남시 분당구 판교역로 235 매핑된 도로명 주소가 여러개인 경우, 사용자가 '선택안함'을 클릭했을 때 임의로 첫번째 매핑 주소를 넣어서 반환합니다.
    (autoMapping을 false로 설정한 경우에는 값이 채워지지 않습니다.)
    autoRoadAddressEnglish 235, Pangyoyeok-ro, Bundang-gu, Seongnam-si, Gyeonggi-do, Korea autoRoadAddress의 영문 도로명 주소
    autoJibunAddress 경기 성남시 분당구 삼평동 681 매핑된 지번 주소가 여러개인 경우, 사용자가 '선택안함'을 클릭했을 때 임의로 첫번째 매핑 주소를 넣어서 반환합니다.
    (autoMapping을 false로 설정한 경우에는 값이 채워지지 않습니다.)
    autoJibunAddressEnglish 681, Sampyeong-dong, Bundang-gu, Seongnam-si, Gyeonggi-do, Korea autoJibunAddress의 영문 지번 주소
    buildingCode 4113510900106810000000001 건물관리번호
    buildingName 에이치스퀘어 엔동 건물명
    apartment N 공동주택 여부(Y/N)
    sido 경기 도/시 이름
    sigungu 성남시 분당구 시/군/구 이름
    sigunguCode 41135 시/군/구 코드
    roadnameCode 3179025 도로명 코드
    bcode 4113510900 법정동/법정리 코드
    bname 삼평동 법정동/법정리 이름
    hname - 행정동 이름
    query 판교역로 235 사용자가 입력한 검색어
    postcodeSeq 001 2015년 8월 1일 이후에는 업데이트가 되지 않습니다.

    onresize 콜백 함수는 그대로 제공합니다.

    onclose 콜백 함수가 추가되었습니다. 생성자 속성 중간 부분 참고


    생성자 속성도 추가되었습니다. 기본값이 있기 때문에 반드시 필요한 경우에만 조절하시면 됩니다.

    추가 속성
    항목 이전 버전 신규 버전 설명
    animation false(default)/true 애니메이션 효과를 줄지의 여부
    autoMapping true(default)/false 매핑된 주소가 여러개인 경우 '선택 안함' 항목을 노출하고 그 항목이 선택된 경우, 첫번째 매핑주소를 반환할지의 여부.
    (기본값으로 두고 조절하지 않는 것을 권장함)
    shorthand true(default)/false 검색된 주소와, 내려가는 데이터의 '시'/'도' 부분의 축약표시 여부
    pleaseReadGuide 0(default)/3~20 검색결과가 입력한 페이지 값 이상일때, 가이드 문구 강조 기능을 활성화 시킵니다.
    theme null(default)/object 우편번호 서비스의 색상 테마를 변경합니다. 자세한 사용법은 "테마 변경 마법사"를 참고해 주세요.

    안내 사항

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

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

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

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