<aside> 💬 The SVMP APIs allow you to utilize a variety of data provided within SVMP, including vessel and cargo location tracking and historical and forecasted voyages. This document describes the parameters for calling each API and the properties of the objects returned. If you have any questions, please contact [email protected].
</aside>
<aside> 🔑 SVMP API uses the Basic Auth (account/password) authentication method for API user authentication. Please send the issued user account and password in the request header and you can use it immediately.
</aside>
Below are the steps to track your vessel:
Request URL
GET /api/v2/ship/search?keyword={ImoNo-ShipName}
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 announced by the ship}",
"aisDestination": "{Destination announced by the ship}",
"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
}
]
}
Below are the steps to track your shipment
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}"
}
Response body
{
"code": 201,
"message": "CREATED",
"error": false,
"timestamp": "2021-12-09T09:21:48Z"
}
Request URL
GET /api/v2/cargo/search?bookingNo={your-booking-No}
GET /api/v2/cargo/search?mblNo={your-master-bl-No}
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
}
]
}
]
}
]
}
}
<aside> 💡 You can get the information of registered cargo (based on M-B/L) whose difference between the estimated time of arrival (ETA) and the predicted time of arrival (PTA) is greater than or equal to the set threshold time at once.
However, there may be some differences from the actual time because the ship's movement is changing in real time, but the PTA calculation is done at a certain time.
</aside>
Request URL
GET /v1/alarm/cargo
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
},
{ // Loading Port Information
"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
}
},
{ // Discharging Port Information
"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 //About ETA vs. PTA delays
}]
}
<aside> 🔑 In the case of user authentication for screen integration, an authentication token (Auth Token) is passed to the URL, so the authentication token expires after a certain period of time to reduce damage caused by the URL being exposed to the outside world. Therefore, it is recommended that the system that integrates the screen should be configured to issue a new token before the token expires.
</aside>
Request URL
GET /api/v1/user/authToken
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"
}
]
}
<aside> 🔑 You can view the vessel's last tracked position, past voyages, and predicted route as of the current time.
</aside>