6. API 규격¶

Endpoint

RUUT 교통 정보 : /ruut/version/segments
RUUT 이벤트 정보 : /ruut/version/incidents
RUUT TPEG : /ruut/version/tpeg

6.1. Geo Filtering¶

지도 상의 영역을 지정하고 해당 영역 내에 포함되는 데이터만 추출하는 데 사용합니다. 인증, V2X를 제외한 모든 RUUT 플랫폼 기능의 필수 파라미터 입니다. Geo Filtering 은 총 5개 종류가 제공되며 각각의 필터 타입을 규정하기 위한 파라미터를 병용 하여야 합니다.

6.1.1. Geo Filtering 파라미터 리스트¶

5개의 필터는 geoFilter 파라미터의 값 영역에 명시하여 활성화 할 수 있습니다. 각각의 필터는 동시 사용이 불가합니다. 또한, 해당 필터와 병용 되어야 하는 파라미터가 추가로 명시되지 않을 경우 필터가 정상 동작하지 않습니다.

Note

예) /endpoint?geoFilter=box&corner1={gps}&corner2={gps} *box should be combined with corner1 and corner2

Params	Type	Value	Description
geoFilter	String	box	2개 gps 좌표로 이루어진 사각 영역 필터링
		circle	중심 좌표(gps)와 반지름 으로 이루어진 원 영역 필터링
		polygon	3개 이상의 gps 좌표로 이루어진 다각형 영역 필터링 (8개 좌표 이내)
		pos	1개 gps 좌표에서 가장 가까운 세그먼트 필터링 (250미터 이내)
		centerpointBox	1개 gps 좌표를 무게중심으로 하는 사각형 영역 필터링
corner1	String	gps 좌표	box 필터의 대각 gps 좌표 (corner2 와 쌍)
corner2	String	gps 좌표	box 피렅의 대각 gps 좌표 (corner1 과 쌍)
center	String	gps 좌표	circle or centerpointBox 필터의 중심 좌표
radius	Integer	radius	circle 필터의 반지름 (미터)
height	Integer	height	centerpointBox 필터의 세로 값 (미터)
width	Integer	width	centerpointBox 필터의 가로 값 (미터)
points	String	gps 좌표 리스트	polygon 필터의 gps 좌표. 파이프 기호로 구분된 목록
point	String	gps 좌표	pos 필터의 gps 좌표
regionId	Integer	지역코드	행정 구역 단위 필터링을 위한 지역 코드 [1]

6.1.2. Geo Filtering 제한 사항¶

Geo filtering 은 파라미터 규칙 외 필터 성능 최적화 및 사용성 강화를 위한 제한 사항이 포함 됩니다.

탐색을 요청하는 도로 등급에 따라 제한이 적용 됩니다 (circle/box 필터 기준)

FRC 레벨 == 0 (고속도로) : 반지름 및 가로/세로 200km 이내 제한

0 < FRC 레벨 < 3 (국도, 고속화도로) : 반지름 및 가로/세로 100km 이내 제한

2 < FRC 레벨 (모든 도로) : 반지름 및 가로/세로 20km 이내 제한

regionId 필터링에 대한 응답은 별도 요청에 한하여 제공합니다.

해당 제한을 따르지 않은 요청에 대해서는 정상 응답을 하지 않으니 이에 유의 하시기 바랍니다 (오류 응답)

6.1.3. Geo Filtering 예제¶

Geo filter 는 모든 교통 정보 데이터 검색 요청의 필수 요소 입니다. 아래에 나온 필터의 종류에 따른 URL sample 을 참고하여 원하는 영역에 대한 필터링 조건을 설정하고 해당 URL 의 뒤에 세부 요청 파라미터를 추가하는 형태로 API 호출이 진행 됩니다.

region 의 경우 별도 채널을 통해 인증 받은 사용자만 사용 가능 합니다.

Filter	Method	URL Sample
box	GET	/endpoint?geoFilter=box&corner1={gps}&corner2={gps}
circle	GET	/endpoint?geoFilter=circle&center={gps}&radius={km}
polygon	GET	/endpoint?geoFilter=polygon&points={gps}\|{gps}\|{gps}\|…
pos	GET	/endpoint?geoFilter=pos&point={gps}
centerpointBox	GET	/endpoint?geoFilter=centerpointBox&center={gps}&height={km}\ &length={km}
region	GET	/endpoint?geoFilter=region&regionId={region ID}

6.2. RUUT¶

RUUT 플랫폼에서 자체적으로 제공하고 있는 API 구성을 설명 합니다. RUUT API 는 크게 Segement 와 Incident 로 구성 되어 있습니다. Segement 는 실시간 교통 정보 검색에 사용되며, Incident 는 실시간 이벤트 (사고, 공사, 재해 등) 검색에 사용됩니다. TPEG2 데이터 검색은 TPEG2 섹션을 참고 하시기 바랍니다.

6.2.1. Segment¶

RUUT API 의 path 파라미터로 사용되는 segment 는 실시간 교통 정보를 요청 하기 위해 사용 됩니다. 해당 교통 정보에 이벤트 (사고, 재해, 공사등)정보는 포함되지 않습니다. 이벤트 정보는 아래 incident 를 참조하시기 바랍니다.

Segment Request

GET

/ruut/{version}/segments?{geo-query}?{set of parameters}

RUUT API 에 대한 요청은 위와 같은 URL로 구성 됩니다. 앞서 언급한 바와 같이 goe filter 를 먼저 URL 에 추가한 후 아래 Request Parameters 를 추가 입력하면 됩니다.

6.2.1.1. Segment Request Parameters¶

Params	Type	Value	Description
rttiField	String	speed	현재 측정 속도 반환
		limit	세그먼트 제한 속도 반환
		travleTime	세그먼트 횡단 평균 시간 반환
		freeFlow	정체 없을 시 속도 반환
		all(default)	모든 필드 반환
frc	Integer	frc	FRC 등급이 같은 항목만 반환 (쉼표 나누어 여러 개의 등급 명시 가능)
		all(default)	모든 FRC 등급 데이터 반환
lr	String	openLr	위치 참조 정보로 openLR 인코딩 정보 반환
		agoraC	위치 참조 정보로 AGORA-C 인코딩 정보 반환
		all (default)	위치 참조 정보로 openLR / AGORA-C 인코딩 정보 반환
lane	String	on (default)	차선 단위 교통 정보 활성화
		off	차선 단위 교통 정보 비활성화
segmentCoordinates	String	on (default)	제공 세그먼트의 시작/끝 노드의 GPS 좌표 정보 반환
		off	세그먼트 GPS 정보 반환 않음

6.2.1.2. Segment Response Elements¶

Note

응답은 하나 이상의 segment 로 구성 되며 JSON array 형태로 구성 됩니다.

Property	Type	Description
segmentId	String	세그먼트의 ID
roadCategory	String	세그먼트의 도로 레벨
speed	Integer	세그먼트의 측정 차량 속도
limit	Integer	세그먼트의 제한 속도
freeFlow	Integer	세그먼트 정체 없을 경우 차량 평균 속도
travelTime	String	세그먼트를 관통 하는데 걸리는 시간 (초)
openLr	String	위치 참조를 위한 openLR encoded code
agoraC	String	위치 참조를 위한 AGORA-C encoded code
lane	Array	차선 교통 정보 제공을 위한 배열 객체
laneNumber	String	차선 번호 (안쪽 차선부터 1차선)
laneSpeed	Integer	laneNumber 로 특정된 차선의 측정 속도
segmentCoordinates	Object	segment nodes 에 대한 GPS 좌표 제공 (양 끝 노드)
point1	Object	node 1 에 대한 GPS 좌표 컨테이너
lat	String	node 1 에 대한 GPS 위도
lon	String	node 1 에 대한 GPS 경도
point2	Object	node 2 에 대한 GPS 좌표 컨테이너
lat	String	node 2 에 대한 GPS 위도
lon	String	node 2 에 대한 GPS 경도
timeStamp	Datetime	정보 생성 시간

6.2.1.3. Segment Request/Response Example¶

RUUT API Segment 요청/응답 예제 를 참고 하시기 바랍니다.

6.2.2. Incident¶

RUUT API 의 path 파라미터로 사용되는 incident 는 도로 상의 이벤트인 사고, 재해, 공사, 일정, 통제 정보를 제공 합니다. 앞서 설명된 segment 와 마찬가지로 incident 의 query 파라미터 또한 Geo filtering 파라미터와 더불어 사용 됩니다.

Incident Request

GET

/ruut/{version}/incidents?{geo-query}?{set of parameters}

RUUT API 에 대한 요청은 위와 같은 URL로 구성 됩니다. 앞서 언급한 바와 같이 goe filter 를 먼저 URL 에 추가한 후 아래 Request Parameters 를 추가 입력하면 됩니다.

6.2.2.1. Request Parameters¶

Params	Type	Value	Description
incidentField	String	lane	이벤트 발생 차선 정보 반환
		length	이벤트가 영향을 미치는 물리적 범위 (미터) 반환
		vehicleKind	이벤트 차량 종류 반환
		description	이벤트 세부 정보 문자열 반환
		all(default)	모든 필드 반환
lr	String	openLr	위치 참조 정보로 openLR 인코딩 정보 반환
		agoraC	위치 참조 정보로 AGORA-C 인코딩 정보 반환
		all (default)	위치 참조 정보로 openLR / AGORA-C 인코딩 정보 반환
segmentCoordinates	String	on (default)	제공 세그먼트의 시작/끝 노드의 GPS 좌표 정보 반환
		off	세그먼트 GPS 정보 반환 않음

6.2.2.2. Response Elements¶

Note

응답은 하나 이상의 segment 로 구성 되며 JSON array 형태로 구성 됩니다.

Property	Type	Description
segmentId	String	세그먼트의 ID
incidentId	String	이벤트의 ID
incidentType	String	이벤트의 타입 (A:사고, B:공사, C:행사, D:재해, E:통제)
lane	Integer	이벤트 발생 차선 정보
vehicleKind	String	사고 차량 종류
description	String	이벤트 세부 정보 설명 문자열
schedule	Object	이벤트에 일정에 있을 때 제공되는 오브젝트 (이벤트 일정이 있는 경우에만 기본 제공)
isPlanned	String	계획된 이벤트인지 여부
startTime	Datetime	이벤트 개시 시점
endTime	Datetime	이벤트 종료 시점
reoccuring	Object	반복 이벤트인지 여부에 따라 제공되는 오브젝트
daysOfWeek	String	일주일 중 언제 반복 발생하는지
from	String	반복 이벤트 시작 시점
until	String	반복 이벤트 종료 시점
openLr	String	위치 참조를 위한 openLR encoded code
agoraC	String	위치 참조를 위한 AGORA-C encoded code
segmentCoordinates	Object	segment nodes 에 대한 GPS 좌표 제공 (양 끝 노드)
point1	Object	node 1 에 대한 GPS 좌표 컨테이너
lat	String	node 1 에 대한 GPS 위도
lon	String	node 1 에 대한 GPS 경도
point2	Object	node 2 에 대한 GPS 좌표 컨테이너
lat	String	node 2 에 대한 GPS 위도
lon	String	node 2 에 대한 GPS 경도
timeStamp	Datetime	정보 생성 시간

6.2.2.3. Request/Response Example¶

RUUT API Incident 요청/응답 예제 를 참고 하시기 바랍니다.

6.3. V2X¶

RUUT 는 T Map 에서 서비스 되고 있는 V2X 서비스 (응급 차량 출동 알림, 전방 급정거 알림) 및 기타 V2X 서비스의 원시 데이터를 제공 합니다. V2X 데이터는 webhook 방식으로 제공 됩니다.

Header

option	Type	Default	Description
X-Authorization	string	{accessToken}	API Key

6.3.1. V2X Webhook 관리¶

V2X 서비스 데이터를 획득 하려면 각 서비스의 유형에 맞는 Webhook URL 을 등록 합니다. 사용자는 Webhook URL의 등록/조회/삭제를 수행할 수 있습니다.

6.3.1.1. Webhook URL 등록¶

POST

/ruut/{version}/hooks

Request Body

Type	key	Value	Description
String	url	hook_url	V2X webhook 을 수신할 URL
String	locationReference	openLR	위치 참조 타입 openLR 명시
		agoraC	위치 참조 타입 AGORA-C 명시
		segmentID	위치 참조 타입 Segment ID 명시 (RUUT 자체 타입)
String List	events	emergencyVehicle	응급 차량 알림 메시지 수신
		otherEvents	급정거 알림 및 기타 알림 메시지 수신

Request Example

{
  "url":"http://v2xhook.test",
  "locationReference":"openLR",
  "events": [
    "emergencyVehicle", "otherEvents"
  ]
}

6.3.1.2. Webhook URL 조회¶

Header 를 통해 권한 인증 후 해당 사용자가 등록한 Hook URL 을 반환합니다.

GET

/ruut/{version}/hooks

6.3.1.3. Webhook URL 삭제¶

Header 를 통해 권한 인증 후 해당 사용자가 등록한 Hook URL 을 삭제합니다.

DELETE

/ruut/{version}/hooks

6.3.2. V2X Incoming Webhook 명세¶

V2X 이벤트가 발생하면 사용자가 등록한 Webhook URL로 Webhook 이 전송 됩니다. 해당 Incoming Webhook 은 3가지 종류로 구분됩니다.

응급 차량 이동 알림
응급 차량 목적지 (재난지) 정보 알림
급정거 알림 및 기타 V2X 이벤트 알림

6.3.2.1. 응급 차량 목적지 (재난지) 정보 알림¶

Webhook Payload Elements

Property	Type	Description
dsrID	String	재난 정보 ID
provider	String	재난 정보 제공자
dsrType	String	재난 유형
startTime	String	재난 발생 시간
endTime	String	재난 종료 시간
locationReference	String	재난 위치의 위치 참조 코드 (openLR, AGORA-C, segment ID 중 택일)
locationOfDisaster	String	재난 위치 GPS 정보 배열
lat	String	재난 위치 위도
lon	String	재난 위치 경도
timeStamp	String	정보 생성 시간

Webhook Payload Example

{
  "dsrID": "h4dkdeekd3",
  "provider" : "소방 방재청",
  "disasterType": "사고",
  "startTime" : "20200116081953",
  "endTime" : "",
  "locationReference" : "C1pkKRqXySOPAAAA//IjDw==",
  "locationOfDisaster": {
    "lat": "37.396133",
    "lon": "127.112698"
  },
  "timestamp": "2020-01-16 19:59:00"
}

6.3.2.2. 응급 차량 이동 알림¶

Webhook Payload Elements

Property	Type	Description
plateNumber	String	응급 출동 차량 번호
dsrID	String	재난 정보 ID
distToDsr	String	응급 출동 차량으로부터 재난지 까지의 잔여 거리
locationReference	String	응급 출동 차량 위치 참조 코드 (openLR, AGORA-C, segment ID 중 택일)
locationOfDisaster	String	응급 출동 차량 GPS 정보 배열
lat	String	응급 출동 차량 위도
lon	String	응급 출동 차량 경도
timeStamp	String	정보 생성 시간

Webhook Payload Example

{
  "plateNumber" : "73무8261",
  "dsrID": "UO4409579157",
  "distToDsr" : "21844",
  "locationReference" : "d1pkKRqXySOPAAAA//IjDw==",
  "locationOfDisaster": {
    "lat": "37.396133",
    "lon": "127.112698"
  },
  "timestamp": "2020-01-16 19:59:00"
}

6.3.2.3. 급정거 알림 및 기타 V2X 이벤트 알림¶

Webhook Payload Elements

Note

본 메시지는 eventType 에 따라 구분 됩니다.

0 : 급정거
258 : 정체
513 : 사고
534 : 정지차
1281 : 낙하물
1286 : 보행자

Property	Type	Description
eventId	String	이벤트 ID
eventType	String	이벤트 유형
tunnelYn	String	이벤트 발생 위치가 터널인지 여부
roadType	String	이벤트 발생 위치의 도로 유형
locationReference	String	이벤트 위치 참조 코드 (openLR, AGORA-C, segment ID 중 택일)
locationOfDisaster	String	이벤트 위치 GPS 정보 배열
lat	String	이벤트 위치 위도
lon	String	이벤트 위치 경도
timeStamp	String	정보 생성 시간

Webhook Payload Example

{
  "eventId": "4djakdjk2ddk2",
  "eventType": "0",
  "tunnelYn" : "N",
  "roadType" : "0",
   "locationReference" : "d1pkKRqXySOPAAAA//IjDw==",
   "locationOfDisaster": {
     "lat": "37.396133",
     "lon": "127.112698"
   },
   "timestamp": "2020-01-16 19:59:00"
}

6.4. RUUT TPEG¶

RUUT는 자체적으로 TPEG2 표준에 맞는 교통 데이터를 제공하고 있습니다. TPEG2는 기존 TPEG 대비하여 제공 데이터의 정밀도 향상, 교통 정보 범위 확대, 차선 단위 교통정보 제공 기능 추가, 예측 교통 정보 제공을 위한 포맷 강화, Peer to Peer 연동 규격 추가 등을 제공하는 최신 교통 정보 제공 국제 표준입니다. RUUT TPEG2 는 TPEG2 어플리케이션 중 아래 3가지 어플리케이션을 제공합니다.

TFP : 실시간 교통 정보
TEC : 실시간 이벤트(돌발) 정보
WEA : 날씨 정보

6.4.1. TPEG2¶

TPEG2 Request

GET

/ruut/{version}/tpeg/getMessage?{geo-query}?{set of parameters}

RUUT TPEG 메시지에 대한 요청은 위와 같은 URL로 구성 됩니다. 앞서 언급한 바와 같이 goe filter 를 먼저 URL 에 추가한 후 아래 Request Parameters 를 추가 입력하면 됩니다.

6.4.1.1. Request Parameters (TPEG2)¶

Params	Type	Value	Description
frc	Integer	frc	FRC 등급이 같은 항목만 반환 (쉼표 나누어 여러 개의 등급 명시 가능)
		all (default)	모든 FRC 등급 데이터 반환
format	String	base64xml (default)	TPEG 메시지를 base64 로 인코딩 한 후 xml 컨테이너로 반환
		tepgML	TPEG 메시지를 TPEG-ML 로 반환
app	String	tfp (default)	TPEG2 TFP 어플리케이션 반환
		tec	TEPG2 TEC 어플리케이션 반환
		wea	TEPG2 WEA 어플리케이션 반환
delta	String	on	이전 요청에서 변경된 데이터만 반환 (델타 업데이트)
		off	매 요청 시 모든 세그먼트 데이터 반환 (전체 업데이트)

6.4.1.2. Response Formats (TPEG2)¶

TEPG2 요청에 대한 응답은 2 가지 형태로 제공 됩니다.

TPEG2 Message Binary (Base64 Encoding 후 XML 전송)
TPEG2 ML (TPEG proprietary ML)

각 응답 포맷에 대한 세부 사항은 TPEG2 표준 문서를 참고 하시기 바랍니다.

6.4.1.3. Request/Response Example¶

TFP 요청 응답 예제, TEC 요청 응답 예제, WEA 요청 응답 예제, TPEG 조합 요청 응답 예제 를 참고 하시기 바랍니다.

6.5. Errors¶

RUUT API 호출 중 발생하는 에러 코드에 대한 안내

코드	메시지	HTTP Response
ER40001	Invalid inputs (parameters, formats, …)	400
ER40101	Authorization failure	401
ER42901	Too many requests	429
ER99999	System errors	500

[1]	행정 구역 코드는 별도로 안내.