INTRODUCTION
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.
1. API
1) User Authentication
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.
2) Ship Insight
•
The steps for tracking the vessel are as follows.
- Search for 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 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
}
]
}
JSON
복사
3) Cargo Insight
•
The steps for tracking the cargo are as follows.
- Send basic information for tracking cargo
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) Alerts for Cargo (Notification of Cargo arrival/Delay)
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.
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 //delay hours of ETA VS PTA
}]
}
JSON
복사
2. SVMP Screen Integration (Map View Embed)
1) User Authentication
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.
- Issue 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) Vessel location tracking and destination and expected route trajectory
On the screen, you can see the ship's last location based on the current time, previous track, and expected track.
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 (Utilization) Screen
Parameters
imoNo : IMO No. of the vessel to be tracked. Usually 7 digits.
// If you want to track multiple ships, you can enter them consecutively in the form imoNo={0000000}&imoNo={0000001}.
* You can view up to 15 ships at a time.
routing [optional] : {auto | destination}
// auto : Expresses the expected route from the ship's current location to the destination set.
// destination: Expresses the expected route from the ship's current location to the destination provided as a parameter.
* if the destination is a port that the target vessel cannot go to, the route may not appear.
destination [optional] : The UNLOCODE of the destination port.
* Generally known code and UNLOCODE used in SVMP may be different.
startDate [optional] : {yyyyMMdd | auto}
// yyyyMMdd: Expresses the start date of the past track's initial point.
// auto: Expresses the past track starts from the last port destination.
// If the parameter is not used, the past track will not appear.
popupType [optional] : {normal|small}
// small: Shows the smaller version of ship information popup.
// If the parameter is not used, the normarl version will apply.
popupOpen [optional] : {on|off}
// Sets whether the ship information popups will appear open or closed on the initial page load.
// Off: only the ship locations will appear on map on the initial page load. Once they are clicked, the rest of infomration will appear depending on the given startDate, destination, routing values.
// If the parameter is not used, 'on' will apply.
JSON
복사
popupType
1.
normal
2.
small
How to Check Destination UNLOCODE
1.
Enlarging the map screen shows the port area, as shown in the image below. Click on the name of the port of your interest to set it as a destination..
2.
You can check UNLOCODE in the port information window as shown below.
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
복사
4) Port Insight
Port Insight is a service that monitors maritime traffic occurring within a specific port.
Interested in the situation of ports and whether your shipment will be cleared through the port soon? Worldwide port congestion is currently causing chaos in the ocean freight industry.
See the SeaVantage Port Insight platform in action and how we can help.
There are two ways to view ports in SVMP.
•
Vessel Tracking Page
•
Cargo Tracking > Map POP UP
Click on the map above and enlarge to see the area of each port and its port mark.
By clicking on a port icon, you can access the Port Insight service as below.
Now, Let's look one by one at what information "Port Insight" contains..
1. Map
•
You can check the real-time port status.
•
Through the controller on the right, you can adjust the map in various ways.
An anchored vessel is indicated by a square, and a vessel in operation is indicated by an arrow.
The SIZE/TYPE of the vessel can be distinguished at a glance by the color and size of each arrow (ship).
If you click, you can check the ship name and IMO NO., and when you click the name, it moves to the tracking screen of the relevant ship as shown below. (You can see that it is not berthing at Long Beach and is waiting nearby.)
•
The red icon displayed when zooming in indicates the berth, and the gray area is the zone defined by SeaVantage.
2. Weather
•
It shows the temperature, precipitation, wind strength, and sunrise/sunset times of the port based on the current time of inquiry.
•
It shows weather information up to 7 days in the future from the time of inquiry.
For bulk items that are highly affected by weather during unloading, weather information can be useful.
3. Predicted to Arrive
•
Number of ships expected to arrive at the port
→ AIS > Destination + Prediction information using Big Data (past track) of SeaVantage
•
It is the average value of the last 7 days.
•
You can check the full list of terminals in the port, and you can select and inquire only the desired terminal
•
If you click a value, you will be taken to the screen where you can check the list.
Column | Definition | Remarks |
No | Order | |
Own | Owner | |
Ship type (size) | Ship type (size) | |
Ship name (imo no) | Ship name (imo no) | |
Departure port | Departure port | Previous calling port |
Predicted to arrival terminal | Predicted to arrival terminal | |
ETA | ETA | Estimated Time of Arrival |
PTA | PTA | Predicted Time of Arrival |
Diff | Deviation. | |
Draft | Deviation |
4. Waiting / Day
•
Number of ships waiting to dock at the berth in the port / Average waiting days
•
It is the average value of the last 7 days.
•
You can check the full list of terminals in the port, and you can select and inquire only the desired terminal.
Column | Definition | Remarks |
No | Order | |
Own | Owner | |
Ship type (Size) | Ship type (Size) | |
Ship name | Ship name | |
Departure port | Departure port | Previous Calling port |
Predicted to arrival termina | Predicted to arrival terminal | |
ATA | ATA | Actual Time of Arrival |
Draft | Draift |
5. Working / Day
•
Number of vessels working after berthing at the berth in the port / Average working days
•
It is the average value of the last 7 days.
•
You can check the full list of terminals in the port, and you can select and inquire only the desired terminal.
Column | Definition | Remarks |
No | Order | |
Own | Owner | |
Ship type(size) | Ship type(size) | |
Departure Port | Departure Port | Previous Calling Port |
ATA | ATA | Actual Time of Arrival |
Arrival Terminal | Arrival Terminal | |
ATB | ATB | Actual Time of Berth |
Working | Working hours | |
Draft (Update Time) | Draft (update time) |
6. Departed
•
Number of ships that have left the port after completion of work
•
It is the average value of the last 7 days.
•
You can check the full list of terminals in the port, and you can select and inquire only the desired terminal.
Column | Definition | Remarks |
No | Order | |
Own | Owner | |
Ship name(IMO) | Ship name(IMO) | |
Departure terminal | Departure terminal | Previous Calling Port |
ATA | ATA | Actual Time of Arrival |
ATB | ATB | Actual Time of Berth |
ATD | ATD | Actual Time of Departure |
Worked | Working Hours | |
Draft (Updated Time) | Draft (Updated Time) |
7. Daily Report
•
you can check the Daily report for each 7 days here, Whereas you Could see the average value for the last 7 days in the detailed part above,
- Waiting average
- Working average
- Waiting ship count
•
By selecting "7Day" / "Monthly", you can check the average of 7 days or the average of the month.
8. Status Bar
•
You can move to any screen you are working on
•
POI (Point of interest): You can designate the area you want to manage with interest even if it is not a port.
9. refresh / port local time
•
You can check the updated information every 30 minutes with the auto-refresh button "on" (BLUE)
•
You can find out the local local time of the port.
