3. RUUT 서비스 가이드¶

RUUT 의 모든 서비스는 REST API 호출 기반으로 이루어져 있습니다. 전체적인 서비스 사용 절차는 아래 그림과 같습니다.

3.1. 인증 (공통 프로세스)¶

3.1.1. 계정 생성¶

API 호출을 통해 로그인을 수행하고 접근 권한을 담은 token 을 부여 받습니다.

POST

/api/auth/v1/join

Header

option	Type	Default	Description
Content-Type	string	application/json	content type

Body

Key	Type	Description
username	String	사용자 ID
password	String	패스워드
email	String	사용자 이메일 주소
phone	String	휴대폰 번호 (01x-xxxx-xxxx)

Example Code

Request

content-type:"application/json"

{
    "username":"example",
    "password":"1234",
    "email":"example@mail.com",
    "phone":"010-0000-0000"
}

Response (code: 200)

별도 응답 body 없음

3.1.2. 로그인 (인증 토큰 획득)¶

API 호출을 통해 계정을 생성 합니다.

POST

/api/auth/v1/login

Header

option	Type	Default	Description
Content-Type	string	application/json	content type

Body

Key	Type	Description
username	String	사용자 ID
password	String	패스워드

Example Code

Request

content-type:"application/json"

{
    "username":"example",
    "password":"1234",
}

Response (code: 200)

{
    "token":"eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJzeXNhZG1pbkB0aG…",
    "refreshToken": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJzeXNhZG1…"
}

3.1.3. 토큰 갱신¶

API 호출을 통해 만료된 인증 토큰을 갱신 합니다.

POST

/api/auth/v1/token

Header

option	Type	Default	Description
Content-Type	string	application/json	content type

Body

Key	Type	Description
refreshToken	String	갱신 토큰 정보

Example Code

Request

content-type:"application/json"

{
    "refreshToken": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJzeXNhZG1…"
}

Response (code: 200)

{
    "token":"eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJzeXNhZG1pbkB0aG…",
    "refreshToken": "yJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJdWIiO…"
}

3.1.4. 패스워드 변경¶

API 호출을 통해 패스워드를 변경 합니다.

POST

/api/auth/v1/changePassword

Header

option	Type	Default	Description
Content-Type	string	application/json	content type

Body

Key	Type	Description
password	String	기존 패스워드
newPasswrod	String	변경할 패스워드

Example Code

Request

content-type:"application/json"

 {
    "passwrod":"1234",
    "newPassword":"5678",
}

Response (code: 200)

별도 응답 body 없음

3.1.5. 패스워드 리셋 (이메일 연동)¶

API 호출을 통해 패스워드를 변경 합니다.

POST

/api/auth/v1/resetPasswordByEmail

Header

option	Type	Default	Description
Content-Type	string	application/json	content type

Body

Key	Type	Description
email	String	회원 정보에 등록된 메일 주소

Example Code

Request

content-type:"application/json"

{
    "email":"example@mail.com"
}

Response (code: 200)

{
    "password": "WEx8Ekp1rT"
}

3.2. RUUT 고유 API 활용¶

RUUT 고유 API 는 JSON 형태로 실시간 교통 정보, 돌발 (사고 및 이벤트) 정보, V2X 서비스 구독, 예측 교통 정보 (비공개), 도로 위험도 정보 제공 (2020년 4분기 예정) 등의 기능을 제공하고 있습니다. 앞서 인증 과정에서 발급받은 API 접근 키 API 헤더에 포함 시킨 후 API규격 에 따라 원하는 정보를 요청 하시면 됩니다.

Header

option	Type	Default	Description
Content-Type	string	application/json	content type
X-Authorization	string	{accessToken}	API Key

3.2.1. 실시간 교통 정보¶

실시간 교통 정보를 획득 하려면 API URL 에 하기 항목을 명시하셔야 합니다.

예) 특정 지역 중심 반경 1km 원형 영역 내 모든 실시간 교통 정보를 openLR 위치 참조 형태로 요청

Geo filtering 교통 정보 탐색하고자 하는 지리적 영역 규정 (geoFilter)
획득 하고자 하는 정보의 유형 및 카테고리 선택 (rttiField, lane)
위치 참조 방식 선택 (lr)

Request Example

// 원형 geo filter 반경 1km, 모든 교통 정보 표출, 위치 참조 openLr
ruut/v1/segments?geoFilter=circle&center=37.397619,127.112465&radius=1&incidentField=all
&lr=openLr

Response Example

{
  "segments": [
      {
          "segmentId": "1020245101",
          "roadCategory": "1",
          "speed": "27",
          "limit": "70",
          "freeFlow": "70",
          "travelTime": "43",
          "openLr": "C1pllBqXeQ4wBf/X/tQOEQ==",
          "linkId": "10202451",
          "segmentCoordinates": {
              "point1": {
                  "lat": "37.394568",
                  "lon": "127.120485"
              },
              "point2": {
                  "lat": "37.391561",
                  "lon": "127.120067"
              }
          },
          "timeStamp": "2020-03-03 13:19:00"
      },
      ...

3.2.2. 돌발 정보 (이벤트, 사고)¶

돌발 정보를 획득 하려면 API URL 에 하기 항목을 명시하셔야 합니다.

예) 특정 지역 중심 반경 1km 원형 영역 내 모든 돌발 정보를 openLR 위치 참조 형태로 요청

Geo filtering 돌발 정보 탐색하고자 하는 지리적 영역 규정 (geoFilter)
획득 하고자 하는 정보의 유형 및 카테고리 선택 (incidentField, type)
위치 참조 방식 선택 (lr)

Request Example

ruut/v1/incidents?geoFilter=circle&center=37.397619,127.112465&radius=1
&incidentField=all&type=all&lr=all

Response Example

{
  "incidents": [
      {
          "segmentId": "209699101",
          "incidentId": "L93105264991",
          "incidentType": "B",
          "lane": "00",
          "length": 83,
          "vehicleKind": "000000",
          "description": "<경찰청제공>[공사] 세계로 삼평중삼거리 에서 사송사거리 방향 1차로 도로공사 주의운전",
          "schedule": {
              "isPlanned": "",
              "startTime": "202003030806",
              "endTime": "202003031800",
              "reoccuring": {
                  "daysOfWeek": "",
                  "from": "",
                  "until": ""
              }
          },
          "openLr": "C1pk5xqYcSugCP/FAb0rHA==",
          "linkId": "2096991",
          "segmentCoordinates": {
              "point1": {
                  "lat": "37.399888",
                  "lon": "127.116777"
              },
              "point2": {
                  "lat": "37.404339",
                  "lon": "127.11618"
              }
          },
          "timeStamp": "2020-03-03 13:15:00"
      },
      ...

3.3. V2X 서비스 연동 요청¶

3.3.1. Webhook URL 등록 작업¶

V2X 서비스 메시지를 획득 하려면 원하는 V2X 서비스의 유형과 webhook 이 인입될 URL을 입력하여야 합니다.

예) 응급 차량 출동 알림 V2X 서비스를 https://myserverurl.net 에서 수신하기를 요청

Header 에 사용자 인증 정보 포함
Webhook 연동할 서비스명 설정
Webhook 인입될 URL 명시 (unreachable 상태가 지속될 경우 무통보 삭제합니다)

Request Example

POST root/v1/hooks
header : X-Authorization

Body :
{
  "url":"https://myserverurl.net",
  "locationReference":"openLR",
  "events": [
    "emergencyVehicle"
  ]
}

서비스 안정성 확보를 위하여 별도 권한을 획득하지 않은 사용자의 V2X Webhook URL 은 매일 자정에 삭제 됩니다.

3.3.2. Incoming Webhook¶

세부 정보는 V2X 서비스 Incoming Webhook 명세 을 참고하시기 바랍니다.

3.4. 도로 위험 점수 획득¶

‘20년 2분기 제공 예정

3.4.1. 예측 교통 정보 (비공개)¶

별도 계약 필요 (관리자 문의)

3.5. 과거 교통 정보 요청¶

별도 계약 필요 (관리자 문의)