해당 API는 IMO 번호와 항구 portId를 입력하여 선박의 현재 위치부터 지정한 항구까지의 예상 항적과 PTA(예상 도착 시각)를 반환합니다.
인증 방법
Past Track API는 사용자 인증을 위해 Swagger UI에서 Basic Authorize 인증 방식을 제공합니다.
인증 절차는 다음과 같습니다:
1.
우측 상단의 [Authorize] 버튼을 클릭합니다.
2.
팝업 창에 제공받은 인증 정보(아이디, 비밀번호)를 입력합니다.
3.
입력 후 다시 [Authorize] 버튼을 클릭하여 인증을 진행합니다.
4.
인증이 완료되면 [Close] 버튼을 클릭하여 인증 창을 닫습니다.
Swagger UI에서 호출되는 모든 API 요청에 인증 토큰이 자동으로 포함되어 전송됩니다.
요청 정보
요청 정보
Request URL : [POST] https://insight.seavantage.com/api/route/ship-to-port
실행 순서
1.
2.
/route/ship-to-port 경로로 이동합니다.
3.
[Try it out] 버튼을 클릭하여 입력창을 활성화합니다.
4.
아래 요청 Parameters 조건에 따라 입력합니다.
•
imoNo : 라우팅을 예측할 선박의 IMO번호 입력
•
portId : SeaVantage에서 발급한 고유 항구 식별자(Port ID)
•
Request body : routing option을 입력하면 해당 옵션에 따라 라우팅이 예측되며, 입력하지 않은 경우 기본 설정값으로 대체되어 라우팅 예측
5.
[Execute] 버튼을 클릭합니다.
6.
하단 응답 영역에서 등록 결과를 확인합니다.
Request body 예시
{
"routeMethod": "frequency",
"maxSpeed": 17,
"options": {
"eca": 2,
"hra": 2,
"jwc": 1,
"cyclone": 2,
"avoid": [],
"frequencyPercentage": 45,
"speedType": "upper10"
}
}
JavaScript
복사
필드 설명
•
routeMethod: 라우팅 설정 기준
◦
distance: 최단 거리 우선
◦
time: 최단 시간 우선
◦
frequency: 최대 빈도 우선
•
maxSpeed: 최대 속도 (knot 단위)
•
options.eca: 배출 규제 구역(ECA) 옵션
1.
구역 내 최단거리 이동
2.
무시하고 이동
3.
회피하여 이동
•
options.hra: 고위험 지역(HRA) 옵션
1.
구역 내 최단거리 이동
2.
무시하고 이동
3.
회피하여 이동
•
options.jwc: 전쟁 위험 지역(JWC) 옵션
1.
구역 내 최단거리 이동
2.
무시하고 이동
3.
회피하여 이동
•
options.cyclone: 태풍 옵션
1.
구역 내 최단거리 이동
2.
무시하고 이동
3.
회피하여 이동
•
options.avoid: 회피 운하 선택
◦
88f3f52e-2b8a-11e9-8abd-54802853d888: 수에즈 운하
◦
3f298f0e-2b89-11e9-8abd-54802853d888: 파나마 운하
◦
7addce3a-5927-11ea-87d0-54802853d888: 키엘 운하
•
options.frequencyPercentage: 빈도 기반 경로 탐색 시 적용 비율
•
options.speedType: 속도 설정
◦
top: 최고 속도
◦
average: 평균 속도
◦
upper10: 상위 10% 속도
◦
lower10: 하위 10% 속도
응답 정보
응답 예시
{
"code": 200,
"message": "OK",
"error": false,
"timestamp": "2025-08-04T05:47:30.441096649",
"response": {
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"coordinates": [
[
126.491341,
33.499621
],
[
126.491341,
33.499621
]
],
"type": "LineString",
"emptyCoordinate": false
},
"properties": {
"distanceHra": 100,
"atNoonPoints": [
{
"dateTime": "2025-03-01T23:59:59Z",
"longitude": 80,
"latitude": 80
}
],
"startDateTime": "2025-03-01T23:59:59Z",
"hours": 10,
"portStayHours": 2,
"arrivalName": "arrival name",
"startNo": 1,
"distance": 100,
"startName": "start name",ss
"maxSpeed": 20,
"seaStayHours": 2,
"arrivalDateTime": "2025-03-01T23:59:59Z",
"courseHours": 10,
"distanceEca": 100,
"planPoints": [
{
"speed": 0,
"dateTime": "2025-03-01T23:59:59Z",
"longitude": 80,
"latitude": 80,
"eca": false
}
],
"distanceJwc": 100,
"arrivalNo": 1
}
}
]
}
}
JSON
복사
응답 필드 상세 설명
응답 항목별 정의
필드명 | 예시 값 | 설명 |
code | 200 | 응답 상태 코드 (HTTP status code와 동일하게 사용됨)
(아래 별도 응답 상태 코드표 참조) |
message | success | 응답 메시지 (상태에 따른 설명) |
error | false | 오류 여부
true: 오류 발생
false: 정상 처리 |
timestamp | 2025-05-14T01:09:00.834665213 | 응답 생성 시각 (UTC 기준) |
response | Object | 예상 항적 존재시 Object 반환 |
응답 코드 종류
코드 | 설명 |
200 | 정상 처리 (Success) |
400 | 잘못된 파라미터 (Bad request) |
401 | 인증 필요 (Unauthorized) |
403 | 권한 없음 (Forbidden) |
422 | 처리 불가 (Unprocessable entity) |
429 | 요청 과다 (Too many requests) |
응답 객체 상세 설명
Depth 1 필드 설명 (geometry 객체)
geojson을 반환합니다.
필드명 | 예시 값 | 설명 | 데이터 타입 |
type | Feature | 선의 유형 | varchar |
coordinates | [126.491341, 33.499621], [126.491341, 33.499621] | 항로 좌표점 목록 | double precision |
emptyCoordinate | false | boolean |
Depth 2 필드 설명 (properties 객체)
geojson의 속성값을 반환합니다.
필드명 | 예시 값 | 설명 | 데이터 타입 |
startDateTime | 2025-03-01T23:59:59Z | 출발 시간
(선박 위치 정보 마지막 수신 시간) | timestamp |
hours | 10 | 총 걸린 시간 | double precision |
portStayHours | 0.0 | 항구에서 머무는 시간 | double precision |
arrivalName | dc822048-5534-11e9-a747-54802853d888 | 도착 지점 항구 portId | varchar |
startNo | 1 | 출발 지점 Way Point 번호 | integer |
distance | 100 | 거리 | double precision |
startName | 1234567 | 출발 지점 선박 IMO | varchar |
maxSpeed | 17 | 대상 속도 (knot) | double precision |
seaStayHours | 0.0 | 해상에서 머무는 시간 | double precision |
arrivalDateTime | 2025-05-01T23:59:59Z | PTA (예상 도착 시간) | timestamp |
courseHours | 10 | 출발지 ~ 도착지 항해 시간 | double precision |
distanceEca | 0.0 | 배출 규제 구역 통과 거리 | double precision |
distanceHra | 0.0 | 고위험 지역 통과 거리 | double precision |
distanceJwc | 0.0 | 전쟁 위험 지역 통과 거리 | double precision |
arrivalNo | 1 | 도착 지점 Way Point 번호 | integer |
Depth 3 필드 설명 (planPoints 객체)
예상 항적의 구간별 평균 스피드와 함께 ECA, HRA, JWC에 위치해있는지를 함께 반환합니다.
필드명 | 예시 값 | 설명 | 데이터 타입 |
speed | 0 | 속도 (knot) | integer |
dateTime | 2025-03-01T23:59:59Z | 예상 시간 | timestamp |
longitude | 80 | 경도 | double precision |
latitude | 80 | 위도 | double precision |
eca | false | ECA에 위치 여부 | boolean |
hra | false | HRA에 위치 여부 | boolean |
jwc | false | JWC에 위치 여부 | boolean |
Depth 4 필드 설명 (atNoonPoints 객체)
예상 항적의 정오 시간 기준의 위치정보 및 PTA를 반환합니다.
필드명 | 예시 값 | 설명 | 데이터 타입 |
dateTime | 2025-03-01T12:00:00Z | 정오 시간 | timestamp |
longitude | 80 | 경도 | double precision |
latitude | 80 | 위도 | double precision |