<aside> 💬 By using the SVMP API, you can utilize various data provided within SVMP, such as tracking the location of ships and cargoes, as well as historical and future forecasting trajectories.
This article describes the parameters for calling each API and the properties of the returned object.
If you have any questions, please contact us at [email protected].
</aside>
<aside> 🔑 SVMP API uses Basic Auth (account/password) authentication for API user authentication. If you send the issued user account and password together in the Request Header, you can use it immediately.
</aside>
The steps for tracking the vessel are as follows.
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 provided by the vessel }",
"aisDestination": "{Destination provided by the vessel}",
"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
}
]
}
The steps for tracking the cargo are as follows.
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 retrieve information on cargoes whose difference between the estimated arrival time (ETA) and the predicted arrival time (PTA) of the registered cargo (based on M-B/L) is longer than the set standard time. The movement of the vessel changes in real time, so in the case of PTA calculation there may be some differences from the actual because it is performed at a specific 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
},
{ // 선적지 정보
"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 //delay hours of ETA VS PTA
}]
}
<aside> 🔑 In the case of user authentication for screen interlocking, since the authentication token is passed to the URL, the authentication token expires after a certain period of time to to reduce the risk of external exposure of URLs. Therefore, it is recommended to configure the screen interlocking system so that it issues a new token before the expiration date and interlocks it.
</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"
}
]
}