Fleet API는 사용자의 Fleet에 등록된 선박의 실시간 위치 정보 및 예측 도착 시간(PTA) 을 제공합니다.
선박 단위 또는 카테고리 단위 조회가 가능하며, AIS 기반의 정적/동적 데이터가 포함됩니다.
요청 방식
•
HTTP Method : GET
•
API 경로 : /fleet
•
•
인증 방식 : Basic Auth
•
응답 포맷 : JSON
인증 방법
Swagger UI에서 본 API를 호출하려면 아래 절차를 따라야 합니다:
1.
우측 상단 [Authorize] 클릭
2.
제공된 ID / PW 입력
3.
[Authorize] 클릭하여 인증
4.
완료 후 [Close] 클릭
인증이 완료되면 Swagger UI에서 실행되는 모든 API 요청에 인증 토큰이 자동으로 포함됩니다.
Fleet 선박 위치/도착정보 조회 방법
1. Swagger UI 실행 순서
1.
Swagger 문서에서 Fleet 선택
2.
/fleet 경로로 이동
3.
[Try it Out] 클릭
4.
아래 파라미터 입력 조건에 따라 사용
•
아무 파라미터도 입력하지 않으면 전체 선박 리스트 조회
•
categoryId만 입력 시 해당 카테고리의 선박 리스트 조회
•
shipId만 입력 시 해당 선박만 조회
•
categoryId + shipId 함께 입력 시 해당 카테고리 내 특정 선박만 조회
5.
[Execute] 클릭
6.
하단에서 응답 결과 확인
2. 요청 파라미터
파라미터 | 타입 | 설명 |
categoryId | UUID (선택) | 카테고리 ID (8-4-4-4-12 형식) |
shipId | UUID (선택) | 선박 ID (8-4-4-4-12 형식) |
categoryId와 shipId는 [GET /fleet], [GET /fleet/snapshot] 등을 통해 확인할 수 있습니다.응답 정보
응답 예시
{
"code": 200,
"message": "success",
"error": false,
"timestamp": "2025-05-20T10:58:44.269119315",
"response": [
{
"ship": { ... },
"position": { ... },
"categoryIds": [ "27ecdb29-08ec-4880-b73c-dacdd3e6c93c" ]
}
]
}
JSON
복사
응답 필드 설명
필드명 | 예시 | 설명 |
code | 200 | 응답 상태 코드 |
message | success | 처리 결과 메시지 |
error | false | 오류 여부 |
timestamp | 2025-05-20T10:58:44Z | 응답 생성 시각 (UTC) |
response | Array | 선박 정보 배열 (ship + position + category) |
주요 객체 구조
1. ship 객체
필드명 | 예시 | 설명 |
shipId | aaa9dcf0-6af2-4f89-a6d5-c25594ed9837 | 내부 고유 선박 ID |
imoNo | 9637076 | IMO 번호 |
mmsi | 538005248 | MMSI 번호 |
shipName | ARDMORE SEAVANTAGE | 선명 |
shipType | PRODUCT_TANKER | 선종 |
built | 2014 | 건조년도 |
destination | null | 목적지 |
pta | 2025-05-12T00:00:00Z | 예측 도착 시간 (PTA) |
ptb | 2025-05-12T00:00:00Z | 예측 접안 시간 (PTB) |
기타 상세 정보: hullType, gt, breadth, engineBuiltBy, designedBy, nationCode, destinationUnlocode, destinationPortId, teuCapacity 등 포함됨
2. position 객체
필드명 | 예시 | 설명 |
aisClass | A | AIS Class (A = 상업용 대형, B = 소형) |
latitude / longitude | 17.96 / -76.74 | 위도 / 경도 |
speedOverGround | 2.1 | 선박 속도 |
courseOverGround | 47.3 | 진행 방향 |
trueHeading | 51 | 선수 방향 |
timestamp | 2025-05-19T01:10:11Z | 위치 정보 수신 시각 |
추가 정보: deviceType, aisShipType, aisEta, aisDestination, staticDateTime, aisMaxDraught 등 포함됨
3. categoryIds 객체
필드명 | 예시 | 설명 |
categoryIds | 27ecdb29-08ec-4880-b73c-dacdd3e6c93c | 선박이 속한 Fleet 카테고리 ID |
응답 코드 안내
코드 | 설명 |
200 | 정상 처리 |
201 | 리소스 생성 |
400 | 잘못된 요청 |
401 | 인증 실패 |
403 | 권한 없음 |
422 | 처리 불가 |
429 | 요청 과다 (Rate Limit 초과) |
참고 자료
•
[AIS Navigation Status 설명]
•
[AIS Ship Type 목록]
•
[선박 크기 (AIS Dim A/B/C/D)]
•
[Predicted Time of Arrival (PTA)]
이 항목들은 별도 시트나 Notion 문서로도 제공 가능합니다. 원하시면 요청해 주세요.