해당 API는 선박의 UUID(shipId)와 조회 기간(시작일, 종료일)을 입력하여, 지정한 기간 동안의 입출항 이력을 반환합니다. AIS 데이터를 기반으로 평균 약 15분 단위로 업데이트됩니다.
1. 인증 방법
Port Call API는 사용자 인증을 위해 Swagger UI에서 Basic Authorize 인증 방식을 제공합니다.
인증 절차는 다음과 같습니다:
1.
우측 상단의 [Authorize] 버튼을 클릭합니다.
2.
팝업 창에 제공받은 인증 정보(아이디, 비밀번호)를 입력합니다.
3.
입력 후 다시 [Authorize] 버튼을 클릭하여 인증을 진행합니다.
4.
인증이 완료되면 [Close] 버튼을 클릭하여 인증 창을 닫습니다.
Swagger UI에서 호출되는 모든 API 요청에 인증 토큰이 자동으로 포함되어 전송됩니다.
2. 요청 정보
2-1. 요청 정보
Request URL : [GET] https://insight.seavantage.com/api/port-call/{shipId}
2-2. 실행 순서
1.
2.
/port-call/{shipId} 경로로 이동
3.
[Try it out] 클릭 → 입력창 활성화
4.
아래 요청 Parameters 조건에 따라 결과 반환
•
•
from : 선박의 이동 경로 시작 날짜이며, 형식은 UTC 형식의 데이터
ex) 2025-01-01T00:00:00Z
•
to : 선박의 이동 경로 종료 날짜이며, 형식은 UTC 형식의 데이터
ex) 2025-02-01T23:59:59Z
5.
[Execute] 버튼 클릭
6.
하단 응답 영역에서 등록 결과 확인
3. 응답 정보
응답 예시
{
"code": 200,
"message": "OK",
"error": false,
"timestamp": "2024-12-01T12:00:00",
"response": [
{
"departurePort": {
"portId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"portName": "Busan",
"unlocode": "KRPUS",
"nationCode": "KR",
"latitude": 35.1796,
"longitude": 129.0756,
"timezone": "+09:00",
"geoData": "{\"type\":\"Polygon\",\"coordinates\":[126.491341,33.499621]}"
},
"arrivalPort": {
"portId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"portName": "Busan",
"unlocode": "KRPUS",
"nationCode": "KR",
"latitude": 35.1796,
"longitude": 129.0756,
"timezone": "+09:00",
"geoData": "{\"type\":\"Polygon\",\"coordinates\":[126.491341,33.499621]}"
},
"atd": "2025-08-04T05:31:38.160Z",
"ata": "2025-08-04T05:31:38.160Z",
"atb": "2025-08-04T05:31:38.160Z",
"atSeaHour": 10.5,
"atSeaDistance": 100,
"inPortHour": 5,
"inPortDistance": 50,
"ecaDistance": 20
}
]
}
JSON
복사
응답 필드 상세 설명
응답 항목별 정의
필드명 | 예시 값 | 설명 |
code | 200 | 응답 상태 코드 (HTTP status code와 동일하게 사용됨)
(아래 별도 응답 코드표 참조) |
message | success | 응답 메시지 (상태에 따른 설명) |
error | false | 오류 여부
(true: 오류 발생, false: 정상 처리) |
timestamp | 2025-05-14T01:09:00.834665213 | 응답 생성 시각 (UTC 기준) |
response | 배열 또는 빈배열 | 포트콜 존재시 배열, 미존재 시 빈배열 |
응답 코드 종류
코드 | 설명 |
200 | 정상 처리 (Success) |
400 | 잘못된 파라미터 (Bad Request) |
401 | 인증 필요 (Unauthorized) |
403 | 권한 없음 (Forbidden) |
422 | 처리 불가 (Unprocessable Entity) |
429 | 요청 과다 (Too Many Requests) |
응답 상세 설명
Depth 1 필드 설명 (response 객체)
필드명 | 예시 값 | 설명 | 데이터 타입 |
atd | 2025-05-13T09:32:29.460Z | Actual Time of Departure | timestamp |
ata | 2025-05-13T09:32:29.460Z | Actual Time of Arrival | timestamp |
atb | 2025-05-13T09:32:29.460Z | Actual Time of Berthing | timestamp |
atSeaHour | 177.75 | 항구 간 해상에서 이동한 총 항해 시간 | double precision |
atSeaDistance | 870.385 | 항구 간 해상에서 이동한 총 이동 거리 | double precision |
inPortHour | 78.75 | 항구 내 이동 시간 | double precision |
inPortDistance | 7.0155673 | 항구 내 이동 거리 | double precision |
ecaDistance | 0 | ECA(배출규제해역) 포함 이동 거리 | double precision |
departurePort | [object Object] | Depth 2 → departurePort, arrivalPort 객체 참고 | |
arrivalPort | [object Object] | Depth 2 → departurePort, arrivalPort 객체 참고 |
Depth 2 필드 설명 (departurePort, arrivalPort 객체)
필드명 | 예시 값 | 설명 | 데이터 타입 |
portId | 3fa85f64-5717-4562-b3fc-2c963f66afa6 | 내부적으로 사용하는 port 구분 값 | varchar(36) - UUID |
portName | Lake Charles | 항구명 | varchar(255) |
unlocode | USLCH | 항구 UNLOCODE | varchar(36) |
nationCode | US | 국가 코드 | varchar(36) |
latitude | 30.16705757 | 위도 | double precision |
longitude | -93.28987508 | 경도 | double precision |
timezone | -06:00 | 항구 타임존 | varchar(36) |
geoData | {\"type\":\"Polygon\",\"coordinates\":[[[-93.245241209,30.235700469],[-93.239001696,30.219920273],[-93.274622474,30.101477518],[-93.32514921,30.101209342],[-93.337327325,30.143453744],[-93.337338055,30.171193622],[-93.283388298,30.2346084],[-93.245241209,30.235700469]]]} | 항구 구역 GeoData | text |