이 API는 항구의 터미널 기준 이전 기항 물동량 데이터를 반환합니다. AIS 데이터를 기반으로 평균 약 15분 단위로 업데이트됩니다.
1. 인증 방법
Port Insight Previous Calling 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-insight/previous-calling/terminals
2-2. 실행 순서
1.
2.
/port-insight/previous-calling/terminals 경로로 이동
3.
[Try it out] 클릭 → 입력창 활성화
4.
아래 요청 Parameters 조건에 따라 결과 반환
•
portId (필수)
◦
Seavantage에서 발급한 고유 항구 식별자(Port ID)
◦
[GET] /port API를 통해 Port ID 확인 가능
•
from (필수)
◦
조회 시작 일시 (UTC 기준)
◦
예 : 2025-01-01T00:00:00Z
•
to (필수)
◦
조회 종료 일시 (UTC 기준)
◦
예 : 2025-01-01T00:00:00Z
•
terminalIds (선택)
◦
조회 항구의 터미널 ID 리스트 필터
◦
[GET] /port/terminal API를 통해 terminal ID 확인 가능
◦
복수 입력 가능
•
previousCallingNationCode (선택) : 조회 시 이전 기항 국가 코드 필터
•
previousCallingPortId (선택)
◦
이전 기항지에 대한 portId 필터
◦
[GET] /port API를 통해 Port ID 확인 가능
5.
[Execute] 버튼 클릭
6.
하단 응답 영역에서 등록 결과 확인
3. 응답 정보
요청이 성공하거나 실패했을 때 공통적으로 아래와 같은 형식으로 응답이 반환됩니다.
응답 예시 (조건별)
요청 시 입력한 파라미터 조건에 따라 응답 결과가 달라지며, 각 조건별 응답 형태는 아래 예시를 참고해 주세요.
•
항구 및 터미널에 대한 정보만 입력 시 → 국가 단위로 선박 수 및 월별 물동량 조회
•
이전 기항지의 nationCode 입력 시 → 항구 단위로 선박 수 및 월별 물동량 조회
•
이전 기항지의 nationCode + portId 입력 시 → 터미널 단위로 선박 수 및 월별 물동량 조회
portId + from + to 입력
•
조회 대상 항구 기준 → 국가 단위 이전 기항 선박 수 및 월별 물동량 조회
{
"code": 200,
"message": "OK",
"error": false,
"timestamp": "2025-08-18T08:53:58.569647467",
"response": [
{
"key": "CN",
"value": "China",
"shipCount": 100,
"volume": 7099721
}
]
}
JavaScript
복사
portId + from + to + terminalIds 입력
•
조회 대상 항구의 상세 터미널 기준 → 국가 단위 이전 기항 선박 수 및 월별 물동량 조회
{
"code": 200,
"message": "OK",
"error": false,
"timestamp": "2025-08-18T08:53:58.569647467",
"response": [
{
"key": "CN",
"value": "China",
"shipCount": 100,
"volume": 7099721
}
]
}
JavaScript
복사
portId + from + to + previousCallingNationCode 입력
•
조회 대상 항구 기준 → 항구 단위 이전 기항 선박 수 및 월별 물동량 조회
{
"code": 200,
"message": "OK",
"error": false,
"timestamp": "2025-08-18T08:56:01.474372636",
"response": [
{
"key": "3ad979b4-9370-11ea-b3ad-049226dae5ce",
"value": "Gwangyang",
"shipCount": 48,
"volume": 1175679
}
]
}
JavaScript
복사
portId + from + to + terminalIds + previousCallingNationCode 입력
•
조회 대상 항구의 상세 터미널 기준 → 항구 단위 이전 기항 선박 수 및 월별 물동량 조회
{
"code": 200,
"message": "OK",
"error": false,
"timestamp": "2025-08-18T08:56:01.474372636",
"response": [
{
"key": "3ad979b4-9370-11ea-b3ad-049226dae5ce",
"value": "Gwangyang",
"shipCount": 48,
"volume": 1175679
}
]
}
JavaScript
복사
portId + from + to + previousCallingNationCode + previousCallingPortId 입력
•
조회 대상 항구 기준 → 터미널 단위 이전 기항 선박 수 및 월별 물동량 조회
{
"code": 200,
"message": "OK",
"error": false,
"timestamp": "2025-08-18T08:57:55.601328709",
"response": [
{
"key": "8932aaf6-7882-11ec-a285-049226dae5ce",
"value": "GWANGYANG WEST CONTAINER TERMINAL",
"shipCount": 25,
"volume": 788658
}
]
}
JavaScript
복사
portId + from + to + terminalIds + previousCallingNationCode + previousCallingPortId 입력
•
조회 대상 항구의 상세 터미널 기준 → 터미널 단위 이전 기항 선박 수 및 월별 물동량 조회
{
"code": 200,
"message": "OK",
"error": false,
"timestamp": "2025-08-18T08:57:55.601328709",
"response": [
{
"key": "8932aaf6-7882-11ec-a285-049226dae5ce",
"value": "GWANGYANG WEST CONTAINER TERMINAL",
"shipCount": 25,
"volume": 788658
}
]
}
JavaScript
복사
응답 필드 상세 설명
응답 항목별 정의
필드명 | 예시 값 | 설명 |
code | 200 | 응답 상태 코드 (HTTP status code와 동일하게 사용됨)
(아래 별도 응답 코드표 참조) |
message | "OK" | 응답 메시지 (상태에 따른 설명) |
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 객체)
필드명 | 예시 값 | 설명 | 데이터 타입 |
key | nationCode, portId, terminalId | 조회 대상의 코드 및 ID 값 | varchar |
value | nationName, portName, terminalName | 조회 대상의 이름 | varchar |
shipCount | 10 | 선박 수 | integer |
volume | 10 | 물동량 (단위 : dwt) | integer |