연계신청(원격 정보제공 서비스)
매일 변경되는 최신 도로명주소 변동자료를 제공합니다.
도로명주소 연계
본 서비스는 별도의 행정절차 없이 연계 신청 즉시 승인키가 발급되며, 가이드 및 샘플소스를 활용하여 구축 후 바로 이용 가능합니다.
도로명주소 변동자료는 매일 오전 07시 이후 다운로드 가능합니다.
※ 인터넷망, 행정망 모두 이용 가능합니다. 행정망 서비스를 위한 도로명주소 연계 URL은 별도로 문의 주시기 바랍니다.
[문의] 1588-0061(7번 도로명주소)
시스템 구축 언어별(JAVA, .NET) 연계적용방법
소스 및 가이드(연계에 필요한 클라이언트 라이브러리 포함)
주요정보
JAVA기반일 경우, 일변동 DB 자동제공 클라이언트 API에는 아래와 같은 파일이 제공됩니다.
ADSClient-x.x.jar : 클라이언트 라이브러리(x.x : 버전 넘버), 이 jar 파일은 적용하는 application의 classpath에 위치해야 합니다.
ADSClient-x.x.zip : 클라이언트 라이브러리의 소스파일, 이 zip 파일은 API를 통해 개발하지 않고, 소스를 수정하여 사용할 수 있습니다.
ADSClient-x.x-doc.zip : API의 Java Document입니다. 라이브러리에서 사용되는 함수에 대한 자세한 설명을 보실수 있습니다.
일변동 DB 자동제공_가이드_JAVA.pdf : 일변동 DB 자동제공 가이드를 통해서 서비스를 적용하기 위한 설명을 확인할 수 있습니다.
.NET기반일 경우, 일변동 DB 자동제공 클라이언트 API에는 아래와 같은 파일이 제공됩니다.
ADSClient-dll-x.x.jar : 클라이언트 라이브러리(x.x : 버전 넘버), 이 DLL 파일은 적용하는 application에 위치해야 합니다.
ADSClient-x.x.zip : 클라이언트 라이브러리의 소스파일, 이 zip 파일은 DLL를 통해 개발하지 않고, 소스를 수정하여 사용할 수 있습니다.
일변동 DB 자동제공_가이드_닷넷.pdf : 일변동 DB 자동제공 가이드를 통해서 서비스를 적용하기 위한 설명을 확인할 수 있습니다.
1. 승인키[필수] : 변동자료 연계서비스 사용을 위해 제공받은 승인키
2. 요청자료 구분[필수] : 제공 받고자 하는 요청자료의 구분값(가이드 문서 참고)
3. 변동자료 날짜구분[필수] : 일변동 자료(D), 월변동 자료(M)으로 구분되며, 매칭데이터및 지도 자료는 D만 가능함, 기초구역관련 정보는 M
4. 재반영 포함여부[필수] : 재반영 데이터를 포함하여 제공받을지 여부(기본으로 Y 설정을 통해서, 재반영 데이터도 일변동 자료 제공시 함께 적용할 수 있도록 해야합니다.)
5. 요청 데이터 일자(From) : 일반적으로 일변동 자료 요청시에는 해당 값을 요청하지 않습니다.
6. 요청 데이터 일자(To) : 일반적으로 일변동 자료 요청시에는 해당 값을 요청하지 않습니다.
// ADSReceiver 클래스의 receiveAddr()함수를 호출하여, 데이터를 요청합니다.
// receiveAddr()함수에 사용되는 입력파라미터는 app_key, date_gb, cntc_cd, retry_in, req_date_from, req_date_to입니다.
// 결과 데이터는 ReceiveDatas 객체로 반환되며, 이를 getReceiveDatas(int order)를 통해서 정렬하여 ArrayList 타입으로 반환합니다.
import java.io.File;
import java.io.FileInputStream;
import java.util.ArrayList;
import java.util.Properties;
// import 필요한 클래스 정보
import kr.go.ads.client.ADSReceiver;
import kr.go.ads.client.ReceiveData;
import kr.go.ads.client.ReceiveDatas;
public class UpdateClient {
public static void main(String[] args){
UpdateClient uc = new UpdateClient();
try{
uc.getAddrInfo();
}catch(Exception ex){
ex.printStackTrace();
}
}
public void getAddrInfo(){
ADSReceiver ads = new ADSReceiver(); // ADSReceiver 객체 생성
String app_key = "AAABBBCCC"; // 승인키
String date_gb = "D"; // 날짜 구분
String retry_in = "Y"; // 재반영 요청 여부
String cntc_cd = "009000"; // 자료 요청 구분
String req_date_from; // 요청일자(From)
String req_date_to; // 요청일자(To)
// 일변동 자료를 저장할 장소를 설정합니다.
ads.setFilePath("addrInfo");
ads.setCreateDateDirectory(ADSUtils.YYMMDD);
try {
// 변동자료 연계서비스 요청 및 응답데이터 확인
ReceiveDatas receiveDatas = ads.receiveAddr(app_key, date_gb, cntc_cd, retry_in, req_date_from, req_date_to);
/* --------------------------------- 응답 결과 확인 --------------------------------- */
if(receiveDatas.getResult() != 0){
if(receiveDatas.getResult() == -1){
// 서버 접속 실패 : 잠시후 재 시도 하시기 바랍니다.
System.out.println("서버 접속 실패");
}
// 서버 페이지 오류 사항 확인
System.out.println("Result code : "+receiveDatas.getResult());
System.out.println("Response code : "+receiveDatas.getResCode());
System.out.println("Response Msg : "+receiveDatas.getResMsg());
System.out.println("Total count : "+receiveDatas.getResTotalCnt());
System.out.println("Normal count : "+receiveDatas.getResNormalCnt());
System.out.println("Retry count : "+receiveDatas.getResRetryCnt());
return;
}
// 서버 응답 확인
System.out.println("Response code : "+receiveDatas.getResCode()); // 응답코드
System.out.println("Response Msg : "+receiveDatas.getResMsg()); // 응답메시지
System.out.println("Total count : "+receiveDatas.getResTotalCnt()); // 전체 자료수
System.out.println("Normal count : "+receiveDatas.getResNormalCnt()); // 변동 자료수
System.out.println("Retry count : "+receiveDatas.getResRetryCnt()); // 재반영 자료수
if(!"P0000".equals(receiveDatas.getResCode())){
// 거절 응답
return;
}
/* --------------------------------- 응답 결과 완료 --------------------------------- */
// 결과 데이터 정렬
ArrayList result = receiveDatas.getReceiveDatas(ADSUtils.UPDATE_ASC);
Iterator itr = result.iterator();
while(itr.hasNext()){
// 결과 데이터 건별 정보 확인
ReceiveData receiveData = (ReceiveData)itr.next();
System.out.print(" CNTC : ");
System.out.print(receiveData.getCntcCode());
System.out.print(" RES_CODE : ");
System.out.println(receiveData.getResCode());
if(!"P0000".equals(receiveData.getResCode())){
// 해당 파일응답 에러. 특히 E1001 인경우, 해당 파일을 아직 생성하지 못한 응답으로 추후 재시도 필요.
System.out.println("해당파일에 대한 응답이 정상이 아니기에 재 요청 필요");
}
}
} catch (Exception e) {
e.printStackTrace();
}
}
}
// ADSReceiver 클래스의 receiveAddr()함수를 호출하여, 데이터를 요청합니다.
// receiveAddr()함수에 사용되는 입력파라미터는 app_key, date_gb, cntc_cd, retry_in, req_date_from, req_date_to입니다.
// 결과 데이터는 ReceiveDatas 객체로 반환되며, 이를 getReceiveDatas(int order)를 통해서 정렬하여 ArrayList 타입으로 반환합니다.
using System;
using System.Collections.Generic;
using System.Text;
using kr.go.ads.client;
namespace UpdateClient
{
class Program
{
static void Main(string[] args)
{
Program uc = new Program();
try
{
uc.getAddrInfo();
}
catch (Exception ex)
{
System.Console.Write(ex.StackTrace);
}
}
public void getAddrInfo(){
ADSReceiver ads = new ADSReceiver();
Properties props = new Properties();
String app_key,req_date,cntc_cd,req_date_to,date_gb,retry_in;
//-----------------------요청 정보 설정------------------------------------------
app_key = props.APP_KEY;
req_date = props.REQ_DATE;
req_date_to = props.REQ_DATE_TO;
cntc_cd = props.CNTC_CD;
date_gb = props.DATE_GB;
retry_in = props.RETRY_IN;
// 일변동 자료를 저장할 장소를 설정합니다.
ads.setFilePath("addrInfo");
ads.setCreateDateDirectory(ADSUtils.YYMMDD);
//-----------------------------------------------------------------------------
try {
ReceiveDatas receiveDatas = ads.receiveAddr(app_key, date_gb, cntc_cd, retry_in, req_date, req_date_to);
/* --------------------------------- 응답 결과 확인 --------------------------------- */
if(receiveDatas.Result != 0){
if(receiveDatas.Result == -1){
// 서버 접속 실패 : 잠시후 재 시도 하시기 바랍니다.
System.Console.WriteLine("서버 접속 실패");
}
// 서버 페이지 오류 사항 확인
System.Console.WriteLine("Result code : " + receiveDatas.Result);
System.Console.WriteLine("Response code : " + receiveDatas.ResCode);
System.Console.WriteLine("Response Msg : " + receiveDatas.getResMsg());
System.Console.WriteLine("Total count : " + receiveDatas.ResTotalCnt);
System.Console.WriteLine("Normal count : " + receiveDatas.ResNormalCnt);
System.Console.WriteLine("Retry count : " + receiveDatas.ResRetryCnt);
return;
}
// 서버 응답 확인
System.Console.WriteLine("Response code : " + receiveDatas.ResCode); // 응답코드
System.Console.WriteLine("Response Msg : " + receiveDatas.getResMsg()); // 응답메시지
System.Console.WriteLine("Total count : " + receiveDatas.ResTotalCnt); // 전체 자료수
System.Console.WriteLine("Normal count : " + receiveDatas.ResNormalCnt); // 변동 자료수
System.Console.WriteLine("Retry count : " + receiveDatas.ResRetryCnt); // 재반영 자료수
/* --------------------------------- 응답 결과 완료 --------------------------------- */
// 결과 데이터 정렬
List <ReceiveData> result = receiveDatas.getReceiveDatas(ADSUtils.UPDATE_ASC);
foreach (ReceiveData receiveData in result)
{
// 결과 데이터 건별 정보 확인
System.Console.WriteLine(receiveData.FileName);
}
} catch (Exception e) {
System.Console.WriteLine(e.StackTrace);
}
}
}
}
데이터 다운로드 설정 및 서비스 호출방법
ads.setFilePath(String filePath)로 파일을 저장할 기본 Path를 설정.
EX) ads.setFilePath("addrInfo");
setCreateDateDirectory(String datePattern)로 해당 날짜형식의 하위 디렉토리를 자동 생성 가능.
입력 파라미터인 String datePattern값이 null 이면 기본 'YYYYMMDD' 형식의 디렉토리에 변동 자료가 저장.
입력 파라미터는 ADSUtils.YYYYMMDD, ADSUtils.YYMMDD, ADSUtils.YYYYY, ADSUtils.MMDD 4종류를 제공.
EX) ads.setCreateDateDirectory(ADSUtils.YYMMDD);
setUsingDate(int usingDatePattern) 통해서, 디렉토리 생성시 일변동자료의 기준일, 일변동자료 파일 생성일을 기준으로 해당 디렉토리에 파일이 저장.
일변동자료 기준일(ADSUtils.FILE_DATE) : 변동내역의 기준일자 입니다.
예) 20150101일 변동 자료 → 20150101일자에 해당하는 디렉토리에 파일이 저장.
입력 파라미터는 ADSUtils.YYYYMMDD, ADSUtils.YYMMDD, ADSUtils.YYYYY, ADSUtils.MMDD 4종류를 제공.
EX) ads.setUsingDate(ADSUtils.MAKE_DATE);
// 일변동자료 다운로드 호출함수
ReceiveDatas receiveDatas = ads.receiveAddr(app_key, date_gb, cntc_cd, retry_in, req_date_from, req_date_to);
// 재반영 다운로드 호출함수, retry_in, req_date_from, req_date_to 파라미터 불필요
ReceiveDatas receiveDatas = ads.receiveRetry(app_key, date_gb, cntc_cd);.
결과 데이터 처리 메소드 및 샘플소스
// 다운로드 받은 결과 데이터를 원하는 방식으로 Sort를 수행해서 List를 전달
// 반영 순서대로 정렬
ArrayList result = receiveDatas.getReceiveDatas(ADSUtils.UPDATE_ASC);
// 파일이 생성된 일자별 정렬
ArrayList result = receiveDatas.getReceiveDatas(ADSUtils.MAKE_ASC);
제공 받은 데이터의 정보 확인 가능.
제공 받은 데이터 파일을 정렬하여 ArrayList로 결과값을 제공.
제공받은 각 파일의 정보는 ReceiveData 객체로 제공되며, 아래와 같이 확인 가능.
receiveData.getFileName() 파일명 정보
receiveData.getFilePath() 파일 절대경로
receiveData.getRetryYn() 재반영 데이터 여부(Y:재반영데이터, N:일반 변동데이터)
receiveData.getFileDate() 변동자료 파일기준일(YYYYMMDD 형식)
receiveData.getCreateDate() 변동자료 파일 생성일(YYYYMMDD 형식)
receiveData.getCntcCode() 요청자료 코드
receiveData.getFileSize() 파일 사이즈(byte)
receiveData.getResCode() 응답코드
receiveData.getResMsg() 응답메시지(한글)
// 결과 데이터 확인 : 데이터를 정렬하여 가져올 수 있습니다.
ArrayList result = receiveDatas.getReceiveDatas(ADSUtils.UPDATE_ASC);
Iterator itr = result.iterator();
while(itr.hasNext()){
ReceiveData receiveData = (ReceiveData)itr.next();
System.out.print("DOWNLOAD FILE NAME:");
System.out.print(receiveData.getFileName());
System.out.print(" RETRY:");
System.out.print(receiveData.getRetryYn());
System.out.print(" MAKE DATE:");
System.out.print(receiveData.getCreateDate());
System.out.print(" FILE DATE:");
System.out.println(receiveData.getFileDate());
System.out.print(" CNTC : ");
System.out.print(receiveData.getCntcCode());
System.out.print(" RES_CODE : ");
System.out.println(receiveData.getResCode());
}
// 결과 데이터 확인 : 데이터를 정렬하여 가져올 수 있습니다.
List <ReceiveData> result = receiveDatas.getReceiveDatas(ADSUtils.UPDATE_ASC);
foreach (ReceiveData receiveData in result)
System.Console.WriteLine("DOWNLOAD FILE NAME:");
System.Console.WriteLine(receiveData.FileName);
System.Console.WriteLine(" RETRY:");
System.Console.WriteLine(receiveData.RetryYn);
System.Console.WriteLine(" MAKE DATE:");
System.Console.WriteLine(receiveData.CreateDate);
System.Console.WriteLine(" FILE DATE:");
System.Console.WriteLine(receiveData.FileDate);
}
기타 언어 연계적용방법
도로명주소 연계는 개발언어의 종류와 상관없이 URL정보를 만들어 도로명주소 서버로 요청하면, 해당하는 자료를 제공받을 수 있는 구조입니다.
아래의 순서와 기준에 맞게 개발하시면, Java/.Net 외의 개발언어로 도로명주소 연계를 제공받을 수 있습니다.
연계적용방법 가이드
-
- 가이드
연계적용방법
URL정보를 만들어 연계정보를 요청하면, 해당하는 변동자료를 수신받을 수 있습니다.
SAMPLE URL : http://update.juso.go.kr/updateInfo.do?app_key=인증키&date_gb=D&cntc_cd=009004&retry_in=Y&req_dt=20180501
app_key[필수] : 도로명주소 연계 신청을 통해 발급받은 승인키
date_gb[필수] : 날짜구분 코드(D:일변동)
cntc_cd[필수] : 자료요청 구분 코드(JAVA 또는 .NET 가이드문서 참조)
retry_in[필수]: 재반영 데이터 포함여부(Y:재반영 데이터 포함 제공, N:재반영 데이터 미제공)
req_dt : 요청일자 From(요청일자 설정시, 해당 일에 대한 정보를 제공 받는다.)
req_dt2 : 요청일자 To(요청기간동안의 데이터를 요청시 설정, 단 From~To 사이의 기간이 10일을 초과할 수 없다.)
Response 수신정보를 100Byte로 나눠 저장합니다. 특정경로에 생성일자폴더(YYMMDD)를 만들고, 100Byte 이후부터 파일사이즈 길이만큼
데이터를 읽어 파일을 생성합니다.
SAMPLE DATA : 0120180501AlterD.JUSUBU.20180501.ZIP 0000384849P0000001000N20180501
0~2 Byte : 파일 순번
2~10 Byte : 기준일
10~60 Byte : 파일명(공백제거)
60~70 Byte : 파일사이즈
70~75 Byte : 응답코드
75~81 Byte : 제공받은 자료요청 구분 코드(cntc_cd)정보
81~82 Byte : 재반영데이터 여부
82~90 Byte : 생성일자
Response 수신정보의 응답코드별 예외처리를 설정합니다.
- 응답코드별 의미
P0000 : 정상 반영
P1000 : 이미 정상 반영이 이루어진 상태입니다.
중복요청 필요하면, URL정보 호출 시 req_date(수신받을 날짜)값을 입력하시기 바랍니다.
E0001 : 승인키가 입력되지 않았습니다. URL정보 호출 시 app_key(승인키)값을 입력하시기 바랍니다.
E0002 : 해당 승인키가 미승인상태입니다.
E0003 : 존재하지않는 승인키 입니다. 발급받은 승인키와 일치하는지
다시 확인하시기 바랍니다.
E0004 : 도로명주소 연계 신청으로 발급받은 승인키를 사용하시기 바랍니다.
E1001 : 요청하신 날짜에 해당하는 파일이 존재하지 않습니다.
E1002 : 자료요청 구분값이 입력되지 않았습니다.
URL정보 호출 시
cntc_cd(자료요청 구분)값을 입력하시기 바랍니다.
E1004 : 요청기간이 최대 기일을 초과 하였습니다.(MAX 10일)
E1005 : 응답메세지 생성 과정에서 예기치 않은 오류가 발생했습니다.
E1006 : URL정보 호출 시
date_gb(구분)값을 입력하시기 바랍니다.
E1007 : 요청일자는 YYYYMMDD 형식입니다.
URL정보 호출 시 req_date, req_date_to 값이 빈값이 아닐 경우, 형식을 확인하시기 바랍니다.
E1008 : 승인되지 않은 cntc_cd(자료요청 구분)값이 입력되었습니다.
E1999 : 정의되지 않은 오류가 발생했습니다.
import urllib.request
import os
# 요청 url을 변수로 지정
url ="http://update.juso.go.kr/updateInfo.do?app_key=인증키&date_gb=D&retry_in=Y&cntc_cd=009000&req_dt=20180202&req_dt2=20180203"
u = urllib.request.urlopen(url)
while True:
# 파일 순번 존재확인
file_seq = u.read(2)
# 파일 순번 미존재시 종료(break)
if not file_seq:
break
# 수신정보 저장 // strip() = 공백삭제, decode() = 바이트를 스트링으로 변환
file_base_dt = u.read(8)
file_name = u.read(50).strip().decode()
file_size = int(u.read(10))
res_code = u.read(5)
req_code = u.read(6)
replay = u.read(1)
create_dt = u.read(8).decode()
# 파일 다운로드 경로 지정
outpath = "C:/"+create_dt[2:8]+"/"
# 파일 다운로드 폴더 생성
if not os.path.isdir(outpath):
os.makedirs(outpath)
# zip파일 데이터 읽기 & 쓰기
zip_file = u.read(file_size+10)
f = open(outpath+file_name, 'wb')
f.write(zip_file)
f.close()