home

System Integration Manual (English Ver)

Introduction

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 sales@seavantage.com.

1. API

1) User authentication

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.

2) Ship Tracking

Below are the steps to track your vessel:

- Retrieve ship information

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 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 } ] }
JSON
복사

3) Cargo Tracking(Cargo location tracking)

Below are the steps to track your shipment

- Send basic information for 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
복사

- Check the cargo location tracking information after transmission

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(Cargo arrival delay notification)

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.
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 }, { // 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 }] }
JSON
복사

2. SVMP system integration (Map View Embedded)

1) User authentication

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.

- Issuance of authentication token

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

You can view the vessel's last tracked position, past voyages, and predicted route as of the current time.
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
복사
Example screen shot
Parameters
imoNo : IMO No. of the vessel to be tracked. no see. It is usually a 7- digit number. =//When tracking multiple ships, enter them consecutively in the form imoNo={0000000}&imoNo={0000001}. * You can view up to 15 ships at a time. shipName : Enter the name of the ship you want to track. // When tracking multiple ships, enter them consecutively in the format shipName={name1}&shipName={name2}. * shipName=CMA%20CGM%20RIGOLETTO&shipName=COSCO%20SINGAPORE * The name must be URL encoded and sent as a full name. startDate [optional] : {yyyyMMdd | auto} // This item is for displaying the track from the port immediately before the ship departed or from the entered start date to the current location. // By default, if there is no value, historical tracks are not displayed. destination [optional] : UNLOCODE of the destination port. * The commonly known code and UNLOCODE used in SVMP may be different. routing [optional] : {auto | destination} // auto : Expresses the expected route from the ship's current location to the place set as the destination. // destination : Expresses the expected route from the ship's current location to the destination provided as parameter (destination). * However, if the destination is a port that the target vessel cannot reach, the route may not be displayed. popupType [optional] : {normal|small} // This item causes the size of the ship information pop-up on the screen to be displayed small. // By default, if there is no value, normal is applied. popupOpen [optional] : {on|off} // This item sets the state in which the ship information pop-up is initially opened when tracking a ship. // By default, on is applied if there is no value. // If off, only the location of the ship being tracked is displayed at first, and when the ship is clicked, information is displayed according to the startDate, destination, and routing option values.
JSON
복사
Pop Up Type
1.
General Pop Up - Enlarged Dialogue box
2.
Brief Pop Up - Small Dialogue box
Destination UNLOCODE
1.
If you zoom in as shown in the image below, the port location will be displayed. Click on the name of the port you want to set as your destination.
2.
You can check UNLOCODE in the port information window as shown below.

3) Fleet Tracking << In Progress>>

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 screens can be embedded within the system.
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
복사

5) Port Insight <<In Progress>>

6) Cargo Tracking Dashboard

References for using SVMP