터미널 기준으로 Port Insight의 주요 운영 현황을 조회할 수 있는 API입니다. AIS 데이터를 기반으로 평균 약 15분 단위로 업데이트 됩니다. 터미널을 선택하지 않을 경우 항구 기준으로 운영 현황을 확인 할 수 있습니다.
인증 방법
Port Insight Overview API는 사용자 인증을 위해 Swagger UI에서 Basic Authorize 인증 방식을 제공합니다.
인증 절차는 다음과 같습니다:
1.
우측 상단의 [Authorize] 버튼을 클릭합니다.
2.
팝업 창에 제공받은 인증 정보(아이디, 비밀번호)를 입력합니다.
3.
입력 후 다시 [Authorize] 버튼을 클릭하여 인증을 진행합니다.
4.
인증이 완료되면 [Close] 버튼을 클릭하여 인증 창을 닫습니다.
Swagger UI에서 호출되는 모든 API 요청에 인증 토큰이 자동으로 포함되어 전송됩니다.
요청 정보
요청 정보
Request URL : [GET] https://insight.seavantage.com/api/port-insight/overview/terminals
실행 순서
1.
2.
/port-insight/overview/terminals 경로로 이동합니다.
3.
[Try it out] 버튼을 클릭하여 입력창을 활성화합니다.
4.
아래 요청 Parameters 조건에 따라 결과가 반환됩니다.
•
•
terminalIds (선택)
◦
SeaVantage에서 발급한 고유 터미널 식별자(Terminal ID)
◦
[GET] /port/terminal API를 통해 terminal ID 확인 가능
5.
[Execute] 버튼 클릭합니다.
6.
응답 영역에서 등록 결과를 확인합니다.
응답 정보
요청이 성공하거나 실패했을 때 공통적으로 아래와 같은 형식으로 응답이 반환됩니다.
응답 예시
{
"code": 200,
"message": "OK",
"error": false,
"timestamp": "2026-04-03T05:26:17.933656333",
"response": {
"congestionIndex": 5,
"waitingShipCount": 36,
"avgWaitingDays": 2.2,
"workingShipCount": 77,
"avgWorkingDays": 1.8,
"avgIdleTimeHours": 5.2,
"onTheWayShipCount": 453
}
}
JavaScript
복사
응답 필드 상세 설명
응답 항목별 정의
필드명 | 예시 값 | 설명 |
code | 200 | 응답 상태 코드 (HTTP status code와 동일하게 사용됨)
(아래 별도 응답 상태 코드표 참조) |
message | OK | 응답 메시지 (상태에 따른 설명) |
error | false | 오류 여부
true: 오류 발생
false: 정상 처리 |
timestamp | 2026-04-03T05:26:17.933656333 | 응답 생성 시각 (UTC 기준) |
response | 배열 또는 빈배열 | 물동량 존재시 배열, 미존재 시 빈배열 |
응답 코드 종류
코드 | 설명 |
200 | 정상 처리 (Success) |
400 | 잘못된 파라미터 (Bad request) |
401 | 인증 필요 (Unauthorized) |
403 | 권한 없음 (Forbidden) |
422 | 처리 불가 (Unprocessable entity) |
429 | 요청 과다 (Too many requests, 분당 100회 초과 호출 시 발생) |
응답 상세 설명
Depth 1 필드 설명 (response 객체)
필드명 | 예시 값 | 설명 | 데이터 타입 |
congestionIndex | 5 | 과거 대비 현재 혼잡도 (1~10구간으로 수치화한 지표)
1-2구간 : 지연이 거의 없거나 매우 원활한 상태
3-4구간 : 평균보다 원활한 항만 운영 상태
5-6구간 : 정상 수준의 운영, 일부 대기 가능
7-8구간 : 대기 선박 증가 또는 하역 처리 지연 발생
9-10구간 : 대기 선박 급증, 항만 처리 한계에 근접한 상태 | int(null 가능) |
waitingShipCount | 36 | 현재 대기하고 있는 선박 수 | int |
avgWaitingDays | 2.2 | 항구에서 현재 대기 중인 선박들의 평균 대기 시간 (일) | real |
workingShipCount | 77 | 현재 작업 중인 선박 수 | int |
avgWorkingDays | 1.8 | 항구에서 현재 작업 중인 선박들의 평균 작업 시간 (일) | real |
avgIdleTimeHours | 5.2 | 항구에서 현재 Idle 상태인 선박들의 평균 Idle 시간 (시간) | real |
onTheWayShipCount | 453 | 현재 항구로 운항 중인 선박 수 | int |