조회 대상 항구에서 출항한 선박 목록을 반환합니다. 조회 가능 기간은 최대 1년 이내 입니다.
인증 방법
Port Insight 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/ships/history
실행 순서
1.
2.
/port-insight/ships/history 경로로 이동합니다.
3.
[Try it out] 버튼을 클릭하여 입력창을 활성화합니다.
4.
아래 요청 Parameters 조건에 따라 결과가 반환됩니다.
•
portId : SeaVantage에서 발급한 고유 항구 식별자(Port ID)
•
departureDaysAgo : API 호출 시점을 기준으로 몇 일 전부터 항구에서 출항한 선박을 조회할지 설정
5.
[Execute] 버튼 클릭합니다.
6.
응답 영역에서 등록 결과를 확인합니다.
응답 정보
요청이 성공하거나 실패했을 때 공통적으로 아래와 같은 형식으로 응답이 반환됩니다.
응답 예시
{
"code": 200,
"message": "OK",
"error": false,
"timestamp": "2024-12-01T12:00:00",
"response": [
{
"portId": "123e4567-e89b-12d3-a456-123456789012",
"shipId": "123e4567-e89b-12d3-a456-123456789012",
"status": "ON_THE_WAY",
"departureAtd": "2025-01-01T00:00:00Z",
"pta": "2025-01-01T00:00:00Z",
"ptaUpdatedAt": "2025-01-01T00:00:00Z",
"ata": "2025-01-01T00:00:00Z",
"atb": "2025-01-01T00:00:00Z",
"atd": "2025-01-01T00:00:00Z",
"stopHour": 12.3456,
"draught": 12.3456,
"previousDraught": 12.3456,
"draughtUpdatedAt": "2025-01-01T00:00:00Z",
"predictDistance": 12.3456,
"ship": {
"shipId": "47941f60-13b8-4718-bead-aa7c3c61d530",
"imoNo": "1234567",
"mmsi": "123456789",
"callSign": "ABC1234",
"shipName": "Ship Name",
"shipType": "CONTAINER",
"shipTypeBySize": "CONTAINER01",
"nationCode": "KR",
"dwt": 20000,
"maxDraught": 15.5
},
"departurePort": {
"portId": "47941f60-13b8-4718-bead-aa7c3c61d530",
"portName": "Busan",
"unlocode": "KRPUS",
"nationCode": "KR",
"latitude": 35.1796,
"longitude": 129.0756,
"timezone": "+09:00"
},
"predictedTerminal": {
"terminalId": "47941f60-13b8-4718-bead-aa7c3c61d530",
"terminalName": "Terminal Name"
},
"arrivalTerminal": {
"terminalId": "47941f60-13b8-4718-bead-aa7c3c61d530",
"terminalName": "Terminal Name"
}
}
]
}
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 객체)
필드명 | 예시 값 | 설명 | 데이터 타입 |
portId | 123e4567-e89b-12d3-a456-123456789012 | 내부적으로 사용하는 Port 구분 값 | varchar(36) - UUID |
shipId | 123e4567-e89b-12d3-a456-123456789012 | 내부적으로 사용하는 Ship 구분 값 | varchar(36) - UUID |
status | ON_THE_WAY | 선박 상태 정보 | varchar(16) |
departureAtd | 2025-01-01T00:00:00Z | 이전 항구 출발 시각 | timestamp |
pta | 2025-01-01T00:00:00Z | Predicted Time of Arrival (씨벤티지) | timestamp |
ptaUpdatedAt | 2025-01-01T00:00:00Z | pta 업데이트 시각 | timestamp |
ata | 2025-01-01T00:00:00Z | Actual Time of Arrival | timestamp |
atb | 2025-01-01T00:00:00Z | Actual Time of Berth | timestamp |
atd | 2025-01-01T00:00:00Z | Actual Time of Departure | timestamp |
stopHour | 12.3456 | 이전 항구 출발부터 ATA까지의 선박 정지 시간 | double precision |
draught | 12.3456 | 선박 흘수 정보 | double precision |
previousDraught | 12.3456 | 업데이트 이전의 선박 흘수 정보 | double precision |
draughtUpdatedAt | 2025-01-01T00:00:00Z | 선박 흘수 정보 업데이트 시각 | timestamp |
predictDistance | 12.3456 | 현재 위치 기준 다음 목적지까지 남은 예상 거리 | double precision |
ship | [object Object] | Depth 2 ⇒ ship 객체 참고 | |
departurePort | [object Object] | Depth 3 ⇒ departurePort 객체 참고 | |
predictedTerminal | [object Object] | Depth 4 ⇒ predictedTerminal 객체 참고 | |
arrivalTerminal | [object Object] | Depth 5 ⇒ arrivalTerminal 객체 참고 |
Depth 2 필드 설명 (ship 객체)
필드명 | 예시 값 | 설명 | 데이터 타입 |
shipId | 0260120d-39db-45a4-b22d-83addb409219 | 내부적으로 사용하는 Ship 구분 값 | varchar(36) - UUID |
imoNo | 9765988 | 선박 IMO 등록번호 | varchar(10) |
mmsi | 440027000 | 선박 고유 식별 번호 | varchar(10) |
callSign | D7BK | 호출부호 | varchar(7) |
shipName | KEOYOUNG BLUE 1 | 선명 | varchar(100) |
shipType | CHEMICAL_TANKER | 선종/사이즈
선종별 사이즈 분류 (아래 표 참고) | varchar(36) |
shipTypeBySize | CHEMICAL_TANKER01 | 선종/사이즈
선종별 사이즈 분류 (아래 표 참고) | varchar(36) |
nationCode | KR | 국가 코드 | varchar(36) |
dwt | 1773 | 총재화중량 | integer |
maxDraught | 4.93 | 최대 흘수 | real |
Depth 3 필드 설명 (departurePort 객체)
필드명 | 예시 값 | 설명 | 데이터 타입 |
portId | 47941f60-13b8-4718-bead-aa7c3c61d530 | 내부적으로 사용하는 Port 구분 값 | varchar(36) - UUID |
portName | Busan | 항구명 | varchar(255) |
unlocode | KRPUS | 항구 UNLOCODE | varchar(36) |
nationCode | KR | 국가 코드 | varchar(36) |
latitude | 35.1796 | 위도 | double precision |
longitude | 129.0756 | 경도 | double precision |
timezone | +09:00 | 항구 타임존 | varchar(36) |
Depth 4 필드 설명 (predictedTerminal 객체)
필드명 | 예시 값 | 설명 | 데이터 타입 |
terminalId | 47941f60-13b8-4718-bead-aa7c3c61d530 | 내부적으로 사용하는 Terminal 구분 값 | varchar(36) - UUID |
terminalName | Terminal Name | 터미널명 | varchar(128) |
Depth 5 필드 설명 (arrivalTerminal 객체)
필드명 | 예시 값 | 설명 | 데이터 타입 |
terminalId | 47941f60-13b8-4718-bead-aa7c3c61d530 | 내부적으로 사용하는 Terminal 구분 값 | varchar(36) - UUID |
terminalName | Terminal Name | 터미널명 | varchar(128) |
부록
선종별 사이즈 분류
Bulk Carrier
분류 코드 | 선박 등급 | 하한 (DWT) | 상한 (DWT) |
BULK 05 | Handysize | 0 | 34,999 |
BULK 04 | Handymax | 35,000 | 59,999 |
BULK 03 | Panamax | 60,000 | 79,999 |
BULK 02 | Capesize | 80,000 | 179,999 |
BULK 01 | VLBC | 180,000 |
Cargo
분류 코드 | 선박 등급 | 하한 (DWT) | 상한 (DWT) |
CARGO 04 | General Cargo | 0 | 2,999 |
CARGO 03 | General Cargo | 3,000 | 7,499 |
CARGO 02 | General Cargo | 7,500 | 37,999 |
CARGO 01 | General Cargo | 38,000 |
Chemical Tanker
분류 코드 | 선박 유형 | 분류 설명 |
CHEMICAL_TANKER01 | Product Tanker | Chemical tanker, combined chemical and oil tanker |
Container
분류 코드 | 선박 등급 | 하한 (TEU) | 상한 (TEU) |
CONTAINER 07 | Small Feeder | 0 | 1,000 |
CONTAINER 06 | Feeder Containership | 1,001 | 2,000 |
CONTAINER 05 | Feedermax Containership | 2,001 | 3,000 |
CONTAINER 04 | Panamax Containership | 3,001 | 5,100 |
CONTAINER 03 | Post-Panamax Containership | 5,101 | 10,000 |
CONTAINER 02 | Neo-Panamax Containership | 10,001 | 14,500 |
CONTAINER 01 | ULCV Containership | 14,501 |
LNG
분류 코드 | 선박 등급 | 하한 (Gross Tonnes) | 상한 (Gross Tonnes) |
LNG 03 | LNG Gas Carrier | 0 | 73,000 |
LNG 02 | LNG Gas Carrier | 73,001 | 147,000 |
LNG 01 | LNG Gas Carrier | 147,001 |
LPG
분류 코드 | 선박 등급 | 하한 (Gross Tonnes) | 상한 (Gross Tonnes) |
LPG 03 | LPG Gas Carrier | 0 | 4,500 |
LPG 02 | LPG Gas Carrier | 4,501 | 26,000 |
LPG 01 | LPG Gas Carrier | 26,001 |
Pure Car Carrier (PCC)
분류 코드 | 선박 등급 | 하한 (Gross Tonnes) | 상한 (Gross Tonnes) |
PCC 03 | PCC/PCTC | 0 | 35,000 |
PCC 02 | PCC/PCTC | 35,001 | 61,000 |
PCC 01 | PCC/PCTC | 61,001 |
Ro-ro
분류 코드 | 선박 등급 | 하한 (Gross Tonnes) | 상한 (Gross Tonnes) |
RORO 03 | Ro-ro Cargo | 0 | 0 |
RORO 02 | Ro-ro Cargo | 8,501 | 48,000 |
RORO 01 | Ro-ro Cargo | 48,001 |
Tanker
분류 코드 | 선박 유형 | 분류 설명 |
TANKER 05 | Crude Oil Tanker | Tanker- Panamax |
TANKER 04 | Crude Oil Tanker | Tanker- Aframax |
TANKER 03 | Crude Oil Tanker | Tanker- Suezmax |
TANKER 02 | Crude Oil Tanker | Tanker- VLCC |
TANKER 01 | Crude Oil Tanker | Tanker- ULCC |
Product Tanker
분류 코드 | 선박 유형 |
PRODUCT_TANKER01 | Product Tanker |
Tug
분류 코드 | 선박 유형 |
TUG01 | Tug |
FPSO
분류 코드 | 선박 유형 | 분류 설명 |
FPSO01 | FPSO | Floating drilling production tanker, floating gas production, floating gas storage, floating LNG production and storage FLNG, floating power station, floating production tanker, floating storage tanker |
ETC
분류 코드 | 선박 유형 |
ETC01 | ETC All |