Route API는 선박의 항구 간 이동 경로 또는 현재 위치에서 특정 항구까지의 예상 항로를 예측하는 기능을 제공합니다.
요청 방식
•
HTTP Method : POST
•
API 경로 : /weather/forecast/{date}
•
호출 주기 제한 : 없음
•
응답 포맷 : JSON
•
인증 방식 : Basic Auth
인증 방법
Swagger UI를 통해 Route API를 호출할 때는 아래 인증 절차를 따릅니다:
1.
Swagger 상단 우측의 [Authorize] 버튼 클릭
2.
인증 정보(ID, PW) 입력
3.
[Authorize] 클릭
4.
인증 후 [Close] 클릭
이후 실행되는 모든 API 요청은 인증 토큰이 자동 포함되어 전송됩니다.
항로 정보 조회 방법
1. Swagger UI 호출 절차
1.
Swagger 문서에서 Route 정의 선택
2.
/route 경로로 이동
3.
[Try it out] 클릭
4.
Request Body 입력
5.
[Execute] 클릭
6.
응답 정보 확인
2. Request Body 예시
{
"startDateTime": "2025-05-13T15:59:50Z",
"shipTypeBySize": "CONTAINER03",
"routeMethod": "frequency",
"debug": false,
"maxSpeed": 17,
"options": {
"eca": 2,
"hra": 2,
"jwc": 2,
"cyclone": 2,
"avoid": [],
"frequencyPercentage": 50,
"speedType": "top",
"validAreaAngle": 0,
"startNodeCount": 5
},
"wayPoints": [
{
"no": 1,
"name": "",
"latitude": 27.21312,
"longitude": 123.92757333,
"seaStayHours": 0,
"portStayHours": 0
},
{
"no": 2,
"name": "",
"latitude": -3.14774258,
"longitude": -59.95599844,
"seaStayHours": 0,
"portStayHours": 0
}
]
}
JSON
복사
주요 요청 필드 설명
Depth 1필드명 | 예시 값 | 설명 |
startDateTime | 2025-05-13T15:59:50Z | 출발 시간 (UTC) |
shipTypeBySize | CONTAINER03 | 선박 타입 및 크기 |
routeMethod | frequency | distance, time, frequency 중 선택 |
debug | false | 디버그 옵션 |
maxSpeed | 17 | 최대 속도 (knot) |
Depth 2 – options 객체필드명 | 예시 값 | 설명 |
eca | 2 | 배출 규제 구역 설정 (1~3) |
hra | 2 | 고위험 지역 설정 (1~3) |
jwc | 2 | 전쟁 위험 지역 설정 (1~3) |
cyclone | 2 | 태풍 구역 설정 (1~3) |
avoid | [] | 회피 운하 목록 (0=수에즈, 1=파나마 등) |
frequencyPercentage | 50 | 빈도 기반 적용 비율 (%) |
speedType | top | 속도 유형: top, average, upper10, lower10 |
validAreaAngle | 0 | 회전 각도 허용 |
startNodeCount | 5 | 초기 경로 노드 수 |
Depth 3 – wayPoints 배열필드명 | 예시 값 | 설명 |
no | 1 | 순번 |
latitude | 27.21312 | 위도 |
longitude | 123.92757333 | 경도 |
seaStayHours | 0 | 해상 체류 시간 |
portStayHours | 0 | 항구 체류 시간 |
응답 정보
응답 형식 예시
{
"code": 200,
"message": "OK",
"error": false,
"timestamp": "2025-05-19T15:47:59.950411",
"response": {
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "LineString",
"coordinates": [
[121.295939, 36.0]
]
},
"properties": {
"startNo": 1,
"startName": "",
"arrivalNo": 2,
"arrivalName": "",
"distance": 13140.17,
"courseHours": 1059.25,
"seaStayHours": 0.0,
"portStayHours": 0.0,
"maxSpeed": 15.8793,
"distanceEca": 0.0,
"distanceHra": 0.0,
"distanceJwc": 0.0,
"atNoonPoints": [
{
"dateTime": "2025-05-14T12:00:00Z",
"latitude": 32.7124,
"longitude": 122.1457
}
]
}
}
]
}
}
JSON
복사
응답 필드 상세
필드명 | 예시 | 설명 |
code | 200 | 응답 상태 코드 |
message | OK | 응답 메시지 |
error | false | 오류 여부 |
timestamp | 2025-05-19T15:47:59 | 응답 생성 시각 |
geometry 객체
필드명 | 예시 | 설명 |
type | LineString | 경로 타입 |
coordinates | [121.29, 36.0] | 경로 좌표 배열 |
properties 객체
필드명 | 예시 | 설명 |
startNo | 1 | 출발지 번호 |
startName | "" | 출발지 명 |
arrivalNo | 2 | 도착지 번호 |
arrivalName | "" | 도착지 명 |
distance | 13140.17 | 총 거리 (해리) |
courseHours | 1059.25 | 항해 시간 (시간) |
seaStayHours | 0.0 | 해상 체류 시간 |
portStayHours | 0.0 | 항구 체류 시간 |
maxSpeed | 15.8793 | 최대 속도 |
distanceEca | 0.0 | ECA 통과 거리 |
distanceHra | 0.0 | HRA 통과 거리 |
distanceJwc | 0.0 | JWC 통과 거리 |
atNoonPoints 배열
필드명 | 예시 | 설명 |
dateTime | 2025-05-14T12:00:00Z | 기준 시각 (UTC) |
latitude | 32.7124 | 위도 |
longitude | 122.1457 | 경도 |
응답 코드 안내
코드 | 설명 |
200 | 정상 처리 |
201 | 리소스 생성 |
400 | 잘못된 요청 |
401 | 인증 실패 |
403 | 권한 없음 |
422 | 처리 불가 |
429 | 요청 과다 |