교통정보공개서비스이용자매뉴얼 2018.07 국토교통부
목차 1. OPEN API 소개 1 1.1 OPEN API란 1 1.2 제공서비스소개 1 1.3 서비스방식 1 1.4 공지사항 2 2. OPEN API 매뉴얼 3 2.1 개발가이드 3 2.2 교통소통정보 4 2.3 공사정보 6 2.4 사고정보 7 2.5 CCTV 영상 9 2.6 교통안전도우미 12 2.7 V M S정보 13 2.8 공지사항 14 2.9 API 적용방법 15 3. 공개키발급및관리 17
1. OPEN API 소개 1.1 OPEN API(Application Program Interface) 란... 누구나사용할수있도록공개된 API" 로써국토교통부교통정보관련콘텐츠및데이터를누구나쉽게활용하고웹서비스및어플리케이션개발을지원하기위하여 API 를외부에공개한것을말합니다. 위키피디아에서는 API 를 응용프로그램에서사용할수있도록만든인터페이스 로정의하고있습니다. 이 API 를외부에서사용할수있도록공개한것이 OPEN API 이며, 웹서비스의개방지향적인성격을가지고있습니다. 1.2 제공서비스소개 1.3 서비스방식 REST(Representational State Transfer) 방식 REST 는월드와이드웹과같은분산하이퍼미디어시스템을위한소프트웨어아키텍처의한형식으로, 로이필딩 (Roy Fielding) 의 2000 년박사학위논문에서소개되었습니다. 발표당시는대규모의네트워크시스템을위한방법이라는뜻이었지만최근이용되고있는 REST 는 HTTP 와 XML 을이용하여데이터를주고받는웹서비스를이용하는것으로쓰이고있습니다. - 1 -
위그림에서 http://openapi.its.go.kr/... 같은 URL 을통해서데이터를요청하고있으며그결과는 XML 형태로반환되며, 각각의요청과반환되는 XML 형식은아래와같은구조로이루어집니다. 위와같은방법을통해개발자는다양한매쉬업서비스및자체적인웹서비스, 응용어플리케이션을제작할수있습니다. 1.4 공지사항 OPEN API 관련매뉴얼및관련자료등을공지하며, 기타문의사항에대한답변을처리합니다. - 2 -
2. OPEN API 매뉴얼 2.1 개발가이드 API개발가이드 본가이드는국가교통정보센터의교통정보를활용하기위한 OPEN API 개발가이드입니다. 본개발가이드는많은개발방법중한가지예시이며, 일반적인웹서비스클라이언트개발과는어느정도차이가있음을알려드립니다. 환경구성 J2EE 기반의 OPEN API Client 개발을위한개발환경은아래와같습니다. 추가적으로다음과같은 Library 파일이필요합니다. 위라이브러리가운데 Apache Commons 라이브러리 (http://commons.apache.org/) 와 HttpComponents(http://hc.apache.org/) 라이브러리는명시된버전넘버보다최신의것을사용하셔도됩니다. - 3 -
환경구성파일다운로드주소 개발 Platform http://ww w.eclipse.org/dow nloads/ Java developer's kit http://ww w.oracle.com/technetwork/java/javase/downloads/ index.html Apache Commons 라이브러리 http://commons.apache.org Http Components 라이브러리 http://hc.apache.org/ 2.2 교통소통정보 도로별실시간소통정보를제공합니다. 요청 URL URL : http://openapi.its.go.kr/api/ntrafficinfo 샘플 : http://openapi.its.go.kr/api/ntrafficinfo?key=test&req Type=2&MinX=127.800000&MaxX=127.890000&Min Y=34.900000&MaxY=35.100000 이미지 : http://openapi.its.go.kr/api/wmtstile?key=test& zoom=7&row=49&col=108 요청변수 요청변수값설명 key string 공개키 ReqType string boundary 요청여부 (2) TrafficInfo string 교통정보 MinX double boundary MinX MinY double boundary MinY MaxX double boundary MaxX MaxY double boundary MaxY zoom int 지도 zoom level( 이미지정보요청시 ) row int 지도 tilerow( 이미지정보요청시 ) col int 지도 tilecol( 이미지정보요청시 ) - 4 -
출력결과필드 출력변수 값 설 명 RoadSectionCnt int 도로구간개수 RoadSectionId string 도로구간의고유식별번호 RoadNameText string 해당도로구간의도로명칭 StartNodeId string 도로구간시작노드의고유식별번호 EndNodeId string 도로구간종료노드의고유식별번호 TravelTime string 통행시간 ( 초 ) GenerateDate string 교통정보생성일시 샘플페이지 <?xml version="1.0" encoding="utf-8"?> <response> <coordtype>1</coordtype> <datacount>567</datacount> <data> <roadsectionid>1770000101</roadsectionid> <avgspeed>78</avgspeed><startnodeid>3270014200</startnodeid> <roadnametext> 일반국도 1 호선 </roadnametext> <traveltime>46</traveltime><endnodeid>1770000200</endnodeid> <generatedate>20141028102047</generatedate> <data> <roadsectionid>1770000201</roadsectionid> <avgspeed>80</avgspeed> <startnodeid>1770000200</startnodeid> <roadnametext> 일반국도 1 호선 </roadnametext> <traveltime>45</traveltime> <generatedate>20141028102047</generatedate> 에러메시지 000:system error 시스템에러발생시메시지 - 5 -
2.3 공사정보 도로별실시간공사정보를제공합니다. 요청 URL URL : http://openapi.its.go.kr:8082/api/neventidentity 샘플 : http://openapi.its.go.kr:8082/api/neventidentity?key=test &ReqType=2&MinX=127.100000&MaxX=128.890000 &MinY=34.100000&MaxY=39.100000&type=ex 요청변수 요청변수 값 설 명 key string 공개키 ReqType string boundary 요청여부 (2) type string 도로정보 its: 국도 ex: 고속도로 EventIdentity string 이벤트식별 MinX double boundary MinX MinY double boundary MinY MaxX double boundary MaxX MaxY double boundary MaxY 출력결과필드 출력변수값설명 CoordType string 좌표타입 DataCount int 공사정보개수 type string 도로정보 its: 국도 ex: 고속도로 EventId string 공사고유식별번호 EventType string 공사정보유형 CoordX double 경도좌표 CoordY double 위도좌표 LanesBlockType string 공사로인한차로차단방법 0 : 통제없음 1 : 갓길통제 2 : 차로부분통제 3 : 전면통제 LanesBlocked string 공사로인해차단된차로수 EventStartDay string 공사시작일 EventEndDay string 공사종료일 EventStartTime string 공사실제개시시간 EventEndTime string 공사실제종료시간 EventStatusMsg string 공사상황정보메시지 ExpectedCnt int 우회정보개수 ExpectedDetourMsg string 우회정보메시지 - 6 -
샘플페이지 통제 </eventstatusmsg> <eventstartday>20120109</eventstartday> <lanesblocked>110000</lanesblocked> <coordx>126.84840360634061</coordx> <eventtype>0</eventtype> /r p 에러메시지 000:system error 시스템에러발생시메시지 2.4 사고정보 도로별실시간사고정보를제공합니다. <?xml version="1.0" encoding="utf-8"?> - <response> <coordtype>1</coordtype> <datacount>1</datacount> - <data> <expecteddetourmsg /> <lanesblocktype>2</lanesblocktype> <eventstarttime /> <eventendday>20120110</eventendday> <coordy>37.31605561732977</coordy> <expectedcnt>0</expectedcnt> <eventendtime /> <eventstatusmsg>1,2 차로포장공사로인한차로 요청 URL 교통정보 OPEN API 이용자매뉴얼 URL : http://openapi.its.go.kr:8082/api/nincidentidentity 샘플 : http://openapi.its.go.kr:8082/api/ NIncidentIdentity?key=test &ReqType=2&MinX=127.100000&MaxX=128.890000 &MinY=34.100000&MaxY=39.100000&type=ex 요청변수 요청변수 값 설 명 key string 공개키 ReqType string boundary 요청여부 (2) type string 도로정보 its: 국도 ex: 고속도로 IncidentIdentity string 사고식별 MinX double boundary MinX MinY double boundary MinY MaxX double boundary MaxX MaxY double boundary MaxY - 7 -
출력결과필드 출력변수 값 설 명 CoordType string 좌표타입 DataCount int 공사정보개수 IncidentType string 사고유형 CoordX double 경도좌표 CoordY double 위도좌표 LanesBlockType string 차로차단방법 0 : 통제없음 1 : 갓길통제 2 : 차로부분통제 3 : 전면통제 IncidentMsg string 돌발상황정보메시지 IncidentDuration string 돌발상황지속여부 0 : 조치중 1 : 종료 ExpectedCnt int 우회정보개수 ExpectedDetourMsg string 우회정보메시지 샘플페이지 <?xml version="1.0" encoding="utf-8"?> - <response> <coordtype>1</coordtype> <datacount>2</datacount> - <data> <expecteddetourmsg /> <incidentduration>0</incidentduration> <incidentmsg> 낙석으로인한갓길통제 </incidentmsg> <lanesblocktype>1</lanesblocktype> <incidenttype>1</incidenttype> <coordy>37.26453470516242</coordy> <expectedcnt>0</expectedcnt> <coordx>126.97246113769795</coordx> - <data> <expecteddetourmsg /> <incidentduration>0</incidentduration> <incidentmsg> 차량 4 중추돌사고정리작업으로인한차로통제 </incidentmsg> <lanesblocktype>0</lanesblocktype> <incidenttype>1</incidenttype> <coordy>37.226238217427806</coordy> <expectedcnt>0</expectedcnt> <coordx>126.87719980232526</coordx> </response> 에러메시지 000:system error 시스템에러발생시메시지 - 8 -
2.5 CCTV 영상및정지영상 도로별실시간 CCTV 정보를제공합니다. 요청 URL 교통정보 OPEN API 이용자매뉴얼 CCTV 영상 URL : http://openapi.its.go.kr:8081/api/ncctvinfo CCTV 정지영상 URL : http://openapi.its.go.kr:8081/api/ncctvimage 영상샘플 : http://openapi.its.go.kr:8081/api/ncctvinfo?key=test &ReqType=2&MinX=127.100000&MaxX=128.890000 &MinY=34.100000&MaxY=39.100000&type=ex 정지영상샘플 : http://openapi.its.go.kr:8081/api/ncctvimage?key=test &ReqType=2&MinX=127.100000&MaxX=128.890000 &MinY=34.100000&MaxY=39.100000&type=ex 요청변수 요청변수 값 설 명 key string 공개키 ReqType string boundary 요청여부 (2) type string 도로정보 its: 국도 ex: 고속도로 CCTVInfo string CCTV 정보 MinX double boundary MinX MinY double boundary MinY MaxX double boundary MaxX MaxY double boundary MaxY 출력결과필드 출력변수값설명 CoordType string 좌표타입 DataCount int CCTV 개수 CoordX double 경도좌표 CoordY double 위도좌표 CCTVType string 1 : 실시간스트리밍 ( 예정 ) 2 : 동영상파일 3 : 정지영상 FileCreateTime string 시간구성파일 CCTVFormat string CCTV 형식 CCTVResolution string CCTV 해상도 RoadSectionId string 도로구간의고유식별번호 CCTVName string CCTV 설치지점명칭 CCTVurl string CCTV 영상의 url 주소 - 9 -
샘플페이지 - 동영상파일 <?xml version="1.0" encoding="utf-8"?> -<response> <coordtype>1</coordtype> <datacount>331</datacount> -<data> <roadsectionid/> <filecreatetime/> <cctvtype>2</cctvtype> <cctvurl>http://cctvsec.ktict.co.kr/4217/ 암호화된주소 </cctvurl> <cctvresolution/> <coordy>37.3783395772</coordy> <cctvformat>mp4</cctvformat> <cctvname>[ 국도 43 호선 ] 광주고산 IC</cctvname> <coordx>127.24144157</coordx> -<data> <roadsectionid/> <filecreatetime/> <cctvtype>2</cctvtype> <cctvurl>http://cctvsec.ktict.co.kr/4583/ 암호화된주소 </cctvurl> <cctvresolution/> <coordy>36.760816</coordy> <cctvformat>mp4</cctvformat> <cctvname>[ 국도 21 호선 ] 천안운전교차로 </cctvname> <coordx>127.251873</coordx> -<data> <roadsectionid/> <filecreatetime/> <cctvtype>2</cctvtype> <cctvurl>http://cctvsec.ktict.co.kr/4237/ 암호화된주소 </cctvurl> <cctvresolution/> <coordy>37.8169444</coordy> <cctvformat>mp4</cctvformat> <cctvname>[ 국도 46 호선 ] 가평사그막마을입구 </cctvname> <coordx>127.5102777</coordx> - 10 -
- 정지영상 <?xml version="1.0" encoding="utf-8"?> -<response> <coordtype>1</coordtype> <datacount>330</datacount> -<data> <roadsectionid/> <filecreatetime/> <cctvtype>3</cctvtype> <cctv im gur l>h ttp ://op tsvc.ktict.co.kr:8090/4583/ 암호화된주소 </cctvimgurl> <cctvresolution/> <coordy>36.760816</coordy> <cctvformat>jpeg</cctvformat> <cctvname>[ 국도 21 호선 ] 천안운전교차로 </cctvname> <coordx>127.251873</coordx> -<data> <roadsectionid/> <filecreatetime/> <cctvtype>3</cctvtype> <cctv im gur l>h ttp ://op tsvc.ktict.co.kr:8090/4681/ 암호화된주소 </cctvimgurl> <cctvresolution/> <coordy>36.1774400009</coordy> <cctvformat>jpeg</cctvformat> <cctvname>[ 국도 4 호선 ] 영동주곡리 </cctvname> <coordx>127.82612</coordx> 에러메시지 000:system error 시스템에러발생시메시지 - 11 -
2.6 교통안전도우미 고속도로교통안전정보를제공합니다. 요청 URL 교통안전도우미 URL : http://openapi.its.go.kr:8083/api/posincidentinfo? key=test&minx=127.1000&maxx=128.8900&miny=34.1000&maxy=3 9.1000 요청변수 요청변수 값 설 명 key string 공개키 gettype string 정보수신방식 (json, xml(default)) MinX double boundary MinX MinY double boundary MinY MaxX double boundary MaxX MaxY double boundary MaxY 출력결과필드 출력변수값설명 contentmsg string 제공문안 stepcd String 이벤트에대한제공순번 inctpcd string 콘텐츠유형 contentrank string 생성문안우선순위 routename String 이벤트시작위치 ( 노선명 ) routeno string 이벤트시작위치 ( 노선 ) startx string 이벤트시작위치 ( 경도 ) starty String 이벤트시작위치 ( 위도 ) updowndiv String 이벤트시작위치 ( 노선방향코드 ) startstdlinkid String 이벤트시작위치 ( 표준노드링크 ) rupdowndiv string 메세지수신위치 ( 차량진행방향코드 ) rrouteno string 메세지수신위치 ( 노선 ) rroutename string 메시지수신위치 ( 노선명 ) rstdlinkid string 메세지수신위치 ( 표준노드링크 ) rx string 메세지수신위치 ( 경도 ) ry string 메세지수신위치 ( 위도 ) incid string 이벤트ID - 12 -
2.7 V M S 정보 VMS 정보를제공합니다. 위경도좌표정보는 VMS 현황자료를참조하세요. 요청 URL VMS 정보 URL : http://openapi.its.go.kr:8082/api/vmsinfo?key=test 요청변수 요청변수값설명 key string 공개키 gettype string 정보수신방식 (json, xml(default)) 출력결과필드 출력변수 값 설 명 vmsmessage string VMS 정보메시지 vmsid int VMSID grdate double 문안생성일시 (YYYYM MDDHH24MIS S) vmsseqn double VMS DISPLAY 순서 - 13 -
2.8 공지사항 공지사항정보를제공합니다. 요청 URL 공지사항목록 URL : http://openapi.its.go.kr/api/notice?key=test &gettype=json 요청변수 요청변수값설명 key string 공개키 gettype string 정보수신방식 (json, xml(default)) 출력결과필드 출력변수 값 설 명 noticetext string 공지사항제목 noticetitle int 공지사항내용 count double 조회수 useyn double 사용여부 updatedate string 업데이트일시 rnum string 시간구성파일 - 14 -
2.9 API 적용방법 교통정보 OPEN API 이용자매뉴얼 교통소통정보 -고속도로및주요국도소통정보적용예시 ( 샘플코드는 HTML 로되어있으며다른언어로개발이가능합니다 ) 공사정보 - 주요국도공사정보적용예시 ( 샘플코드는 HTML 로되어있으며다른언어로개발이가능합니다 ) - 15 -
사고정보 - 주요국도사고정보적용예시 ( 샘플코드는 HTML 로되어있으며다른언어로개발이가능합니다 ) CCTV- 주요국도영상정보적용예시 ( 샘플코드는 HTML 로되어있으며다른언어로개발이가능합니다 ) - 16 -
3. 공개키발급및관리 국토교통부교통정보관련 OPEN API 는 HTTP 요청및 XML 응답형식의프로토콜을지원합니다. 이를통해개발자는다양한매쉬업서비스및자체적인웹서비스, 응용어플리케이션을제작할수있습니다. 본서비스를사용하기위해서는먼저공개키 (Key) 발급이필요합니다. OPEN API 회원가입을통하여공개키를발급해드립니다. 신청및키 (Key) 발급 공개키발급번호가있어야서비스목록에있는검색결과를제공받을수있습니다. 신청자가회원가입시사용할서비스를선택하여발급신청을합니다. 해당항목들을정확히기재하여주시고공공기관의경우기관명을입력하여주시기바랍니다. 신청정보입력을완료하고등록을클릭하시면자동으로회원가입과동시에키발급이됩니다. 기타 OPEN API메뉴얼탭메뉴에각서비스별로설명되어있는포맷에따라 XML DATA를원하시는목적에맞게사용할수있습니다. 하나의유저 (Key) 당서비스별하루 (24시간) 트래픽제한은현재없으며, 추후트래픽이과다하여전체서비스에영향을미칠경우일일트래픽이설정될수있습니다. - 17 -