주소기반산업지원서비스 API
주소기반산업지원서비스를 통해 API 승인키를 발급받고 활용하는 방법은 다음과 같습니다. 크게 승인키 발급 과정과 API 활용 방식(팝업 API vs 검색 API)으로 나뉩니다.
1. 승인키(API Key) 발급 방법
사이트 접속 및 로그인
- 주소기반산업지원서비스(business.juso.go.kr) 또는 도로명주소 안내시스템(juso.go.kr) 내 개발자센터에 접속합니다.
- 원활한 서비스 이용을 위해 회원가입 및 로그인을 진행합니다.
API 신청 메뉴 이동
- 상단 메뉴에서 [주소정보 API 연계]를 선택한 후 [API 목록]으로 이동하거나 메인 화면의 [API 서비스 신청하기]를 클릭합니다.
API 종류 선택
- 서비스에 적용할 API 방식을 선택합니다. (도로명주소 팝업 API, 검색 API, 영문주소 API 등)
시스템 정보 입력 및 발급
- 시스템명, 사용 목적, 서비스 URL(또는 IP) 등 필수 정보를 입력합니다.
- 정보 입력 완료 후 신청하기를 누르면 즉시 승인키(confmKey)가 발급됩니다.
참고: 개발 초기 단계라면 본인 인증이나 URL 입력 없이 사용 기간이 제한된 개발자용 테스트 승인키(7일/30일/90일)를 발급받아 바로 테스트해 볼 수 있습니다.
2. 승인키 활용 방법
발급받은 승인키는 선택한 API 유형에 따라 활용 방식이 다릅니다. 가장 대표적으로 많이 쓰이는 두 가지 방식의 활용법은 다음과 같습니다.
A. 팝업 API (UI 제공형)
행정안전부에서 미리 만들어둔 주소 검색 창(팝업)을 띄워서 사용자가 주소를 검색 및 선택하면, 그 결괏값을 내 시스템으로 가져오는 방식입니다. UI 개발 부담이 없어 구축이 빠릅니다.
적용 방법:
- 개발자센터에서 제공하는 개발 언어별(JSP, PHP, ASP) 가이드 및 샘플 소스를 다운로드합니다.
- 다운로드한 소스 코드 중 팝업창을 호출하는 기본 설정 파일(예: jusoPopup.jsp, jusoPopup.php 등)을 엽니다.
- 코드 내에 있는 confmKey 변수 값에 발급받은 승인키를 붙여넣기 합니다.
- 주소 검색 완료 후 결과를 반환받을 내 서버의 페이지 경로를 returnUrl 변수에 설정합니다.
- 사용자가 팝업에서 주소를 검색하여 선택하면, 설정한 returnUrl로 전체 도로명주소, 지번, 우편번호, 상세주소 등의 데이터가 전달됩니다.
B. 검색 API (데이터 연동형)
개발자가 직접 주소 검색 화면을 디자인하고, 행안부 서버에는 검색 요청만 보내 결괏값(XML 또는 JSON)을 데이터로만 받아 화면에 그려주는 방식입니다.
적용 방법:
- 클라이언트(웹/앱) 또는 서버단에서 행안부 API 서버 URL로 HTTP 요청(GET/POST)을 보냅니다.
- 요청 URL: https://business.juso.go.kr/addrlink/addrLinkApi.do
- API 호출 시 아래의 필수 파라미터를 함께 전달해야 합니다.
- confmKey: 발급받은 검색 API 승인키
- keyword: 사용자가 입력한 주소 검색어 (예: "세종대로 209")
- currentPage: 현재 페이지 번호
- countPerPage: 페이지당 출력할 결과 수
- resultType: 반환 형식 (json 또는 xml)
행안부 서버로부터 JSON이나 XML 형식으로 검색 결과 데이터가 응답되면, 이를 파싱(Parsing)하여 자체적으로 만든 UI 리스트에 출력하여 사용합니다.
💡 유의사항
API 키 교차 사용 불가: 팝업 API용으로 발급받은 승인키를 검색 API에 사용하거나, 그 반대로 사용할 경우 "승인키가 일치하지 않습니다"라는 오류 메시지가 발생합니다. 반드시 신청한 유형에 맞는 방식으로 사용해야 합니다.
방화벽 설정: 사내망 등 폐쇄적인 네트워크 환경에서 개발하는 경우 행안부 API 서버 IP 및 포트(80, 443)에 대해 아웃바운드 방화벽 오픈이 필요할 수 있습니다.
