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
3. Steps to call API
1) How to Call the Cargo Insight API?
•
Step 1. Click on the “API Development Manual” URL below.
•
Step 2. Click on the “ Run in Postman” as shown in the below image and download the
Postman column.
•
Step 3- Click on (post) create Cargo API of Cargo V2 tag for BL registration. Then please authenticate (Basic Auth) and set body value to 'none'.
•
Step 4. Register the M-B/L by entering carrier code and MBL.No or Booking.No.
Please refer to the code column of the service support shipping list in the URL below when entering carrier code.
•
Step 5. Once you register M-B/L, please click (get) get Cargo API on Cargo V2 tag for BL data tracking and authenticate.
•
Step 6. Please enter the registered BL in order 2 to inquire Cargo Tracking data
2) How to Call the Ship Insight API?
•
Step 1. Please proceed with Basic Auth in the same way as explained for Cargo Insight API.
•
Step 2. ShipId is acquired by entering the imo of the vessel to be inquired through Ship - get Ship by Keyword.
•
Step 3. Register the vessel by entering the Ship ID of the vessel inquired in order 1 through the Fleet - create User Fleet API.
•
Step 4. If you call the Fleet - get User Fleet All API, you can look up ships registered in Fleet at once.
