소개
SVMP API를 사용하면 SVMP 내에서 제공하는 선박 및 화물의 위치 추적 및 과거, 미래 예측 항적 등 다양한 데이터를 활용할 수 있습니다.
이 문서에서는 각 API를 호출하기 위한 매개 변수 및 반환되는 개체의 속성에 대해 설명합니다.
질문이 있으시면 support@seavantage.com 으로 연락 주시기 바랍니다.
1. API
1) 사용자 인증
SVMP API 에서는 API 사용자 인증을 Basic Auth(계정/비밀번호) 인증 방식을 사용하고 있습니다.
발급 받으신 사용자 계정과 비밀번호를 Request Header에 함께 전송해주시면 바로 사용하실 수 있습니다.
2) Ship Tracking(선박 위치 추적)
•
선박 추적을 위한 단계는 아래와 같습니다.
- 선박 정보 검색
Request URL
GET /api/v2/ship/search?keyword={ImoNo-ShipName}
JSON
복사
Response body
{
"code": 200,
"message": "OK",
"error": false,
"timestamp": "2021-12-09T09:57:41Z",
"response": [
{
"shipId": "b794428e-8b3a-11e9-b34d-54802853d888", //{SVMP Ship ID}
"imoNo": "9769295",
"mmsi": "538007476",
"callSign": "V7PO8",
"shipType": "CONTAINER",
"shipTypeCargo": "fully cellular containership",
"shipImage": null,
"built": 2017,
"dwt": 197106, //{DeadWeight}
"hullType": "Single",
"gt": 210678, //{GrossTonnage}
"destination": "Hong Kong",
"eta": null,
"shipStatusType": "Active",
"builtBy": "Samsung Shipbuilding & Heavy Industries Company Limited",
"builtAt": "South Korea",
"loa": 400,
"engineBuiltBy": null,
"designedBy": "MAN Diesel AS",
"serviceSpeed": null,
"nationCode": "MH",
"useYn": "Y",
"position": {
"imoNo": "9769295",
"mmsi": "538007476",
"mmsiProcess": null,
"imoNoProcess": null,
"mmsiOrigin": null,
"imoNoOrigin": null,
"aisProcessStatus": null,
"clusterTotalCount": null,
"deviceType": "AIS",
"aisShipType": 72,
"aisDimA": 34,
"aisDimB": 257,
"aisDimC": 25,
"aisDimD": 34,
"aisEta": "{선박에서 기재한 ETA}",
"aisDestination": "{선박에서 기재한 목적지}",
"aisClass": "A",
"nvgStatus": 15,
"longitude": 110.30814,
"latitude": 13.95823167,
"elapsed": 0,
"utcSecond": 60,
"dte": 1,
"specialManeuverIndicator": "0",
"raimFlag": "0",
"staticMessageNo": 5,
"locationMessageNo": 1,
"callsSign": "V7PO8",
"shipName": "MOL TRIBUTE",
"staticDateTime": "2021-12-08T12:45:34Z",
"timestamp": "2021-12-09T09:26:18Z",
"rateOfTurn": 128,
"speedOverGround": 16.6,
"positionAccuracy": 0,
"courseOverGround": 197,
"trueHeading": 195,
"aisMaxDraught": 15.1
},
"siteShip": {
"siteId": "4a88d1f3-9913-4d09-8686-b13837b3baf6",
"shipId": "b794428e-8b3a-11e9-b34d-54802853d888",
"registerId": "{your-account-id}",
"registDateTime": "2021-05-10T09:29:14Z"
},
"shipName": "{ship-name}",
"shipAliasName": null,
"shipTypeBySize": "CONTAINER01",
"depth": 32.8,
"maxDraught": 17
}
]
}
JSON
복사
3) Cargo Tracking(화물 위치 추적)
•
화물 추적을 위한 단계는 아래와 같습니다.
- 화물 추적을 위한 기본 정보 전송
Request URL
POST /api/v2/cargo?bookingNo={your-booking-No}&carrierCode={SCAC-code}
POST /api/v2/cargo?mblNo={your-master-bl-No}&carrierCode={SCAC-code}
{
"bookingRegno": "{Booking Registration No}",
"hbls": [
{
"ciNo": "{Commercial Invoice No}",
"consigneeCode": "{Your Consignee Code}",
"consigneeName": "{Your Consignee Name}",
"containers": [
{
"commodify": "{Your Commodity}",
"containerNo": "{Your Container No}",
"gw": {Your Gross weight},
"hscode": "{Your hscode}",
"qty": {Your Container Qty},
"sealNo1": "{SealNo#1}",
"sealNo2": "{SealNo#2}",
"sealNo3": "{SealNo#3}",
"size": "{Your container size}",
"type": "{Your container type}"
}
],
"hblNo": "{Your house BL}",
"ownerCode": "{Your Cargo Owner Code}",
"ownerName": "{Your Cargo Owner Name}",
"shipperCode": "{Your Cargo Shipper Code}",
"shipperName": "{Your Cargo Shipper Name}"
}
],
"srNo": "{Shipping Request No}"
}
JSON
복사
Response body
{
"code": 201,
"message": "CREATED",
"error": false,
"timestamp": "2021-12-09T09:21:48Z"
}
JSON
복사
- 전송 후 해당 화물 위치 추적 정보 확인
Request URL
GET /api/v2/cargo/search?bookingNo={your-booking-No}
GET /api/v2/cargo/search?mblNo={your-master-bl-No}
JSON
복사
Response body
{
"code": 200,
"message": "OK",
"error": false,
"timestamp": "2021-12-09T09:32:01Z",
"response": {
"documentId": "{SVMP Key}",
"carrierCode": "{Carrier Code}",
"bookingNo": "{Your Booking No}",
"mblNo": "{Your Master B/L No}",
"bookingRegno": "{Booking Registration No}",
"srNo": "{Shipping Requer No}",
"blStatus": "ON",
"locations": [
{
"documentId": "{SVMP Key}",
"partialSeq": 0,
"locationSeq": 1,
"locationId": "{SVMP Location Key}",
"locationCode": "",
"locationName": "BUSAN, KOREA",
"locationType": "POL", //{POR, POL, TSD, TSL, POD, PVY}
"terminalId": null,
"terminalName": "HYUNDAI PUSAN NEWPORT",
"eta": "2021-11-08 22:20",
"ata": "2021-11-10 20:09",
"carrierAta": null,
"etb": "2021-11-08 22:50",
"atb": "2021-11-10 20:40",
"carrierAtb": null,
"etd": "2021-11-12 20:00",
"atd": "2021-11-12 20:58",
"carrierAtd": null,
"pta": null,
"imoNo": "9863340",
"shipName": "{Ship Name}",
"voyageNo": "0005W",
"shipData": { "Ship Detail Info"
}
},
"portData": { "Port Detail Info"
}
},
{}
],
"hbls": [ // {Your House B/L Info}
{
"documentId": "{SVMP key}",
"hblNo": "string",
"ciNo": "string",
"shipperCode": "string",
"shipperName": "string",
"consigneeCode": "string",
"consigneeName": "string",
"ownerCode": "{Cargo Owner Name:Optional}",
"ownerName": "{Cargo Owner Name:Optional}",
"containers": [
{
"documentId": "{SVMP Key}",
"containerNo": "string",
"hblNo": "string",
"partialSeq": 0,
"size": "string",
"type": "string",
"commodify": "string",
"hscode": "string",
"qty": 0,
"gw": 0,
"sealNo1": "string",
"sealNo2": "string",
"sealNo3": "string",
"trackings": [
{
"documentId": "{SVMP Key}",
"containerNo": "{Container NO}",
"trackingSeq": 0,
"eventCode": null,
"eventTime": "202111082220",
"eventStatus": "Actual",
"eventDesc1": "GATE-OUT-EMPTY",
"eventDesc2": "",
"locationName": "Busan new port terminal Co.ltd",
"imoNo": null,
"shipName": null,
"voyageNo": null
}
]
}
]
}
]
}
}
JSON
복사
4) Alarm Cargo (화물 도착 지연 알림)
등록한 화물(M-B/L기준)의 예상 도착 시간(ETA) 대비 예측 도착 시간(PTA)의 차이가 설정한 기준 시간 이상인 화물들의 정보를 한번에 가져올 수 있습니다.
단, 선박의 움직임이 실시간으로 바뀌고 있으나 PTA 계산의 경우 일정 시간에 이루어 지기 때문에 실제와는 일부 차이가 발생할 수 있습니다.
Request URL
GET /v1/alarm/cargo
JSON
복사
Response body
{
"code": 200,
"message": "OK",
"error": false,
"timestamp": "2021-12-10T07:08:47Z",
"response": [{
"mblV2DTO": {
"documentId": "{SVMP Key}",
"carrierCode": "MAEU",
"bookingNo": null,
"mblNo": "{master bl No}",
"bookingRegno": "",
"srNo": "",
"blStatus": "ON",
"locations": [{
"documentId": "{SVMP Key}",
"partialSeq": 0,
"locationSeq": 0,
"locationId": null,
"locationCode": "",
"locationName": "Busan, Korea, South",
"locationType": "POR",
"terminalId": null,
"terminalName": "Busan new port terminal Co.ltd",
"eta": null,
"ata": null,
"carrierAta": null,
"etb": null,
"atb": null,
"carrierAtb": null,
"etd": "2021-11-03 14:19",
"atd": null,
"carrierAtd": null,
"pta": null,
"imoNo": null,
"shipName": "",
"voyageNo": "",
"shipData": null,
"portData": null
},
{ // 선적지 정보
"documentId": "{SVMP Key}",
"partialSeq": 0,
"locationSeq": 1,
"locationId": "dc822048-5534-11e9-a747-54802853d888",
"locationCode": "",
"locationName": "Busan, Korea, South",
"locationType": "POL",
"terminalId": "d20f5180-bbcc-11ea-b607-049226dae5ce",
"terminalName": "Busan new port terminal Co.ltd",
"eta": null,
"ata": "2021-11-05 17:38",
"carrierAta": "2021-11-05 17:40",
"etb": null,
"atb": null,
"carrierAtb": null,
"etd": "2021-11-06 11:32",
"atd": "2021-11-06 22:52",
"carrierAtd": "2021-11-06 22:54",
"pta": null,
"imoNo": "9260445",
"shipName": "ARTHUR MAERSK",
"voyageNo": "142E",
"shipData": {
// Ship Deatil Data
}
},
"portData": {
// Port Detail Data
}
},
{ // 양하지 정보
"documentId": "{SVMP Key}",
"partialSeq": 0,
"locationSeq": 2,
"locationId": "aa925038-e0c8-11e9-a622-54802853d888",
"locationCode": "",
"locationName": "Savannah, United States",
"locationType": "POD",
"terminalId": "d2188e9e-bbcc-11ea-b607-049226dae5ce",
"terminalName": "Savannah Garden City Terminal L738",
"eta": "2021-12-08 05:17",
"ata": null,
"carrierAta": null,
"etb": null,
"atb": null,
"carrierAtb": null,
"etd": null,
"atd": null,
"carrierAtd": null,
"pta": "2021-12-10 15:55",
"imoNo": "9260445",
"shipName": "ARTHUR MAERSK",
"voyageNo": "142E",
"shipData": {
// Ship Detail Data
}
},
"portData": {
// Port Detail Data
}
}
],
"hbls": [{
"documentId": "{SVMP Key}",
"hblNo": "SVH.214348845",
"ciNo": "",
"shipperCode": "",
"shipperName": "",
"consigneeCode": "",
"consigneeName": "",
"ownerCode": null,
"ownerName": null,
"containers": [{
"documentId": "{SVMP Key}",
"containerNo": "{Container No}",
"hblNo": "SVH.214348845",
"partialSeq": 0,
"size": "40",
"type": "Dry",
"commodify": "",
"hscode": "",
"qty": null,
"gw": null,
"sealNo1": "",
"sealNo2": "",
"sealNo3": "",
"trackings": [{
"documentId": "{SVMP Key}",
"containerNo": "{Container NO}",
"trackingSeq": 0,
"eventCode": null,
"eventTime": "202110281407",
"eventStatus": "Actual",
"eventDesc1": "GATE-OUT-EMPTY",
"eventDesc2": "",
"locationName": "Busan new port terminal Co.ltd, Busan, Korea, South",
"imoNo": null,
"shipName": null,
"voyageNo": null
}
]
}]
}]
}
},
"diffHour": 58 //ETA 대비 PTA 지연 시간 정보
}]
}
JSON
복사
2. SVMP 화면 연동(Map View Embed)
1) 사용자 인증
화면 연동을 위한 사용자 인증의 경우 URL에 인증 토큰(Auth Token)을 넘기는 방식이기 때문에 해당 URL이 외부에 노출 됨으로 인한 피해를 줄이기 위해 인증 토큰이 일정 시간 후 만료 됩니다.
따라서 화면을 연동하는 시스템에서 토큰 만료전에 새로운 토큰을 발급 받아서 연동되도록 시스템을 구성하기를 권장합니다.
- 인증 토큰 발급
Request URL
GET /api/v1/user/authToken
JSON
복사
Response body
{
"code": 200,
"message": "OK",
"error": false,
"timestamp": "2021-12-09T06:52:33Z",
"response": [
{
"userId": "{user-account-email}",
"tokenId": "{your-user-token}",
"registDt": "2021-09-29T20:02:31Z",
"expiredDt": "2022-11-14T05:03:50Z"
}
]
}
JSON
복사
2) Ship Tracking
현재 시점 기준 선박의 마지막 추적 위치 및 과거 항적, 예상 항적등을 화면으로 볼 수 있습니다.
Request URL
https://svmp.seavantage.com/#/tracking/ship?authToken={your-user-token}&imoNo={for-tracking-ship-imoNo}&destination={UNLOCODE}&routing={auto|destination}&startDate={yyyyMMdd|auto}
JSON
복사
예시(활용) 화면
Parameters
imoNo : 추적할 선박의 IMO No. 입니다. 일반적으로 숫자 7자리입니다.
// 여러 척의 선박을 추적할 경우 imoNo={0000000}&imoNo={0000001} 형태로 연속해서 입력합니다.
* 한 번에 최대 15척까지 조회할 수 있습니다.
shipName : 추적할 선박의 선명을 입력합니다.
// 여러 척의 선박을 추적할 경우 shipName={name1}&shipName={name2} 형태로 연속해서 입력합니다.
* shipName=CMA%20CGM%20RIGOLETTO&shipName=COSCO%20SINGAPORE
* 선명은 Fullname 으로 URL Encoding하여 전송해야 합니다.
startDate [optional] : {yyyyMMdd | auto}
// 선박이 출발한 직전 항구로부터 또는 입력한 시작일부터 현재 위치까지의 항적 표시를 위한 항목입니다.
// 기본적으로 값이 없을 경우 과거 항적이 표시되지 않습니다.
destination [optional] : 목적지 항구의 UNLOCODE 입니다.
* 일반적으로 알고 있는 Code와 SVMP 에서 사용하고 있는 UNLOCODE는 다를 수 있습니다.
routing [optional] : {auto | destination}
// auto : 선박의 현재 위치에서부터 목적지로 설정하고 있는 곳으로 예상 항로를 표현합니다.
// destination : 선박의 현재 위치에서부터 parameter(destination)로 제공된 목적지까지로의 예상 항로를 표현합니다.
* 단 목적지가 대상 선박이 갈수 없는 항구인 경우 항로가 나오지 않을 수 있습니다.
popupType [optional] : {normal|small}
// 화면 내 선박 정보 팝업의 사이즈를 작게 표시하도록 하는 항목입니다.
// 기본적으로 값이 없을 경우 normal이 적용됩니다.
popupOpen [optional] : {on|off}
// 선박 추적 시 최초에 선박 정보 팝업이 열려있는 상태를 설정하는 항목입니다.
// 기본적으로 값이 없을 경우 on이 적용됩니다.
// off일 경우 최초에는 추적 중인 선박 위치만 표시되고 선박 클릭 시 startDate, destination, routing 옵션값에 따라 정보를 보여줍니다.
JSON
복사
popupType 상태 비교
1.
normal 상태일 때
2.
small 상태일 때
Destination UNLOCODE 확인 방법
1.
아래 이미지와 같이 지도 화면을 확대하면 항구 영영이 표시되면 목적지로 잡고 싶은 항구 이름을 클릭합니다.
2.
아래 그림과 같이 항구 정보 창에서 UNLOCODE를 확인할 수 있습니다.
3) Fleet Tracking << 추가중 >>
4) Cargo Insight
You can access the shipment tracking information sent by SVMP via URL using your UI or API. Such information may be included on Customer's system or accessed through a link.
Cargo Insight 화면을 시스템 내부에 포함시킬 수 있습니다.
Example
Request URL
// Inquiry through Booking No.
https://svmp.seavantage.com/#/cargo/tracking?authToken={your-auth-Token}&bookingNo={your-booking-No}
// Inquiry through M-B/L No.
https://svmp.seavantage.com/#/cargo/tracking?authToken={your-auth-Token}&mblNo={your-master-bl-No}
JSON
복사
new add-on
•
The cargo insight screen has been improved to be responsive to fit the screen size of multiple devices.
•
Add embed option
// Added option to hide panel.
// hiddenPanel=info,timeline,all
hiddenPanel=info : hides only the top info panel
hiddenPanel=timeline : hides only the left timeline panel
hiddenPanel=all : hide all panels except map
JavaScript
복사
If you want to embed the cargo insight screen inside another system, please refer to the following.
<iframe src="https://svmp.seavantage.com/#/cargo/tracking?authToken={your-auth-Token}&mblNo={your-master-bl-No}" style="border:1px #000000 solid;" name="cargoTracking" scrolling="no" frameborder="1" marginheight="0px" marginwidth="0px" height="780px" width="1200px" allowfullscreen></iframe>
HTML
복사
