GET/port-insight/statistics/ports

1. API 소개

2. 인증

1. API 소개

지정한 항만(port)과 조회 기간 내의 선박 운영에 대한 통계 데이터를 제공합니다.
제공되는 통계에는 대기 시간, 작업 시간, 입항 선박 수 등이 포함됩니다.

2. 인증

Port Insight Statistics API는 사용자 인증을 위해 Swagger UI에서 Basic Authorize 인증 방식을 제공합니다.

인증 절차는 다음과 같습니다:

우측 상단의 [Authorize] 버튼을 클릭합니다.

팝업 창에 제공받은 인증 정보(아이디, 비밀번호)를 입력합니다.

입력 후 다시 [Authorize] 버튼을 클릭하여 인증을 진행합니다.

인증이 완료되면 [Close] 버튼을 클릭하여 인증 창을 닫습니다.

Swagger UI에서 호출되는 모든 API 요청에 인증 토큰이 자동으로 포함되어 전송됩니다.

3. 요청 정보

3-1. 요청 정보

Request URL : [GET] https://insight.seavantage.com/api/port-insight/statistics/terminals

3-2. 실행 순서

Swagger 문서에서 우측 상단의 Select a definition 메뉴에서 Port Insight 선택

/port-insight/statistics/ports 경로로 이동

[Try it Out] 클릭 → 입력창 활성화

요청 portId, from, to를 입력

[Execute] 버튼 클릭

하단 응답 영역에서 등록 결과 확인

Parameters

•

portId : SeaVantage에서 발급한 고유 항구 식별자(Port ID)입니다.

•

from : 조회 시작 일시를 의미하며, UTC 형식의 날짜 및 시간(포함)으로 입력해야 합니다.

•

to : 조회 종료 일시를 의미하며, UTC 형식의 날짜 및 시간(포함)으로 입력해야 합니다.

Swagger 문서 바로가기

4. 응답 정보

요청이 성공하거나 실패했을 때 공통적으로 아래와 같은 형식으로 응답이 반환됩니다.

응답 예시

{
  "code": 200,
  "message": "OK",
  "error": false,
  "timestamp": "2025-05-30T00:17:55.112265142",
  "response": [
    {
      "localAggregatedAt": "2025-01-01T11:30:00Z",
      "aggregatedAt": "2025-01-01T02:30:00Z",
      "onTheWayCount": 160,
      "waitingCount": 27,
      "workingCount": 66,
      "avgStopHour": 3.3614239590291697,
      "avgWaitingHour": 4.451843,
      "avgWorkingHour": 20.572117,
      "arrivalCount": 68,
      "berthingCount": 63,
      "departureCount": 74
    }
  ]
}
JavaScript
복사

입력 필드 상세 설명

필드명 (Attr)	예시 값 (Example)	설명 (Desc)
code	200	응답 상태 코드 (HTTP status code와 동일하게 사용됨)코드 목록은 아래 참조
message	OK	응답 메시지 (상태에 따른 설명)
error	false	오류 여부 (true: 오류 발생, false: 정상 처리)
timestamp	2025-05-15T10:56:59.034880881	응답 생성 시각 (UTC 기준)
response		응답 본문 데이터. 상황에 따라 null 또는 데이터 객체

응답 코드 종류 (code 필드 기준)

코드	설명
201	정상 처리 (Created)
400	잘못된 파라미터 (Bad Request)
401	인증 필요 (Unauthorized)
403	권한 없음 (Forbidden)
422	처리 불가 (Unprocessable Entity)
429	요청 과다 (Too Many Requests)

Depth 1 필드 설명

Attr	Example	Desc
localAggregatedAt	2025-01-01T11:30:00Z	통계 집계 시각(항구 local time 기준)
aggregatedAt	2025-01-01T02:30:00Z	통계 집계 시각(UTC 기준)
onTheWayCount	10	데이터 생성 시점 항구로 이동중인 선박 수
waitingCount	10	데이터 생성 시점 항구 접안 대기중인 선박 수
workingCount	10	데이터 생성 시점 항구 접안 선박 수
avgStopHour	12.3456	대기 영역 바깥쪽에서 발생하는 평균 대기 시간
avgWaitingHour	12.3456	대기 영역에서 발생하는 평균 대기 시간
avgWorkingHour	12.3456	평균 작업 시간
arrivalCount	10	24시간 내 대기 선박 수
berthingCount	10	24시간 내 접안 선박 수
departureCount	10	24시간 내 출항 선박 수