====== 도로명 주소 연계 ======

===== 개요 =====
도로명주소 안내시스템(http://www.juso.go.kr)에서 제공하는 Open API 기반의 주소정보연계 서비스를 이용하여 도로명 주소를 조회하는 기능을 제공한다.

===== 설명 =====
- 도로명주소 안내시스템에서 제공하는 Open API 기반의 주소정보연계 서비스를 이용하며, AJAX를 활용한 Controller 호출 방식과 JSON을 활용한 웹 페이지 호출 방식을 제공한다.\\
- 도로명주소 DB 구축없이 다양한 시스템 환경에서 실시간으로 주소 검색 할 수 있도록 주소정보연계 API 팝업 화면으로 제공한다.\\

== 관련소스 ==

^유형^대상소스명^비고^
|Controller|egovframework.com.sym.adr.web.EgovAdressCntcController.java|도로명주소 안내시스템의 Open API를 호출하는 역할을 하는 컨트롤러 클래스|
|JSP|/WEB-INF/jsp/egovframework/cmm/sym/cal/EgovNormalCalPopup.jsp|일반달력 팝업을 위한 JSP 페이지|
|JSP|WEB-INF/jsp/egovframework/com/sym/adr/EgovAdressCntc.jsp|주소정보연계 서비스를 통해 전달받은 주소정보를 출력하기 위한 JSP 페이지|

== 관련테이블 ==
없음 (Open API를 통해 데이터를 조회하므로 관련테이블이 없음)

===== 환경설정 =====
관련 설정 없음

==== 주소정보 연계 신청 ====
도로명주소 안내시스템에서 제공하는 주소정보연계 OpenAPI를 사용하기 위해서는 등록 작업이 필요하다. \\
등록을 위한 주소와 메뉴는 아래와 같다. \\

http://www.juso.go.kr -> 개발자센터 -> OpenAPI 연계 등록/확인 \\
등록이 완료되면 승인키를 받게 되며, 승인키는 OpenAPI 호출시 인자로 필요한 값이다. \\
http://www.juso.go.kr/addrlink/devAddrLinkRequestSample.do → 도로명주소 API 팝업 연계가이드 다운로드, 예제소스 다운로드 등\\
http://www.juso.go.kr/addrlink/addressBuildDev.do → 주소DB 및 가이드 다운로드 등

===== 사용방법(1.검색 API =====

요소기술 -> 2180. 주소정보연계 메뉴를 선택하면 도로명주소연계를 확인할 수 있다.

{{:egovframework:com:v3:sym:adresscntcinit_3.5.jpg|}}

== 관련입력 ==

^이름^필드명^설명^
|현재 페이지|currentPage|출력한 주소 정보의 현재 페이지|
|페이지 사이즈|countPerPage|한 페이지에 출력한 주소 정보 수|
|검색어|keyword|주소 정보 조회를 위한 검색어|
|승인키|confmKey|주소정보연계 Open API 호출을 위한 승인키 (서버 IP별로 신청해야 하는 값)|

== AJAX를 활용한 Controller 호출 방식 ==
도로명주소연계 페이지의 "주소가져오기_Controller" 버튼을 클릭하면 Controller 방식으로 주소정보를 연계한다. \\
이 때 연계 신청을 통해 받은 승인키를 포함해야 한다. (공통 컴포넌트 내에 제공되는 승인키는 임의의 값으로 정상동작하지 않으며 프로젝트별로 등록을 통해 배포받아야 하는 값이다.)\\
만약 아직 승인을 받지 않은 상태에서 연계가 정상적으로 동작하는지 미리 확인하고자 한다면 "주소가져오기(테스트)_Controller" 버튼을 활용할 수 있다. 이 경우 검색어에 해당하는 데이터가 아닌 임의의 데이터를 전송받는다. \\

주소정보연계 Controller의 관련 메소드는 아래와 같다.

<code java>
@Controller
public class EgovAdressCntcController {

    @RequestMapping(value="/sym/adr/getAdressCntcApi")
    public void getAddrApi(HttpServletRequest req, ModelMap model, HttpServletResponse response) throws Exception {

    	String currentPage = req.getParameter("currentPage");
		String countPerPage = req.getParameter("countPerPage");
		String confmKey = req.getParameter("confmKey");
		String keyword = req.getParameter("keyword");
		String apiUrl = "http://www.juso.go.kr/addrlink/addrLinkApi.do?currentPage="+currentPage+"&countPerPage="+countPerPage+"&keyword="+URLEncoder.encode(keyword,"UTF-8")+"&confmKey="+confmKey;
		URL url = new URL(apiUrl);
    	BufferedReader br = new BufferedReader(new InputStreamReader(url.openStream(),"UTF-8"));
    	StringBuffer sb = new StringBuffer();
    	String tempStr = null;
    	while(true){
    		tempStr = br.readLine();
    		if(tempStr == null) break;
    		sb.append(tempStr);	
    	}
    	br.close();
    	response.setCharacterEncoding("UTF-8");
		response.setContentType("text/xml");
		response.getWriter().write(sb.toString());
    }
</code>

== JSON을 활용한 웹 페이지 호출 방식 ==
도로명주소연계 페이지의 "주소가져오기_JSON" 버튼을 클릭하면 웹 페이지 호출 방식으로 주소정보를 연계한다. \\
이 때 연계 신청을 통해 받은 승인키를 포함해야 한다. (공통 컴포넌트 내에 제공되는 승인키는 임의의 값으로 정상동작하지 않으며 프로젝트별로 등록을 통해 배포받아야 하는 값이다.)\\
만약 아직 승인을 받지 않은 상태에서 연계가 정상적으로 동작하는지 미리 확인하고자 한다면 "주소가져오기(테스트)_Controller" 버튼을 활용할 수 있다. 이 경우 검색어에 해당하는 데이터가 아닌 임의의 데이터를 전송받는다. \\

주소정보연계 JSP의 관련 javascript function는 아래와 같다.


<code javascript>
function getAddr(){
	$.ajax({
		 //url :"http://행정망 IP/addrlink/addrLinkApiJsonp.do"  //행정망
		 url :"http://www.juso.go.kr/addrlink/addrLinkApiJsonp.do"  //인터넷망
		,type:"post"
		,data:$("#form").serialize()
		,dataType:"jsonp"
		,crossDomain:true
		,success:function(xmlStr){
			if(navigator.appName.indexOf("Microsoft") > -1){
				var xmlData = new ActiveXObject("Microsoft.XMLDOM");
				xmlData.loadXML(xmlStr.returnXml)
			}else{
				var xmlData = xmlStr.returnXml;
			}
			$("#list").html("");
			var errCode = $(xmlData).find("errorCode").text();
			var errDesc = $(xmlData).find("errorMessage").text();
			if(errCode != "0"){
				alert(errCode+"="+errDesc);
			}else{
				if(xmlStr != null){
					makeList(xmlData);
				}
			}
		}
	    ,error: function(xhr,status, error){
	    	alert("에러발생");
	    }
	});
}
</code>


===== 사용방법(2.팝업 API =====

사용자가 [주소연계API 팝업 호출 JSP]를 통해서 [팝업_domainChk]버튼 클릭시 [주소연계API 팝업 JSP]을 호출하여 주소를 실시간으로 검색 할 수 있습니다.\\ 

2.1)주소연계API 팝업 호출 JSP

<code html>

<%@ page language="java" contentType="text/html; charset=UTF-8"
    pageEncoding="UTF-8"%>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<script language="javascript">

function goPopup(){
	// 주소검색을 수행할 팝업 페이지를 호출합니다.
	// 호출된 페이지(jusopopup.jsp)에서 실제 주소검색URL(http://www.juso.go.kr/addrlink/addrLinkUrl.do)를 호출하게 됩니다.
	var pop = window.open("/popup/jusoPopup.jsp","pop","width=570,height=420, scrollbars=yes, resizable=yes"); 
}


function jusoCallBack(roadFullAddr,roadAddrPart1,addrDetail,roadAddrPart2,engAddr, jibunAddr, zipNo, admCd, rnMgtSn, bdMgtSn){
		// 팝업페이지에서 주소입력한 정보를 받아서, 현 페이지에 정보를 등록합니다.
		document.form.roadFullAddr.value = roadFullAddr;
		document.form.roadAddrPart1.value = roadAddrPart1;
		document.form.roadAddrPart2.value = roadAddrPart2;
		document.form.addrDetail.value = addrDetail;
		document.form.engAddr.value = engAddr;
		document.form.jibunAddr.value = jibunAddr;
		document.form.zipNo.value = zipNo;
		document.form.admCd.value = admCd;
		document.form.rnMgtSn.value = rnMgtSn;
		document.form.bdMgtSn.value = bdMgtSn;
}

</script>
<title>주소 입력 샘플</title>
</head>
<body>
<form name="form" id="form" method="post">

	<input type="button" onClick="goPopup();" value="팝업_domainChk"/>
	<div id="list"></div>
	<div id="callBackDiv">
		<table>
			<tr><td>도로명주소 전체(포멧)</td><td><input type="text"  style="width:500px;" id="roadFullAddr"  name="roadFullAddr" /></td></tr>
			<tr><td>도로명주소           </td><td><input type="text"  style="width:500px;" id="roadAddrPart1"  name="roadAddrPart1" /></td></tr>
			<tr><td>고객입력 상세주소    </td><td><input type="text"  style="width:500px;" id="addrDetail"  name="addrDetail" /></td></tr>
			<tr><td>참고주소             </td><td><input type="text"  style="width:500px;" id="roadAddrPart2"  name="roadAddrPart2" /></td></tr>
			<tr><td>영문 도로명주소      </td><td><input type="text"  style="width:500px;" id="engAddr"  name="engAddr" /></td></tr>
			<tr><td>지번                 </td><td><input type="text"  style="width:500px;" id="jibunAddr"  name="jibunAddr" /></td></tr>
			<tr><td>우편번호             </td><td><input type="text"  style="width:500px;" id="zipNo"  name="zipNo" /></td></tr>
			<tr><td>행정구역코드        </td><td><input type="text"  style="width:500px;" id="admCd"  name="admCd" /></td></tr>
			<tr><td>도로명코드          </td><td><input type="text"  style="width:500px;" id="rnMgtSn"  name="rnMgtSn" /></td></tr>
			<tr><td>건물관리번호        </td><td><input type="text"  style="width:500px;" id="bdMgtSn"  name="bdMgtSn" /></td></tr>
		</table>
	</div>

</form>
</body>
</html>
                                                     
</code>
 

2.2)주소연계API 팝업 JSP(jusoPopup.jsp) \\ \\
입력 파리미터 정보
^파리이터정보 ^타입 ^필수여부  ^설명^
|confmKey|String|Y|신청 시 부여받은 승인키|
|returnUrl|String|Y|주소 검색 결과를 리턴받을 URL(통합검색창을 호출한 페이지)|
\\
출력 파라미터 정보
^파리이터정보 ^타입 ^필수여부  ^설명^
|roadFullAddr|String|Y|전체 도로명주소|
|roadAddrPart1|String|Y|도로명주소(참고항목 제외)|
|roadAddrPart2|String|N|도로명주소 참고항목|
|jibunAddr|String|Y|지번 정보|
|engAddr|String|Y|도로명주소(영문)|
|zipNo|String|Y|우편번호|
|admCd|String|Y|행정구역코드|
|rnMgtSn|String|Y|도로명코드|
|bdMgtSn|String|Y|건물관리번호|
|addrDetail|String|N|고객 입력 상세 주소|

<code java>

<%@ page language="java" contentType="text/html; charset=UTF-8" pageEncoding="UTF-8"%>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Insert title here</title>
<% 
	//request.setCharacterEncoding("UTF-8");  //한글깨지면 주석제거
	//request.setCharacterEncoding("EUC-KR");  //해당시스템의 인코딩타입이 EUC-KR일경우에
	String inputYn = request.getParameter("inputYn"); 
	String roadFullAddr = request.getParameter("roadFullAddr"); 
	String roadAddrPart1 = request.getParameter("roadAddrPart1"); 
	String roadAddrPart2 = request.getParameter("roadAddrPart2"); 
	String engAddr = request.getParameter("engAddr"); 
	String jibunAddr = request.getParameter("jibunAddr"); 
	String zipNo = request.getParameter("zipNo"); 
	String addrDetail = request.getParameter("addrDetail"); 
	String admCd    = request.getParameter("admCd");
	String rnMgtSn = request.getParameter("rnMgtSn");
	String bdMgtSn  = request.getParameter("bdMgtSn");
%>
</head>
<script language="javascript">
function init(){
	var url = location.href;
	var confmKey = "승인키"; //연계신청시 부여받은 승인키입력(테스트용 승인키 : TESTJUSOGOKR)
	var inputYn= "<%=inputYn%>";
	if(inputYn != "Y"){
		document.form.confmKey.value = confmKey;
		document.form.returnUrl.value = url;
		//document.form.action="http://행정망 IP/addrlink/addrLinkUrl.do"; //행정망
		document.form.action="http://www.juso.go.kr/addrlink/addrLinkUrl.do"; //인터넷망
		document.form.submit();
	}else{
		opener.jusoCallBack("<%=roadFullAddr%>","<%=roadAddrPart1%>","<%=addrDetail%>","<%=roadAddrPart2%>","<%=engAddr%>","<%=jibunAddr%>","<%=zipNo%>", "<%=admCd%>", "<%=rnMgtSn%>", "<%=bdMgtSn%>");
		window.close();
	}
}
</script>
<body onload="init();">
	<form id="form" name="form" method="post">
		<input type="hidden" id="confmKey" name="confmKey" value=""/>
		<input type="hidden" id="returnUrl" name="returnUrl" value=""/>
		<!-- 해당시스템의 인코딩타입이 EUC-KR일경우에만 추가 START-->
		<!-- 
		<input type="hidden" id="encodingType" name="encodingType" value="EUC-KR"/>
		 -->
		<!-- 해당시스템의 인코딩타입이 EUC-KR일경우에만 추가 END-->
	</form>
</body>
</html>
                                          
</code>

===== 사용방법(3.주소DB 활용방법 =====


주소DB 구축시 천만 건 기준의 건물단위 정보와 6백만 건 기준의 주소단위 매칭데이터 및 도로명주소 일변동자료, \\  
사서함을 도로명주소 레이아웃으로 변환한 사서함DB, 주소와 좌표가 매칭된 위치정보요약DB를 제공합니다

^구분 ^설명^
|**전체주소**|아파트와 같은 집합건물의 상세 동 단위 건물정보와 도로명주소에 매칭되는 관련지번, \\ 도로명코드 등의 전체분과 전월 대비 변동분을 월 단위로 제공합니다.|
|**매칭데이터**|상세 동 단위의 건물정보에서 도로명주소만 요약한 정보로서, 주소와 지번, 부가정보 및 \\ 도로명코드로 구성하여 월 단위로 전체분과 전월대비 변동분을 제공합니다.|
|**일변동자료(전체주소)**|매일 생성, 변경, 폐지되는 도로명주소의 변동사항을 일일 변동자료로 제공하며, \\ 제공되는 레이아웃은 전체주소를 기준으로 합니다.|
|**사서함 DB**|사서함을 도로명주소 제공DB의 형식으로 구성하여 제공합니다.|
|**위치정보 요약DB**|도로명주소와 주출입구의 위치값이 매칭된 정보를 제공합니다. \\ ※ 주출입구의 위치를 나타내는 좌표는 GRS80 UTM-K 기준 입니다.|