This API enables real-time tracking of registered cargo, including its movement status, Estimated Time of Arrival (ETA), Predicted Time of Arrival (PTA), and delay information.

Go to Swagger Documentation

Authentication

The Cargo API uses Basic Authorization on Swagger UI.

Authentication Steps:

Click the [Authorize] button in the top right corner.

Enter the provided username and password in the pop-up window.

Click [Authorize] again to proceed with authentication.

After successful login, click [Close] to close the window.

All API requests from Swagger UI will automatically include the authorization token.

Cargo Tracking Request

Request URL

[GET] https://insight.seavantage.com/api/cargo/search

Execution Steps

In the Swagger Documentation, select Cargo from the Select a definition menu at the top right.

Navigate to /cargo/search.

Click [Try it Out] to activate input fields.

Enter one of the following:

•

containerNo: Container Number

•

mblNo: Master B/L Number

•

bookingNo: Booking Number

Click [Execute].

View results in the response section.

Only cargo registered via POST /cargo can be queried using this API.

Response Information

The response is returned in the following format, regardless of whether the request is successful or failed.

Sample Response Format

{
  "code": 200,
  "message": "OK",
  "error": false,
  "timestamp": "2024-12-01T12:00:00",
  "response": {
    "documentId": "string",
    "carrierCode": "string",
    "bookingNo": "string",
    "mblNo": "string",
    "containerNo": "string",
    "blStatus": "string",
    "initialEtd": "2025-05-14T02:06:00.647Z",
    "initialEta": "2025-05-14T02:06:00.647Z",
    "bookingRegno": "string",
    "srNo": "string",
    "customColumn1": "string",
    "customColumn2": "string",
    "customColumn3": "string",
    "locations": [
      {
        "locationSeq": 0,
        "locationType": "string",
        "carrierLocationCode": "string",
        "carrierLocationName": "string",
        "carrierTerminalName": "string",
        "carrierEta": "2025-05-14T02:06:00.647Z",
        "carrierEtb": "2025-05-14T02:06:00.647Z",
        "carrierEtd": "2025-05-14T02:06:00.647Z",
        "carrierAta": "2025-05-14T02:06:00.647Z",
        "carrierAtb": "2025-05-14T02:06:00.647Z",
        "carrierAtd": "2025-05-14T02:06:00.647Z",
        "carrierShipName": "string",
        "carrierVoyageNo": "string",
        "ata": "2025-05-14T02:06:00.647Z",
        "atb": "2025-05-14T02:06:00.647Z",
        "atd": "2025-05-14T02:06:00.647Z",
        "pta": "2025-05-14T02:06:00.647Z",
        "imoNo": "string",
        "port": {
          "portId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "portName": "string",
          "unlocode": "string",
          "nationCode": "string",
        }
      }
    ],
    "hbls": [
      {
        "hblNo": "string",
        "ciNo": "1234567890",
        "shipperCode": "string",
        "shipperName": "string",
        "consigneeCode": "string",
        "consigneeName": "string",
        "ownerCode": "string",
        "ownerName": "string",
        "containers": [
          {
            "containerNo": "string",
            "hblNo": "string",
            "size": "string",
            "type": "string",
            "commodity": "string",
            "hscode": "string",
            "qty": 0,
            "gw": 0,
            "sealNo1": "string",
            "sealNo2": "string",
            "sealNo3": "string",
            "trackings": [
              {
                "trackingSeq": 0,
                "eventCode": "string",
                "eventStatus": "string",
                "eventDescription1": "string",
                "eventDescription2": "string",
                "carrierEventTime": "string",
                "carrierLocationName": "string",
                "unlocode": "string",
                "locationType": "POR"
              }
            ]
          }
        ]
      }
    ]
  }
}
JSON
복사

Response Field Descriptions

Top-Level Response Fields

Field	Example Value	Description
code	200	Response status code (used in the same way as standard HTTP status codes). See the list of codes below for reference.
message	"OK"	Response message (description based on status)
error	false	Error flag true: error occurred false: successful processing
timestamp	"2025-05-14T01:09:00.834665213"	Time of response creation (UTC)
response	null or Object	Returns cargo data if found Returns null if not found

Response Codes

Code	Description
200	Success
400	Bad request
401	Unauthorized
403	Forbidden
422	Unprocessable entity
429	Too many requests

Detailed Response Description

Depth 1 Field Description (response object)

Field	Example	Description
documentId	6ebec210-a072-43ef-a6d1-874fddbc4b36	Internal unique cargo identifier
carrierCode	CMAL	SCAC – 4-letter carrier code
bookingNo	SHZ5400465	Booking number
mblNo	SHZ5400465	Master Bill of Lading number
containerNo	BEAU2789169	Container number
blStatus	END	PROCESSING: Tracking is in progress after the tracking request is made. BEFORE: The vessel has not yet departed from the Port of Loading (POL), before ATD occurs. ON: The vessel has departed from POL and has not yet arrived at the Port of Discharge (POD). END: ATA has occurred at the POD (the vessel has arrived and berthed at the POD). PENDING: 1. When Port of Loading (POL) or Port of Discharge (POD) information is not found 2. When the estimated arrival date at the Port of Discharge (POD) has not been set 3. When tracking fails temporarily within a certain period after initial cargo registration NOT_FOUND: Indicates permanent failure to retrieve cargo tracking information after repeated attempts
initialEtd	2025-01-01 00:00	First collected ETD after cargo registration
initialEta	2025-01-01 00:00	First collected ETA after cargo registration
bookingRegno	null	Booking confirmation number
srNo	null	Shipping request number
customColumn1	null	Custom fields for clients
customColumn2	null	Custom fields for clients
customColumn3	null	Custom fields for clients
locations	[object Object]	Depth 2 → Refer to Location Fields
hbls	[object Object]	Depth 3 → Refer to HBL Fields
referenceType	MBL	Indicates which identifier was used when the cargo was initially registered for tracking. • CONTAINER: Registered using a container number • BOOKING: Registered using a booking number • MBL: Registered using a Master B/L number

Depth 2 Field Description (locations object)

locations provide information about each port (Location) that the cargo passes through. For each location type (e.g., POL, POD), you can also check time-related details such as ETA/ETD, ATA/ATD and PTA.

Field	Example	Description
locationSeq	0	Sequential order of each location within a partial shipment segment.
locationType	POL	POR: Place of Receipt POL: Port of Loading TSD: Transshipment Discharging TSL: Transshipment Loading POD: Port of Discharging PVY: Place of Delivery
carrierLocationCode	CNSHK	Port code from carrier
carrierLocationName	SHEKOU	Port name from carrier
carrierTerminalName	CMA CGM PSA LION TERMINAL	Terminal name from carrier
carrierEta	2025-01-01 00:00	Carrier’s Estimated Time of Arrival
carrierEtb	2025-01-01 00:00	Carrier’s Estimated Time of Berthing
carrierEtd	2025-01-01 00:00	Carrier’s Estimated Time of Departure
carrierAta	2025-01-01 00:00	Carrier’s Actual Time of Arrival
carrierAtb	2025-01-01 00:00	Carrier’s Actual Time of Berthing
carrierAtd	2025-01-01 00:00	Carrier’s Actual Time of Departure
carrierShipName	ANL WANGARATTA	Ship name from carrier
carrierVoyageNo	0WWE9W1MA	Voyage number
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 proprietary data)
imoNo	9334167	IMO Number
port	[object Object]	Depth 3 → Refer to the port object

Depth 3 Field Description (port object)

Field	Example	Description
portId	47941f60-13b8-4718-bead-aa7c3c61d530	SeaVantage internal port classification ID
portName	Busan	Port name
unlocode	KRPUS	Port UN/LOCODE
nationCode	KR	Country code

Depth 4 Field Description (hbls object)

hbls is an object that contains cargo information at the House B/L level. Multiple hbls can be associated with a single Master B/L; if none are entered, they will be generated automatically.

Field	Example	Description
hblNo	SVH.SHZ5400465	House B/L No. If the value is system-generated (no House B/L is entered), it will automatically begin with SVH.
ciNo	null	Commercial Invoice No.
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]	Depth 5 → Refer to the containers object

Depth 5 Field Description (containers object)

containers refers to an object that contains detailed information for each container included under a specific House B/L.

Field	Example	Description
containerNo	BEAU2789169	Container Number
hblNo	SVH.SHZ5400465	House B/L Number
size	22	Container Size
type	G1	Container Type Code
commodity	null	Cargo Type
hscode	null	HS Code (International Standard Commodity Code)
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 trackings object

Depth 6 Field Description (trackings object)

trackings presents the event history that occurred for a container, where each object corresponds to a single event.

Field	Example	Description
trackingSeq	0	Event sequence number per container
eventCode	EE	Event Code (See 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 timestamp
carrierLocationName	SHEKOU	Location name where the event occurred
unlocode	CNSHK	UN/LOCODE of the port where the event occurred
locationType	POL	Location type where the event occurred POL: Port of Loading TS: Transshipment POD: Port of Discharging

Appendix

Types of Container Event Codes

Event codes represent a container’s status, location, estimated time, and actual time.

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 intermodal ramp
AV	Available for delivery
CO	Cargo received at contractual place of receipt
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 original intermodal ramp
UR	Unloaded from rail
VE	Estimated vessel arrival
VT	Estimated vessel departure
X2	ETA at consignee location
C	Estimated to depart terminal location
CI	Passing
X6	En route to delivery location
R	Received from prior carrier
NO	Ocean charges paid
AW	Awaiting export
U	Unloading