주소 검색 API, 도로명주소 · 우편번호 서비스 비교표
주소 검색 API를 고를 때 보는 도로명주소 API와 우편번호 서비스의 신청 · 비용 · 영문 주소 · 좌표 비교표, 개발 키에서 운영 키까지 신청 4단계, 택배 연동을 생각한 주소 저장 항목표, 해외 주소를 받는 칸 구성을 정리했습니다.

주소 검색 API는 행정안전부 도로명주소 API와 키 없이 쓰는 무료 우편번호 서비스 가운데 고르면 됩니다. 주문서에 주소 찾기 버튼 하나만 필요하면 우편번호 서비스가 빠르고, 서버에서 주소를 검색하거나 좌표를 함께 받아야 하면 도로명주소 API의 승인키를 받습니다. 배송이 있다면 어느 쪽을 쓰든 우편번호 · 도로명주소 · 지번주소 · 상세주소를 나눠 모두 저장해야 택배 연동에서 주소 오류가 줄어듭니다.
주소 검색 API는 어떤 것이 있나요
고를 수 있는 것은 크게 두 가지입니다. 하나는 행정안전부가 주소기반산업지원서비스(도로명주소 개발자센터)에서 승인키를 받아 쓰게 하는 도로명주소 API이고, 다른 하나는 포털이 공개한 자바스크립트 우편번호 서비스입니다(예: 카카오 우편번호 서비스). 아래는 두 곳의 공식 안내를 나란히 놓은 표입니다.
| 항목 | 도로명주소 API | 우편번호 서비스 |
|---|---|---|
| 신청 | 시스템마다 승인키 신청(1 시스템 1 승인키) | 신청 · 키 없음 |
| 비용 | 공공데이터포털 목록에 무료로 표시 | 기업용 · 상업 용도 상관없이 무료 |
| 방식 | 팝업 API(검색 창 제공), 검색 API(서버에서 호출해 xml · json으로 받음) | 팝업 창 또는 페이지에 끼워 넣는 화면 |
| 영문 주소 | 검색 결과에 영문 도로명주소 포함, 영문주소 API 따로 있음 | 결과에 영문 도로명 · 지번 주소 포함 |
| 좌표 | 좌표제공 API를 따로 신청 | 없음, 지도 API 키를 따로 받아 변환 |
| 사용량 | 제공 기관 정책에 따름 | 사용량 제한 없음 |
| 지킬 것 | 개발 승인키는 정한 기간이 지나면 만료 | 화면 아래 로고를 가리거나 스크립트를 고치면 사용에 제약 |
고르는 기준은 주소를 어디서 쓰느냐입니다. 고객이 화면에서 고르기만 하면 되는 주문서 · 회원가입은 우편번호 서비스로 충분합니다. 엑셀로 받은 주소 목록을 서버에서 한꺼번에 검색해 맞추거나, 매장 찾기처럼 좌표가 필요하거나, 인터넷이 아닌 내부망에서 써야 하면 도로명주소 API가 맞습니다. 우편번호 서비스 안내는 내부망(인트라넷) 환경을 공식 지원하지 않는다고 적고 있습니다.
도로명주소 API는 어떤 순서로 신청하나요
개발자센터의 주소정보 API 연계 메뉴에서 신청합니다. 처음에는 개발 용도로 받아 붙여 보고, 오픈 전에 운영 용도로 다시 받습니다.
| 단계 | 할 일 | 확인할 것 |
|---|---|---|
| 1. API 고르기 | API 목록에서 종류(도로명주소 · 영문주소 · 좌표제공 · 상세주소 · 지도제공)와 유형(팝업 · 검색)을 고릅니다 | 상세주소 팝업은 도로명주소 · 좌표제공 API에서 지원 |
| 2. 신청서 쓰기 | 기관 유형, 업체명, 시스템명, 사이트 주소(URL) 또는 IP, 서비스망, 서비스 용도, 활용 목적을 적습니다 | 개발 용도는 본인인증 없이 발급되고 기간을 7 · 30 · 90일 가운데 고름 |
| 3. 개발 키로 붙이기 | 검색 API는 승인키 · 페이지 번호 · 페이지당 개수 · 검색어를 보내고 결과를 받습니다 | 오류 코드 표대로 검색어 규칙을 화면에 안내 |
| 4. 운영 키로 바꾸기 | 서비스 용도를 운영으로 실제 사이트 주소에 맞춰 다시 신청하고 키를 바꿉니다 | 여러 시스템이면 IP · URL 목록을 첨부해 한꺼번에 발급 |
3단계에서 화면에 미리 알려 줄 검색어 규칙은 오류 코드 표에 있습니다. 시도 이름만으로는 검색되지 않고, 한 글자나 숫자만으로도 검색되지 않으며, 한글 40자 · 영문과 숫자 80자를 넘는 검색어와 결과가 9천 건을 넘는 검색은 막힙니다. 개발 승인키 기간이 끝나면 만료 오류가 나므로 오픈 날짜보다 먼저 운영 키로 바꿔 두세요.
무엇을 저장해야 배송 오류가 줄어드나요
주소를 한 줄 글자로만 저장하면 택배 송장 규격에 맞게 다시 나누기 어렵습니다. 주소 검색 API가 돌려주는 값을 아래처럼 나눠 저장하세요. 표의 영문 이름은 도로명주소 API / 우편번호 서비스 순서입니다.
| 저장 항목 | 결과 값 이름 | 쓰는 곳 |
|---|---|---|
| 우편번호(5자리) | zipNo / zonecode | 송장, 지역별 배송비 규칙 |
| 도로명주소 | roadAddrPart1 / roadAddress | 송장 기본 주소 |
| 참고항목(법정동 · 건물명) | roadAddrPart2 / bname · buildingName | 배송 기사가 건물을 찾을 때 |
| 지번주소 | jibunAddr / jibunAddress | 지번으로 적힌 옛 자료 · 거래처 주소와 대조 |
| 상세주소(동 · 층 · 호) | 고객 입력 | 송장 둘째 줄 |
| 건물관리번호 | bdMgtSn / buildingCode | 같은 건물 주문 묶기, 주소 변경 추적 |
| 영문 주소 | engAddr / roadAddressEnglish | 해외 배송 · 영문 서류 |
우편번호 서비스는 지번 하나에 도로명주소가 여러 개 걸리는 경우 도로명주소 칸이 빈 값으로 올 수 있다고 안내하고, 그때를 위해 자동으로 짝지은 주소 값(autoRoadAddress · autoJibunAddress)을 함께 줍니다. 빈 값을 그대로 저장하지 않도록 이 값으로 채우는 처리를 넣으세요. 주문서 전체 구성은 자체몰 만들기, 결제 · 배송부터 정하는 순서에서 함께 볼 수 있습니다.
해외 주소는 어떻게 받나요
두 서비스 모두 국내 주소만 검색합니다. 해외 주소는 나라마다 적는 순서가 달라서 검색 대신 칸을 나눠 직접 입력받습니다. 국가를 먼저 고르게 하고 받는 사람 이름 · 주소 1 · 주소 2 · 도시 · 주(州) 또는 도 · 우편번호 · 전화번호로 나누면 대부분 나라의 주소를 담을 수 있습니다. 국내 주소를 영문 서류에 적어야 할 때는 검색 결과의 영문 주소 값을 그대로 쓰세요. 우편번호 서비스 안내는 사용자가 고른 값을 쓸 때 영문 주소가 정확히 짝지어지지 않을 수 있다고 적고 있어, 영문 주소가 중요한 화면이면 시험 주소 몇 개로 확인해 두는 것이 좋습니다.
문의 폼처럼 배송이 없는 화면은 주소를 받지 않는 편이 입력 부담을 줄입니다. 꼭 필요한 칸만 남기는 기준은 홈페이지 문의 폼, 입력 항목 10개와 스팸 · 알림 설정에 있습니다.
자주 묻는 질문
우편번호는 숫자로 저장해도 되나요?
글자(문자열)로 저장하세요. 지금 우편번호는 5자리 국가기초구역번호이고 0으로 시작하는 번호가 있어, 숫자로 저장하면 앞자리 0이 사라져 송장에 네 자리로 찍힐 수 있습니다. 두 서비스 모두 결과를 글자로 돌려줍니다.
앱 안 웹 화면에서도 우편번호 서비스를 쓸 수 있나요?
쓸 수 있지만 띄우는 방식을 고릅니다. 우편번호 서비스 안내는 몇몇 웹뷰 기반 브라우저가 새 창 열기를 지원하지 않아, 웹뷰에 적용할 때는 페이지 안에 끼워 넣는 레이어 방식을 권합니다. 업체가 자체 제작한 브라우저 · 웹뷰에서는 정상 동작하지 않을 수 있다고 적고 있으니 적용 전에 기기별로 확인하세요.
개발 승인키 기간이 끝나면 어떻게 되나요?
검색 API가 개발승인키 기간 만료 오류(E0014)를 돌려주고 검색이 멈춥니다. 개발 중이라면 개발 키를 다시 받고, 실제 서비스라면 운영 용도로 신청한 키로 바꿉니다. 오픈 체크리스트에 운영 키 교체를 한 항목으로 넣어 두면 놓치지 않습니다.
주소 검색 기능을 외부에 맡기면 비용은 무엇으로 정해지나요?
주소를 받는 화면 수, 서버에서 검색 · 검증하는지 여부, 좌표나 영문 주소를 함께 쓰는지, 이미 쌓인 주소 데이터를 새 항목으로 나눠 옮기는 작업이 있는지로 정해집니다. 택배 송장 연동까지 이어지면 송장 규격에 맞추는 일이 더해집니다. 주문서 · 주소 입력 기능 개발을 맡길 때 앞의 저장 항목표를 함께 넘기면 범위가 분명해집니다.
오늘 할 일
지금 주문서가 저장하는 주소 항목을 데이터베이스나 주문 엑셀에서 열어 위 저장 항목표와 하나씩 맞춰 보세요.



