다음 우편번호 서비스 연동: 주소 검색과 팝업·임베드 사용법

안녕하세요. 사랑받는 IT 프로덕트의 첫걸음, 똑똑한개발자입니다.

다음 우편번호 서비스는 이용자가 주소를 검색하고 선택할 수 있는 화면을 제공하는 기능입니다. 현재 카카오 우편번호 서비스 가이드에서 연동 방법을 안내하며, 회원가입과 배송지 입력 등에 활용할 수 있습니다. 오늘은 기본 코드와 팝업·임베드 방식, 좌표 변환의 차이를 알아보겠습니다.

다음 우편번호 서비스, 키 없이 쓰는 주소 검색입니다

카카오 우편번호 서비스 가이드에 따르면 키 발급이 필요 없고 사용량 제한도 없으며 상업적 용도여도 무료입니다.

이름은 다음이지만 2026년 10월 기준 postcode.map.daum.net은 postcode.map.kakao.com으로 넘어가고 스크립트도 t1.kakaocdn.net에서 받습니다. 가이드 예제는 kakao.Postcode를 쓰지만 예전 코드의 daum.Postcode도 동작합니다.

주소 검색 API 연동, 최소 코드는 이렇습니다

스크립트를 불러오고 oncomplete만 정의합니다.

사용자가 주소를 누르면 oncomplete가 실행되고 선택한 주소가 data로 들어옵니다.

다음 예시는 zonecode와 address라는 ID의 입력칸이 준비되어 있다는 전제입니다. 팝업 호출은 주소 검색 버튼의 클릭 이벤트에 연결합니다.

<script src="//t1.kakaocdn.net/mapjsapi/bundle/postcode/prod/postcode.v2.js"></script>
<script>
  new kakao.Postcode({
    oncomplete: function (data) {
      document.getElementById("zonecode").value = data.zonecode;
      document.getElementById("address").value =
        data.userSelectedType === "R" ? data.roadAddress : data.jibunAddress;
    }
  }).open();
</script>

반환 값은 필요한 것만 골라 저장합니다.

zonecode는 5자리 우편번호, roadAddress와 jibunAddress는 도로명·지번 주소, buildingName은 건물명, apartment는 공동주택 여부입니다. userSelectedType에는 사용자가 고른 유형이 R이나 J로 담기고 값이 없으면 빈 문자열이 들어옵니다.

상세주소는 별도 입력칸으로 받습니다.

동·호수는 검색 결과에 없으니 주소를 고르자마자 상세주소 칸으로 포커스를 옮겨 주면 빠뜨리기 어렵습니다.

팝업과 임베드, 모바일과 React에서 주의할 점

PC 화면에는 open() 팝업이 가장 간단합니다.

popupKey를 지정하면 버튼을 여러 번 눌러도 창이 하나만 뜹니다.

웹뷰와 모바일에서 embed() 사용하기

일부 웹뷰는 window.open을 지원하지 않아 가이드도 embed() 레이어 모드를 권합니다. iOS에서는 position:fixed로 띄우면 터치와 스크롤이 어긋날 수 있어 페이지 안에 끼워 넣어 테스트하세요.

React에서는 react-daum-postcode를 많이 씁니다.

React용 래퍼를 사용할 때는 설치한 패키지 버전의 컴포넌트와 훅 이름을 확인합니다. 공식 JavaScript API를 직접 연결할 수도 있습니다. 주소 검색 스크립트는 공식 배포 주소를 사용해 업데이트를 받도록 합니다.

다음 우편번호 서비스와 도로명주소 검색 API 비교

행정안전부 주소기반산업지원서비스(business.juso.go.kr)에도 도로명주소 검색 API가 있습니다. 검색 화면은 직접 그려야 하지만 서버에서 호출할 수 있습니다.

승인키는 개발용과 운영용으로 나뉩니다. 개발용은 본인인증 없이 받는 대신 7·30·90일 중 사용기간을 고르며 만료되면 다시 발급받아야 합니다. 요청할 때는 addrLinkApi.do에 confmKey와 keyword를 넘기면 됩니다.

좌표가 필요하면 카카오맵 주소-좌표 변환으로 잇습니다

다음 우편번호 서비스는 위도와 경도를 주지 않습니다. 지도에 찍으려면 카카오맵 API 사용법 글에서 다룬 Geocoder에 data.address를 넘기면 되는데 이때는 카카오 디벨로퍼스 앱 키가 있어야 합니다.

세부 항목과 최신 적용 조건은 카카오 우편번호 서비스 가이드를 참고해 보세요.

주소를 입력하는 작은 과정도 편안하게

서비스에 필요한 연동 기능을 하나씩 붙이다 보면 화면뿐 아니라 데이터와 운영 방식도 함께 살펴보게 됩니다. 지금 서비스에 필요한 범위부터 차근차근 정리해볼 수 있습니다.

똑똑한개발자는 UX/UI 디자인과 웹·앱 개발을 함께 진행합니다. 사용자가 이용하는 화면과 운영에 필요한 기능을 연결해 서비스를 만들어가는 과정을 돕습니다.

서비스에 필요한 연동 기능을 준비하면서 궁금한 점이 있다면 아래 똑똑한개발자 링크로 편하게 이야기 남겨주세요. 함께 살펴보겠습니다. 감사합니다. :)