1. API Introduction
The Cargo Insight API enables real-time tracking of cargo movement,
including Estimated Time of Arrival (ETA), Predicted Time of Arrival (PTA), and delay status.
Through this API, users can comprehensively retrieve key vessel information, event timestamps, and arrival forecasts.
To track cargo, at least one of the following pieces of information is required:
•
Master B/L Number
•
Booking Number
•
Container Number
2. Authentication Method
The Cargo API uses Basic Authorize authentication through the Swagger UI.
Authentication Steps:
1.
Access the Swagger Documentation
2.
Click the [Authorize] button at the top right
3.
Enter the provided ID and Password in the pop-up window
4.
Click [Authorize] again, then [Close] to finish
Once authorized, the authentication token will be automatically included in all API requests made via Swagger UI.
3. Cargo Tracking
3-1. Request Info
Request URL: [GET] https://insight.seavantage.com/api/cargo/search
3-2. Execution Steps
1.
In the Swagger documentation, select Cargo from the "Select a definition" menu at the top right
2.
Navigate to /cargo/search
3.
Click [Try it out] to enable the input fields
4.
Input one of the following parameters:
•
containerNo: Container Number
•
mblNo: M-B/L Number
•
bookingNo: Booking Number
5.
Click [Execute]
6.
Check the response section for results
3-3. Response Format
Responses (success or failure) follow a consistent structure:
Sample Response:
{
"code": 200,
"message": "OK",
"error": false,
"timestamp": "2024-12-01T12:00:00",
"response": { ... }
}
Plain Text
복사
Response Fields Description
Attr | Example | Desc |
code | 200 | HTTP status code |
message | "OK" | Description of the response status |
error | false | Indicates if an error occurred (true/false) |
timestamp | "2025-05-14T01:09:00.834665213" | Timestamp of response (UTC) |
response | Object or null | Cargo data object or null if not found |
Response Code Reference
Code | Description |
201 | Successfully processed (Created) |
400 | Bad Request (Invalid parameters) |
401 | Unauthorized (Authentication required) |
403 | Forbidden (No access rights) |
422 | Unprocessable Entity |
429 | Too Many Requests |
Response Object Details
The response field contains the main cargo information and status.
Depth 1: Cargo Level
Attr | Example | Desc |
documentId | 6ebec210-a072-43ef-a6d1-874fddbc4b36 | An internally used cargo identifier. |
carrierCode | CMAL | SCAC 4-character carrier code. |
bookingNo | SHZ5400465 | Booking Number |
mblNo | SHZ5400465 | Master B/L Number |
containerNo | BEAU2789169 | Container Number |
blStatus | END | PROCESSING: Cargo tracking is in progress after a tracking request has been made.
BEFORE: The vessel has not yet departed from the Port of Loading (ATD not yet recorded).
ON: The vessel has departed from the Port of Loading and has not yet arrived at the Port of Discharge.
END: ATA has been recorded at the Port of Discharge (the vessel has arrived and berthed at POD).
PENDING:
1. When location data is unavailable
2. When the arrival date at POD is not yet determined
3. When tracking fails within 10 days of registration
NOT_FOUND: Tracking has failed for more than 10 days after registration. |
initialEtd | 2025-01-01 00:00 | Initially collected ETD after cargo registration |
initialEta | 2025-01-01 00:00 | Initially collected ETA after cargo registration |
bookingRegno | null | Booking Confirmation Number |
srNo | null | Shipping Request Number |
customColumn1 | null | Custom Field 1 |
customColumn2 | null | Custom Field 2 |
customColumn3 | null | Custom Field 3 |
locations | [object Object] | See Depth 2 → location object |
hbls | [object Object] | See Depth 3 → hbls object |
Depth 2: Location Details
The locations object represents information about each port the cargo passes through.
For each location type (e.g., POL, POD), you can also view associated time data such as ETA/ETD and ATA/ATD.
Attr | Example | Desc |
locationSeq | 0 | Sequence number of the location for each partial shipment |
locationType | POL | POR: Place of Receipt
POL: Port of Loading
TSD: Port of Transit Discharging
TSL: Port of Transit Loading
POD: Port of Discharging
PVY: Place of Delivery |
carrierLocationCode | CNSHK | Location code collected from the carrier |
carrierLocationName | SHEKOU | Location name collected from the carrier |
carrierTerminalName | CMA CGM PSA LION TERMINAL | Terminal name collected from the carrier |
carrierEta | 2025-01-01 00:00 | Estimated Time of Arrival collected from the carrier |
carrierEtb | 2025-01-01 00:00 | Estimated Time of Berthing collected from the carrier |
carrierEtd | 2025-01-01 00:00 | Estimated Time of Departure collected from the carrier |
carrierAta | 2025-01-01 00:00 | Actual Time of Arrival collected from the carrier |
carrierAtb | 2025-01-01 00:00 | Actual Time of Berthing collected from the carrier |
carrierAtd | 2025-01-01 00:00 | Actual Time of Departure collected from the carrier |
carrierShipName | ANL WANGARATTA | Vessel name collected from the carrier |
carrierVoyageNo | 0WWE9W1MA | Voyage number collected from the carrier |
ata | 2025-01-01 00:00 | Actual Time of Arrival generated from SeaVantage port call data |
atb | 2025-01-01 00:00 | Actual Time of Berthing generated from SeaVantage port call data |
atd | 2025-01-01 00:00 | Actual Time of Departure generated from SeaVantage port call data |
pta | 2025-01-01 00:00 | Predicted Time of Arrival (SeaVantage) |
imoNo | 9334167 | IMO Number |
port | [object Object] | See Depth 3 → port object |
Depth 3: Port Object
Attr | Example | Desc |
portId | 47941f60-13b8-4718-bead-aa7c3c61d530 | Internally used port identifier |
portName | Busan | Port name |
unlocode | KRPUS | Port UNLOCODE |
nationCode | KR | Country code |
Depth 4: HBL Object
The hbls object contains cargo information at the House B/L level. A single Master B/L can include multiple hbls entries, and if none are provided, they will be generated automatically.
Attr | Example | Desc |
hblNo | SVH.SHZ5400465 | House B/L Number (auto-generated values start with SVH.) |
ciNo | null | Commercial Invoice Number |
shipperCode | null | Shipper Code |
shipperName | null | Shipper Name |
consigneeCode | null | Consignee Code |
consigneeName | null | Consignee Name |
ownerCode | null | Cargo Owner Code |
ownerName | null | Cargo Owner Name |
containers | [object Object] | See Depth 5 → containers object |
Depth 5: Container Object
The containers object contains detailed information for each container included in a House B/L.
Attr | Example | Desc |
containerNo | BEAU2789169 | Container Number |
hblNo | SVH.SHZ5400465 | House B/L Number |
size | 22 | Container Size |
type | G1 | Container Type Code |
commodity | null | Commodity |
hscode | null | HS Code (International Standard) |
qty | null | Quantity |
gw | null | Gross Weight |
sealNo1 | null | Seal Number #1 |
sealNo2 | null | Seal Number #2 |
sealNo3 | null | Seal Number #3 |
trackings | [object Object] | Depth 6 → Refer to the trackings object |
Depth 6: Tracking Events
Trackings represent the event history that occurred for the container, with each object corresponding to a single event.
Attr | Example | Desc |
trackingSeq | 0 | Sequence number of the event per container |
eventCode | EE | Event code (refer to the separate event code table below) |
eventStatus | Actual | Event status (Actual, Estimate) |
eventDescription1 | EmptyDeliveredToShipper | Event description 1 |
eventDescription2 | TRUCK | Event description 2 |
carrierEventTime | 2025-01-01 00:00 | Event occurrence time |
carrierLocationName | SHEKOU | Event location name |
unlocode | CNSHK | UNLOCODE of the port where the event occurred |
locationType | POL | Event location type
POL: Port of Loading
TS: Port of Transit
POD: Port of Discharging |
3-4. Container Event Code Reference
Event codes represent cargo status and location changes.
Event Code | Description |
I | In Gate |
AE | Loaded on Vessel |
VD | Vessel Departure |
VA | Vessel Arrival |
VB | Vessel Berthing |
UV | Unloaded from Vessel |
OA | Out Gate |
D | Delivered to the Consignee |
RD | Empty Container Returned |
A | Arrived |
AD | Appointment Date/Time for Delivery |
AG | ETA Changed |
AL | Loaded on Rail |
AM | Loaded on Truck |
AP | Loaded on Feeder Vessel |
AR | Rail Arrival at Destination |
AV | Available for Delivery |
CO | Cargo Received at Origin |
CR | Carrier Release |
CT | Customs Released |
CU | Carrier and Customs Released |
FT | Free Time Expired |
MT | Empty Returned to CY |
P | Full Container Issued |
PA | US Customs Hold |
RL | Rail Departure from Origin |
UR | Unloaded from Rail |
VE | Estimated Vessel Arrival |
VT | Estimated Vessel Departure |
X2 | ETA at Consignee Location |
C | Estimated to Depart Terminal |
CI | Passing |
X6 | En Route To Delivery Location |
R | Received From Prior Carrier |
NO | Ocean Charges Paid |
AW | Awaiting Export |
U | Unloading |