Container No. Tracking API

* Container No. Tracking API is available exclusively for enterprise customers. If you wish to use this service, please contact us at cx@tradlinx.com or global_sales@tradlinx.com.

The base request URL for the TRADLINX Ocean Visibility API is: https://api.tradlinx.com

The API is activated based on a pre-agreed schedule. Once activated, you can send requests and receive responses normally.

Common API Guidelines:

• An asterisk * indicates a required field.
• A question mark ? indicates an optional field, which may or may not be provided.
• Requests that violate these constraints will not be processed.
• For types other than string, boolean, or number, refer to the custom types defined within this document.
• For error code references, see the 'Error Codes' section in the reference materials.

🔔 API Update & Backward Compatibility Notice

The TRADLINX Ocean Visibility API may be updated from time to time to improve service quality, expand data coverage, and introduce new features.

When updating the API, we prioritize the stable operation of existing integrations and follow backward-compatible change principles, such as adding new fields.

Accordingly, we recommend that client systems be implemented in a backward-compatible manner so that they can continue to operate normally even when unknown or newly added fields are included in API responses.

If any changes may affect existing integrations, we will provide advance notice.

1. Container No. Tracking Request

• You may register multiple tracking requests at once, up to 50 entries per request.
• Requests must be organized in an Array structure according to the provided data schema.
• The combination of container_no, carrier_code, and reference_no must be unique. Entries with identical values will be treated as duplicates and not registered.
• For the list of carrier codes, please refer to the Supported Carriers.

Request

POST /partners/track/v3/container-tracks

Shipment Tracking Request Data

Field	Type	Size	Description	Constraint
*container_no	string	20	Container number	Max 20 characters
*reference_no	string	400	Reference number	Max 400 characters
*carrier_code	string	5	Carrier code	Max 5 characters
client	string	100	Customer company name	Max 100 characters
internal_usage	string	50	Customer contact name	Max 50 characters
remark	string	400	Notes	Max 400 characters

curl -X POST "https://api.tradlinx.com/partners/track/v3/container-tracks" \
  -H "tx-clientid: [Client ID]" \
  -H "tx-apikey: [API Key]" \
  -H "Content-Type: application/json"
  -d '[
    {
      "container_no": "SAMPLE_CONTAINER_NO",
      "client": "SAMPLE_CLIENT_NAME",
      "internal_usage": "SAMPLE_INTERNAL_USAGE",
      "reference_no": "SAMPLE_REFERENCE_NO",
      "carrier_code": "SAMPLE_CARRIER_CODE",
      "remark": "SAMPLE_REMARK"
    }
  ]'

Response

{
  "api_version": "v3",
  "content": {
    "fail": [
      {
        "data": {
          "container_no": "SAMPLE_CONTAINER_NO",
          "carrier_code": "SAMPLE_CARRIER_CODE",
          "reference_no": "SAMPLE_REFERENCE_NO"
        },
        "reason": "SAMPLE_REASON"
      }
    ],
    "fail_count": 1,
    "success": [
      {
        "container_no": "SAMPLE_CONTAINER_NO",
        "carrier_code": "SAMPLE_CARRIER_CODE",
        "client": "SAMPLE_CLIENT",
        "internal_usage": "SAMPLE_INTERNAL_USAGE",
        "reference_no": "SAMPLE_REFERENCE_NO",
        "track_mst_id": "SAMPLE_TRACK_MST_ID"
      }
    ],
    "success_count": 1,
    "total_count": 2
  },
  "message": "SAMPLE_ERROR_CODE",
  "transaction_time": "2025-07-09T04:49:44.401254"
}

Response Body

Field	Type	Description	Notes
api_version	string	API version
content	SuccessFail	Success/Failure status
message	string	Server message	Returned if applicable
transaction_time	string	Response timestamp	yyyy-MM-dd'T'HH:mm:ss.SSSSSS

SuccessFail

Field	Type	Description
success	Success[]	Summary of successfully registered data
success_count	number	Number of successfully registered data entries
fail	Fail[]	Summary of failed registration data
fail_count	number	Number of failed data entries
total_count	number	Total number of requests

Success

Field	Type	Size	Description
container_no	string	20	Container number
client	string	100	Customer company name
internal_usage	string	50	Customer contact name
reference_no	string	400	Reference number
carrier_code	string	5	Carrier code
track_mst_id	uuid	50	Unique shipment ID that can be obtained through shipment lookup

Fail

Field	Type	Description
data	FailData	Summary of failed data
reason	string	Reason for failure

FailData

Field	Type	Size	Description
container_no	string	20	Container number
carrier_code	string	5	Carrier code
reference_no	string	400	Reference number

2. Container No. Tracking Update Request

• The fields container_no, carrier_code, reference_no are unique identifiers for a shipment. If a record with the same combination already exists, the update will not be applied.

Request

PUT /partners/track/v3/container-tracks/{track_mst_id}

PathVariable

Field	Type	Size	Description
*track_mst_id	uuid	50	Unique shipment ID that can be obtained through shipment lookup

RequestBody

Field	Type	Size	Description	Constraint
*reference_no	string	400	Unique reference number	Max 400 characters
client	string	100	Customer company name	Max 100 characters
internal_usage	string	50	Customer contact name	Max 50 characters
remark	string	400	Notes	Max 400 characters

curl -X PUT "https://api.tradlinx.com/partners/track/v3/container-tracks/[Track MST ID]" \
  -H "tx-clientid: [Client ID]" \
  -H "tx-apikey: [API Key]" \
  -H "Content-Type: application/json"
  -d '{
    "reference_no": "SAMPLE_REFERENCE_NO",
    "client": "SAMPLE_CLIENT_NAME",
    "internal_usage": "SAMPLE_INTERNAL_USAGE",
    "remark": "SAMPLE_REMARK"
  }'

Response

200 OK

{}

400 Error

{
  "error_detail": "[track_mst_id]: must not be blank",
  "message": "SAMPLE_ERROR_CODE",
  "transaction_time": "2024-08-13T05:42:27.402256"
}

3. Container No. Tracking Cancellation Request

• Cancellation requests must be made one at a time.
• If the shipment status is TRACKING or COMPLETE, canceling the tracking request will not refund the credits, as they are already deducted.

Request

DELETE /partners/track/v3/container-tracks/{track_mst_id}

PathVariable

Field	Type	Size	Description
*track_mst_id	uuid	50	Unique shipment ID that can be obtained through shipment lookup

curl -X DELETE "https://api.tradlinx.com/partners/track/v3/container-tracks/[Track MST ID]" \
  -H "tx-clientid: [Client ID]" \
  -H "tx-apikey: [API Key]" \

Response

If successful, the server returns HTTP status code 200.

4. Container No. Tracking Re-Registration Request

• You can re-register tracking for shipments in one of the following statuses: retry failed (after 7 days), unsupported plan, or insufficient credits.

Request

POST /partners/track/v3/container-tracks/{track_mst_id}/re-enroll

PathVariable

Field	Type	Size	Description
*track_mst_id	uuid	50	Unique shipment ID that can be obtained through shipment lookup

curl -X POST "https://api.tradlinx.com/partners/track/v3/container-tracks/[Track MST ID]/re-enroll" \
  -H "tx-clientid: [Client ID]" \
  -H "tx-apikey: [API Key]" \
  -H "Content-Type: application/json"
  -d '{}'

Response

{
  "api_version": "v3",
  "content": {
    "container_no": "SAMPLE_CONTAINER_NO",
    "carrier_code": "SAMPLE_CARRIER_CODE",
    "client": "SAMPLE_CLIENT",
    "internal_usage": "SAMPLE_INTERNAL_USAGE",
    "reference_no": "SAMPLE_REFERENCE_NO",
    "track_mst_id": "SAMPLE_TRACK_MST_ID"
  },
  "message": "SAMPLE_ERROR_CODE",
  "transaction_time": "2025-07-09T05:22:11.380245"
}

Container No. Tracking Re-Registration Request – Response Body

Field	Type	Description	Notes
api_version	string	API version
content	ReEnrollResult	Re-Registration result
message	string	Server message	Available on request
transaction_time	string	Response timestamp	yyyy-MM-dd'T'HH:mm:ss.SSSSSS

ReEnrollResult

Field	Type	Size	Description
container_no	string	20	Container number
client	string	100	Customer company name
internal_usage	string	50	Customer contact name
reference_no	string	400	Reference number
carrier_code	string	5	Carrier code
track_mst_id	uuid	50	Unique shipment ID that can be obtained through shipment lookup

5. Retrieve Container No. Tracking Details

• Retrieve detailed information for Container No. Tracking
• Only successfully registered container no. tracking entries can be queried in detail.
• Date and time data within the content field follows the ISO 8601 format. yyyy-MM-dd'T'HH:mm:ssXXX

Request

GET /partners/track/v3/container-tracks

Query Parameter

Field	Type	Description
status	string	tracking status
register_from	string	Registration Start Date (ISO 8601 date/time format: yyyy-MM-dd'T'HH:mm:ssXXX)
register_to	string	Registration End Date (ISO 8601 date/time format: yyyy-MM-dd'T'HH:mm:ssXXX)
reference_no	string	Reference number
carrier_code	string	Carrier code
container_no	string	Container number
*page	number	Page number (minimum: 1)
*size	number	Page size (range: 1-50)

curl -X GET "https://api.tradlinx.com/partners/track/v3/container-tracks?container_no=[Container No]&register_from=[Register From]&register_to=[Register To]&reference_no=[Reference No]&carrier_code=[Carrier Code]&page=[Page]&size=[Size]" \
  -H "tx-clientid: [Client ID]" \
  -H "tx-apikey: [API Key]" \
  -H "Content-Type: application/json"

Response

{
  "api_version": "v3",
  "content": [
    {
      "container_no": "SAMPLE_CONTAINER_NO",
      "carrier_code": "SAMPLE_CARRIER_CODE",
      "client": "SAMPLE_CLIENT",
      "containers": [
        {
          "cntr_no": "SAMPLE_CNTR_NO",
          "cntr_sz": "SAMPLE_CNTR_SZ",
          "cntr_tp": "SAMPLE_CNTR_TP",
          "container_events": [
            {
              "event_datetime": "SAMPLE_EVENT_DATETIME",
              "event_type": "SAMPLE_EVENT_TYPE",
              "is_actual": false,
              "port_code": "SAMPLE_PORT_CODE",
              "transportation": "SAMPLE_TRANSPORTATION"
            }
          ],
          "seal_no": "SAMPLE_SEAL_NO"
        }
      ],
      "current_vessel": {
        "imo": "SAMPLE_IMO",
        "mmsi": "SAMPLE_MMSI",
        "vessel_name": "SAMPLE_VESSEL_NAME",
        "voyage": "SAMPLE_VOYAGE"
      },
      "detail_status": "SAMPLE_DETAIL_STATUS",
      "internal_usage": "SAMPLE_INTERNAL_USAGE",
      "origin": {
        "location_code": "SAMPLE_LOCATION_CODE",
        "location_name": "SAMPLE_LOCATION_NAME",
        "init_date_time": "2025-07-08T07:25:39+09:00",
        "estimate_date_time": "2025-07-08T07:25:39+09:00",
        "actual_date_time": "2025-07-08T07:25:39+09:00"
      },
      "pod": {
        "ata": "2025-07-09T05:32:47+09:00",
        "eta": "2025-07-09T05:32:47+09:00",
        "init_eta": "2025-07-09T05:32:47+09:00",
        "pod_code": "SAMPLE_POD_CODE",
        "pod_name": "SAMPLE_POD_NAME",
        "tx_ata": "2025-07-09T05:32:47+09:00"
      },
      "pol": {
        "atd": "2025-07-09T05:32:47+09:00",
        "etd": "2025-07-09T05:32:47+09:00",
        "init_etd": "2025-07-09T05:32:47+09:00",
        "pol_code": "SAMPLE_POL_CODE",
        "pol_name": "SAMPLE_POL_NAME",
        "tx_atd": "2025-07-09T05:32:47+09:00"
      },
      "destination": {
        "location_code": "SAMPLE_LOCATION_CODE",
        "location_name": "SAMPLE_LOCATION_NAME",
        "init_date_time": "2025-07-08T07:25:39+09:00",
        "estimate_date_time": "2025-07-08T07:25:39+09:00",
        "actual_date_time": "2025-07-08T07:25:39+09:00"
      },
      "reference_no": "SAMPLE_REFERENCE_NO",
      "registered_datetime": "2025-07-08T07:25:39.493Z",
      "remark": "SAMPLE_REMARK",
      "routes": [
        {
          "ata": "2025-07-09T05:32:47+09:00",
          "atd": "2025-07-09T05:32:47+09:00",
          "eta": "2025-07-09T05:32:47+09:00",
          "etd": "2025-07-09T05:32:47+09:00",
          "imo": "SAMPLE_IMO",
          "init_eta": "2025-07-09T05:32:47+09:00",
          "init_etd": "2025-07-09T05:32:47+09:00",
          "mmsi": "SAMPLE_MMSI",
          "order": 0,
          "pod_code": "SAMPLE_POD_CODE",
          "pod_name": "SAMPLE_POD_NAME",
          "pol_code": "SAMPLE_POL_CODE",
          "pol_name": "SAMPLE_POL_NAME",
          "tx_ata": "2025-07-09T05:32:47+09:00",
          "tx_atd": "2025-07-09T05:32:47+09:00",
          "vessel_name": "SAMPLE_VESSEL_NAME",
          "voyage": "SAMPLE_VOYAGE"
        }
      ],
      "status": "SAMPLE_STATUS",
      "track_mst_id": "SAMPLE_TRACK_MST_ID",
      "trans_type": "SAMPLE_TRANS_TYPE"
    }
  ],
  "message": "SAMPLE_ERROR_CODE",
  "pagination": {
    "current_page": 0,
    "has_next": false,
    "total_page": 0,
    "total_size": 0
  },
  "size": 1,
  "transaction_time": "2025-07-09T05:32:47.939106"
}

Response Body

Field	Type	Description	Notes
api_version	string	API version	v3
content	ContainerTrackDetail[]	Container No. tracking details
transaction_time	string	Response timestamp	yyyy-MM-dd'T'HH:mm:ss.SSSSSS
size	number	Content size
pagination	Pagination	Pagination information

Pagination

Field	Type	Description
total_size	number	Total number of data entries
total_page	number	Total number of pages
current_page	number	Current page number
has_next	boolean	If a next page exists

ContainerTrackDetail - Shipment Tracking Details

Field	Type	Description
track_mst_id	string	Shipment Tracking ID
carrier_code	string	Carrier code
container_no	string	Container number
reference_no	string	Reference number
client	string	Customer company name
internal_usage	string	Customer contact name
remark	string	Notes
registered_datetime	string	Registration date/time (yyyy-MM-dd'T'HH:mm:ssZ)
status	string	Tracking status (see list below)
detail_status	string	Tracking detail status (see list below)
trans_type	string	Import/Export Classification (see list below)
origin?	ExtraRoute	Place of origin (Data is available only for certain carriers) (see list below)
pol	POL	Port of Loading data
pod	POD	Port of Discharge data
destination?	ExtraRoute	Final destination (Data is available only for certain carriers) (see list below)
current_vessel	CurrentVessel	Current vessel information
routes	Route[]	List of route segments for the shipment
containers	Container[]	List of containers associated with the shipment

Tracking Status

Code	Description
PROCESSING	Tracking active
COMPLETE	Tracking completed
DELETED	Tracking deleted
PENDING	Tracking invalid

Tracking Detail Status

Code	Description
WAITING	Waiting
RETRYING	Retrying
RETRY_FAILED	Retry failed after 7 days
NOT_ENOUGH_CREDIT	Insufficient credits
UNSUPPORTED_PLAN	Unsupported plan
TRACKING	Tracking in progress
COMPLETE	Tracking completed
INCOMPLETE	Tracking expired
DELETED	Tracking deleted

Transshipment Type

Code	Description
DIRECT	Direct
TS	Transshipment

ExtraRoute - Origin/Destination Data

Field	Type	Description	Remark
location_name?	string	Location name
location_code?	string	Location code
init_date_time?	string	Initial date/time	[ISO 8601 date/time format] yyyy-MM-dd'T'HH:mm:ssXXX
estimate_date_time?	string	Estimate date/time	[ISO 8601 date/time format] yyyy-MM-dd'T'HH:mm:ssXXX
actual_date_time?	string	Actual date/time	[ISO 8601 date/time format] yyyy-MM-dd'T'HH:mm:ssXXX

POL - Port of Loading Data

Field	Type	Description	Notes
pol_name	string	Port of Loading name
pol_code	string	Port of Loading code
init_etd?	string	Initial ETD	[ISO 8601 date/time format]yyyy-MM-dd'T'HH:mm:ssXXX
etd?	string	ETD	[ISO 8601 date/time format]yyyy-MM-dd'T'HH:mm:ssXXX
atd?	string	ATD	[ISO 8601 date/time format]yyyy-MM-dd'T'HH:mm:ssXXX
tx_atd?	string	AIS based ATD	[ISO 8601 date/time format]yyyy-MM-dd'T'HH:mm:ssXXX

POD - Port of Discharge Data

Field	Type	Description	Notes
pod_name	string	Port of Discharge name
pod_code	string	Port of Discharge code
init_eta?	string	Initial ETA	[ISO 8601 date/time format]yyyy-MM-dd'T'HH:mm:ssXXX
eta?	string	ETA	[ISO 8601 date/time format]yyyy-MM-dd'T'HH:mm:ssXXX
ata?	string	ATA	[ISO 8601 date/time format]yyyy-MM-dd'T'HH:mm:ssXXX
tx_ata?	string	AIS based ATA	[ISO 8601 date/time format]yyyy-MM-dd'T'HH:mm:ssXXX

CurrentVessel

Field	Type	Description
imo	string	IMO
mmsi	string	MMSI
vessel_name	string	Vessel name
voyage	string	Voyage number

Route

Field	Type	Description	Notes
order	number	Route sequence
pol_name	string	Port of Loading name
pol_code	string	Port of Loading code
pod_name	string	Port of Discharge name
pod_code	string	Port of Discharge code
imo	string	Vessel IMO
mmsi	string	Vessel MMSI
vessel_name	string	Vessel name
voyage	string	Voyage number
init_etd?	string	Initial ETD	[ISO 8601 date/time format]yyyy-MM-dd'T'HH:mm:ssXXX
etd?	string	ETD	[ISO 8601 date/time format]yyyy-MM-dd'T'HH:mm:ssXXX
atd?	string	ATD	[ISO 8601 date/time format]yyyy-MM-dd'T'HH:mm:ssXXX
tx_atd?	string	AIS based ATD	[ISO 8601 date/time format]yyyy-MM-dd'T'HH:mm:ssXXX
init_eta?	string	Initial ETA	[ISO 8601 date/time format]yyyy-MM-dd'T'HH:mm:ssXXX
eta?	string	ETA	[ISO 8601 date/time format]yyyy-MM-dd'T'HH:mm:ssXXX
ata?	string	ATA	[ISO 8601 date/time format]yyyy-MM-dd'T'HH:mm:ssXXX
tx_ata?	string	AIS based ATA	[ISO 8601 date/time format]yyyy-MM-dd'T'HH:mm:ssXXX

Container

Field	Type	Description
cntr_no	string	Container number
cntr_sz	string	Container size
cntr_tp	string	Container type
seal_no	string	Container seal number
container_events	ContainerEvent[]	Container event data Array

ContainerEvent

Field	Type	Description	Notes
port_code	string	Port code
event_type	string	Container event types (see list below)
transportation	string	Transport types (see list below)
is_actual	boolean	Whether the event time is actual
event_datetime	string	Time of event occurrence	[ISO 8601 date/time format]yyyy-MM-dd'T'HH:mm:ssXXX

Container Event Types

Code	Description
CONTAINER_PICK_UP	Container pickup
LOADING_ON_VESSEL	Loading onto vessel
VESSEL_DEPARTURE_FROM_PORT	Vessel departure from port
VESSEL_ARRIVAL_AT_PORT	Vessel arrival at port
VESSEL_BERTHING_ON_PORT	Vessel berthing at port
DISCHARGING_FROM_VESSEL	Discharging from vessel
GATE_IN	Entering terminal or container yard
GATE_OUT	Exiting terminal or container yard
RAIL_LOADING	Loading onto train
RAIL_DEPARTURE	Train departure
RAIL_ARRIVAL	Train arrival
RAIL_UNLOADING	Unloading from train
PICKING_UP_BY_CONSIGNEE	Picked up by consignee
DELIVERING_TO_CONSIGNEE	Delivered to consignee
EMPTY_CONTAINER_RETURN	Container return

Transport Types

Code	Description
VESSEL	Vessel
FEEDER	Feeder vessel
BARGE	Barge
RAIL	Train
TRUCK	Truck

400 Error

{
  "error_detail": "[page]: The value of the field must be greater than or equal to 1.",
  "message": "SAMPLE_ERROR_CODE",
  "transaction_time": "2025-03-20T05:42:27.171506"
}

500 Error

{
  "status": 500,
  "type": "Internal Server Error",
  "message": "Internal server error. Please try again in a few minutes."
}