IQAX Shipment Tracking API

Overview

IQAX Shipment Tracking API provide trusted shipment tracking data with

1	Container events & route / vessel change with continuous ETA/ETD update of vessel schedule across carriers
2	Predictive ETA/ETD from proprietary machine learning model
3	Detected ATD & ATA from vessel AIS and advance geofencing technique
4	RESTful in conjunction with a Webhook method to access the update of shipment status via API

Additional Details:

IQAX Shipment Tracking API is maintained to ensure to provide accurate tracking data and service.

Check latest update here

Getting Started

Step 1

400

To get started, you must apply for a API subscription key from IQAX as each request to the interface requires a valid key to be provided.

Step 2

400

After acquiring subscription key, the first step will be to register the shipments into our system.

Once the shipments are registered, you will be able to acquire the shipment data directly through the API ranging from basic information such as container size type all the way to shipment route and events.
From now, every call to the Shipment Tracking API will require an HTTP header Ocp-Apim-Subscription-Key with the value set to one of your subscription key, otherwise, unauthorized errors will result.

Register shipment with API

Step 3

400

After registering shipment, it may take some time to get data.

You may check registered shipment data retrieval status with endpoint /shipment/registrations/registration-with-status under shipment registration
Only "Ready to Track" shipment returned positive result in Shipment Tracking API. Check all shipment registration status here

Step 4

400

According to business needs, choose the main interfacing method by application requirement. Shipment Tracking API provides two kinds of interface, a RESTful API in conjunction with a Webhook API.

RESTful API is a traditional pull-based interface where users/applications can register or browse their shipments by firing HTTP requests.

More details of shipment tracking restful API now.

Webhook API requires customers to host a long-running server exposed to the internet, which will receive timely updates of shipment from Shipment Tracking API.
For security measure, pre-setup of your callback URL(s) is required before enabling the push services.
Once all the setup is ready, you can make use of webhook API to create shipment webhook subscription.

You need to register shipment with register shipment API before creating webhook subscription for push service.

More details of shipment tracking webhook API .

Shipment Registration API

Description:

The gateway endpoint to register shipment for tracking by ocean carrier SCAC code and booking / bill of lading number

Before performing queries, be reminded that each client is assigned a rate limit for calling all the APIs. Rate limiting is defined as below, which:

Allowed 500 requests per minute. When client performed too many requests, they will receive a HTTP 429 Too Many Requests error

Explore The APIs

1	Click "Authorize 🔒", paste your key (e.g. dr212fa991d84374bbp6f0cef8d2ab5c) to the field, then click "Authorize".
2	Select an API, click "Try it out", input parameters, then click "Execute".

Track and Trace Sandbox

Response Status

Details

Error (e.g 400 and 404) will return with a corresponding HTTP status code with the same response body signature, which usually explain themselves:


  1
2
3
4
5

  {
    "message": "Error message",
    "status": "Response Status Code",
    "error": " Response Status "
}

Status Code	Status	Description
200	OK
400	Bad Request	The server could not understand the request due to invalid syntax. Usually it is parameter error, duplicate registration or business key conflict
401	Unauthorized	The request not be authorized.
500	Internal Server Error	The server has encountered a situation it does not know how to handle.

Status Code

Status

Description

200

OK

400

Bad Request

The server could not understand the request due to invalid syntax. Usually it is parameter error, duplicate registration or business key conflict

401

Unauthorized

The request not be authorized.

500

Internal Server Error

The server has encountered a situation it does not know how to handle.

Error Code

Common Error Responses by Code:

Status Code	Error Message
400	shipmentRegistrationCriteria:must not be blank
400	Unexpected error occurred, may be registration conflict. Please try again later.
400	JSON parse error: Unrecognized field \"xxxxxx\ ” xxxxx
400	Exceed the batch size, the registration data is only allowed up to 100
404	Can not find related registration with criteria.
400	Unexpected error occurred, may be registration conflict. Please try again later.
400	registrationFromDate and registrationToDate must not be null!
400	The shipment is not available for current booking number, please register with bl number for Maersk Group shipments.
404	Registration not found.
400	page size must be between 1 and 100
400	page numbers must start at 0

Getting Status for Your Registration

You may query registration status by endpoint /shipment/registrations/registration-with-status above. Below are the detailed explanation of possible value for status and remark.

Status:

Status	Description
PROCESSING	Registered shipment is processing or keeping in re-trigger capture within time range.
READY TO TRACK	Registered shipment has result and ready to track
NO RESULT	Registered shipment cannot be found from carrier
INCOMPLETE	Shipment are found from carrier but with incomplete information. Check Remark for details, system will automatically retry for 7 days.
ERROR	Failed to register shipment. Check Remark for details.

Status

Description

PROCESSING

Registered shipment is processing or keeping in re-trigger capture within time range.

READY TO TRACK

Registered shipment has result and ready to track

NO RESULT

Registered shipment cannot be found from carrier

INCOMPLETE

Shipment are found from carrier but with incomplete information. Check Remark for details, system will automatically retry for 7 days.

ERROR

Failed to register shipment. Check Remark for details.

Remark:

Remark	Description
MISSING CONTAINER SLOT	Returned result does not contain any containers
ALL CONTAINERS MISSING OCEAN LEG	The shipment route information is unavailable for all containers
SOME CONTAINERS MISSING OCEAN LEG	The shipment route information is unavailable for some containers
REGISTERED CONTAINER NOT IN CAPTURE RESULT	Registered container is not found from the returned result
REGISTERED CONTAINER MISSING OCEAN LEG	The shipment route information is unavailable for the registered container
REGISTERED SHIPMENT ENCOUNTERED ISSUE WHEN FETCHING DATA	System will automatically retry for 7 days and set "No result" in "Status".
SCAC CODE NOT DEFINED IN CUSTOMER PROFILE	Unsupported carrierSCAC code is in used.

Remark

Description

MISSING CONTAINER SLOT

Returned result does not contain any containers

ALL CONTAINERS MISSING OCEAN LEG

The shipment route information is unavailable for all containers

SOME CONTAINERS MISSING OCEAN LEG

The shipment route information is unavailable for some containers

REGISTERED CONTAINER NOT IN CAPTURE RESULT

Registered container is not found from the returned result

REGISTERED CONTAINER MISSING OCEAN LEG

The shipment route information is unavailable for the registered container

REGISTERED SHIPMENT ENCOUNTERED ISSUE WHEN FETCHING DATA

System will automatically retry for 7 days and set "No result" in "Status".

SCAC CODE NOT DEFINED IN CUSTOMER PROFILE

Unsupported carrierSCAC code is in used.

Paging

Paging is available for Fetch All Shipment Registrations and Fetch Registrations Status

Default page = 0, and the page number starts from 0

Default size = 100, system accepting input between 1-100

Shipment Tracking Restful API

Description:

The gateway endpoint returns the shipment tracking result by carrier SCAC code together with either booking / bill of lading number [and container number].

Before performing queries, be reminded that each client is assigned a rate limit for calling all the APIs. Rate limiting is defined as below, which:

Allowed 500 requests per minute. When client performed too many requests, they will receive a HTTP 429 Too Many Requests error

Explore The APIs

1	Click "Authorize 🔒", paste your key (e.g. dr212fa991d84374bbp6f0cef8d2ab5c) to the field, then click "Authorize".
2	Select an API, click "Try it out", input parameters, then click "Execute".

Track and Trace Sandbox

When event timestamp as 00:00:00 and GMT as null , it refers to the case which the local time is not available.

Example


  1
2
3
4
5
6
7
8
9

  "pointSequence": 1,
"eventCode": "MTY_PICKUP",
"eventDescription": "Empty equipment dispatched",
"eventStatus": "ACTUAL",
"eventDT": {
        "locDT": "2023-03-17T00:00:00" ,
        "timeZone": "Europe/Amsterdam",
        "GMT": "null"
}

Response Status

Details

Error (e.g 400 and 404) will return with a corresponding HTTP status code with the same response body signature, which usually explain themselves:


  1
2
3
4
5

  {
    "message": "Error message",
    "status": "Response Status Code",
    "error": " Response Status "
}

Status Code	Status	Description
200	OK
204	No Content	Registration record is found but no result yet.
400	Bad Request	The server could not understand the request due to invalid syntax. Usually it is parameter error, duplicate registration or business key conflict
401	Unauthorized	The request not be authorized.
404	Not Found	The server cannot find the requested resource.
500	Internal Server Error	The server has encountered a situation it does not know how to handle.

Status Code

Status

Description

200

OK

204

No Content

Registration record is found but no result yet.

400

Bad Request

The server could not understand the request due to invalid syntax. Usually it is parameter error, duplicate registration or business key conflict

401

Unauthorized

The request not be authorized.

404

Not Found

The server cannot find the requested resource.

500

Internal Server Error

The server has encountered a situation it does not know how to handle.

Error Code

Common Error Responses by Code:

Status Code	Error Message
400	JSON parse error: Unrecognized field \"xxxxxx\ ” xxxxx
400	Exceed the batch size, the number of containers is only allowed up to 100.
404	Can not find related registration with criteria.
404	Registration not found.

Shipment Tracking Webhook API

For security measure, a pre-setup of your callback URL(s) is required to enable the push services, Please contact us by customerservices@iqax.com before you plan to start the connectivity test.

Explore The APIs

1	Click "Authorize 🔒", paste your key (e.g. dr212fa991d84374bbp6f0cef8d2ab5c) to the field, then click "Authorize".
2	Select an API, click "Try it out", input parameters, then click "Execute".

Track and Trace Sandbox

When event timestamp as 00:00:00 and GMT as null , it refers to the case which the local time is not available.

Example


  1
2
3
4
5
6
7
8
9

  "pointSequence": 1,
"eventCode": "MTY_PICKUP",
"eventDescription": "Empty equipment dispatched",
"eventStatus": "ACTUAL",
"eventDT": {
        "locDT": "2023-03-17T00:00:00" ,
        "timeZone": "Europe/Amsterdam",
        "GMT": "null"
}

Response Status

Details

Error (e.g 400 and 404) will return with a corresponding HTTP status code with the same response body signature, which usually explain themselves:


  1
2
3
4
5

  {
    "message": "Error message",
    "status": "Response Status Code",
    "error": " Response Status "
}

Status Code	Status	Description
200	OK
400	Bad Request	The server could not understand the request due to invalid syntax. Usually it is parameter error, duplicate registration or business key conflict
401	Unauthorized	The request not be authorized.
404	Not Found	Shipment Registration is not found.
500	Internal Server Error	The server has encountered a situation it does not know how to handle.

Status Code

Status

Description

200

OK

400

Bad Request

The server could not understand the request due to invalid syntax. Usually it is parameter error, duplicate registration or business key conflict

401

Unauthorized

The request not be authorized.

404

Not Found

Shipment Registration is not found.

500

Internal Server Error

The server has encountered a situation it does not know how to handle.

Error Code

Common Error Responses by Code:

Status Code	Error Message
400	shipmentWebhookCriteria:must not be blank
400	Webhook already exists.
400	The callback URL is not valid.
400	Failed to connect callback endpoint: error on post request for +webhook.getCallbackURL()
400	Failed to connect callback endpoint: cannot get response with 2xx successful or 400 bad request.
400	Inconsistent with the registered secret.
400	JSON parse error: Unrecognized field \"xxxxxx\ ” xxxxx
404	Can not find related subscription with criteria.
404	Registration not found.

Action Status

Shipment updated events are detected Route and Event change. Action Type will be indicted as: NEW / UPDATE / DELETE for Event changes and UPDATE for Route changes.

Action	Description
UPDATE	Updated event/route/message
NEW	New event/message
DELETE	Deleted event

Action

Description

UPDATE

Updated event/route/message

NEW

New event/message

DELETE

Deleted event

A full set message will be pushed to Webhook client server once captured result is available after shipment registration. Action Type at the first time will be indicated as "NEW", on-going update will be marked as "UPDATE".

The Webhook client server should only return HTTP status code 200 to indicate a successful reception. Other responses will be regarded as failures.

Client Server Verification and Confirmation

Upon the creation of a Webhook, the API server will immediately fire an event callback to the designated URL with no events (i.e., the request body is []), client server should return HTTP code 200 as to confirm and verify a healthy connection for both parties. Otherwise this endpoint will fail.

Before fire event to client server, the API server will use sha1 and sha256 to encrypt the secret if the webhook registration includes secret.
The API server will pass the encrypted secret when callback to the designated URL, if the client server validates the encrypted secret, then return 200 to let the API server know the Webhook is already established.

Shipment Updated Event Timing

Only when shipment route/event change happens with a Webhook enabled, the change will be regarded as an event pending to be sent. There is no way to get notified when shipment route/event is updated without any available Webhook connection.

Error and Recovery

Events that happen while the Webhook is disabled will not be actively pushed to the client, even when client recovers and recreate the Webhook.

Clients could use the RESTful API to retrieve all shipments to maintain their data, but no event history could be provided.

Security

A web server exposed to the public internet that can respond to Webhook calls correctly is required to establish a working Webhook. Since the client server prone to attacks, following the security measures is strongly advised.

You are recommended to whitelist our server IP addresses while denying all external request to prevent potentially harmful threats or inappropriate access to your server. Please contact us by customerservices@iqax.com if you have applied this cybersecurity strategy for our IP segments.

Webhook creation requires an HTTPS callback endpoint, this is done to prevent leakage of information throughout the network channel.

Integrity Verification

As clients are exposed to the internet, malicious calls may reach clients' server, the secret key attached in the Webhook callback’s X-DHST-Signature and X-DHST-Signature-256 header, and can be used to ensure the caller’s identity, the integrity of the payload and prevent replay attacks.

Example:

1	Client server received webhook POST request at registered URI with header X-DHST-Signature-256: 4F89C033B5EE1A094B6F16B5F315FE7CE180FD1512D9AB031848472E150095C0
2	Client server previously subscribe webhook with secret key (from /webhook/shipment APIs 's secret field): api_token
3	Client server MUST verify that the DHST-Signature-256 in header should be same as encrypted secret, otherwise it’s highly likely to receive malicious requests.
4	https://en.wikipedia.org/wiki/SHA-2 have an introduction about the principles of encryption.

Supported Carriers

IQAX Shipment Tracking API supports a list of major Ocean Carriers, you will also need to provide carrierScac when you register a shipment for tracking via API.

Unless specified, You may register a shipment by BL number or Booking number.

If you find any carrier which is important to your business but not yet supported, we could help to recommend different options according to your use cases. Please get in touch with us at customerservices@iqax.com.

Untitled

Ocean Carrier	SCAC code	BL Registration	BKG Registration
ANL Container Line 澳航	ANNU	✓	✓
CK Line 天敬海运	CKLU	✓	✓
CMA-CGM 法国达飞	CMDU	✓	✓
CNC Line 正利	CHNL	✓	✓
COSCO SHIPPING Lines 中远海	COSU	✓	✓
Emirates 阿联酋	ESPU	✓	✓
Evergreen Line 长荣海运	EGLV	✓	✓
Gold Star Line 金星	GOSU	✓	✕
Hapag-Lloyd 赫伯罗特	HLCU	✓	✓
Heung-a 兴亚	11QU	✓	✓
Hyundai 现代	HDMU	✓	✓
Interasia Lines 运达	12AT	✓	✕
KMTC 高丽	KMTC	✓	✓
Maersk 马士基	MAEU	✓	✕
MCC MCC运输	MCCQ	✓	✕
MSC 地中海航运	MSCU	✓	✓
Namsung 南星海运	NSRU	✓	✓
Ocean Network Express 海洋网联	ONEY	✓	✓
OOCL 东方海外	OOLU	✓	✓
PIL 太平	PABV	✓	✓
Regional Container Lines (RCL) 宏海	RCLU	✓	✓
Sealand 海陸	SEAU	✓	✕
Shanghai Jinjiang 锦江	11WJ	✓	✕
Sinokor 长锦	SKLU	✓	✕
Sinotrans 中外运	12IH	✓ (Container# is required)	✕
SITC 海丰	12PD	✓	✕
Swire Shipping 太古船务	CHVW	✓	✓
TS Line 德祥	13DF	✓	✕
Wan Hai 万海	WHLC	✓	✓
Yang Ming Line 阳明	YMJA	✓	✓
Zim Lines 以星	ZIMU	✓	✓

Ocean Carrier

SCAC code

BL Registration

BKG Registration

ANL Container Line 澳航

ANNU

✓

CK Line 天敬海运

CKLU

✓

CMA-CGM 法国达飞

CMDU

✓

CNC Line 正利

CHNL

✓

COSCO SHIPPING Lines 中远海

COSU

✓

Emirates 阿联酋

ESPU

✓

Evergreen Line 长荣海运

EGLV

✓

Gold Star Line 金星

GOSU

✓

✕

Hapag-Lloyd 赫伯罗特

HLCU

✓

Heung-a 兴亚

11QU

✓

Hyundai 现代

HDMU

✓

Interasia Lines 运达

12AT

✓

✕

KMTC 高丽

KMTC

✓

Maersk 马士基

MAEU

✓

✕

MCC MCC运输

MCCQ

✓

✕

MSC 地中海航运

MSCU

✓

Namsung 南星海运

NSRU

✓

Ocean Network Express 海洋网联

ONEY

✓

OOCL 东方海外

OOLU

✓

PIL 太平

PABV

✓

Regional Container Lines (RCL) 宏海

RCLU

✓

Sealand 海陸

SEAU

✓

✕

Shanghai Jinjiang 锦江

11WJ

✓

✕

Sinokor 长锦

SKLU

✓

✕

Sinotrans 中外运

12IH

✓ (Container# is required)

✕

SITC 海丰

12PD

✓

✕

Swire Shipping 太古船务

CHVW

✓

TS Line 德祥

13DF

✓

✕

Wan Hai 万海

WHLC

✓

Yang Ming Line 阳明

YMJA

✓

Zim Lines 以星

ZIMU

✓

Supported Event

Event Model:

Event Code	Description
MTY_PICKUP	Empty Container Picked Up
CNTR_RCVD	Full container Received by Carrier
CNTR_DEPARTURE	Container Depart from Facility
CNTR_ARRIVAL	Container Arrive at Facility
VSL_DEPARTURE	Vessel Departure
VSL_ARRIVAL	Vessel Arrival
CNTR_DISCHARGE	Discharged from Vessel
CNTR_PICKUP	Container to Consignee
CNTR_LOAD	Loaded on Board
CNTR_LOAD_ON_TRUCK	Loaded on Truck
CNTR_LOAD_ON_RAIL	Loaded on Rail
CNTR_LOAD_ON_BARGE	Loaded on Barge
CNTR_LOAD_ON_FEEDER	Loaded on Feeder
CNTR_DISCHARGE_FROM_TRUCK	Container Discharged from Truck
CNTR_DISCHARGE_FROM_RAIL	Container Discharged from Rail
CNTR_DISCHARGE_FROM_BARGE	Container Discharged from Barge
CNTR_DISCHARGE_FROM_FEEDER	Container Discharged from Feeder
MTY_RETURN	Empty Container Return to Depot

Event Code

Description

MTY_PICKUP

Empty Container Picked Up

CNTR_RCVD

Full container Received by Carrier

CNTR_DEPARTURE

Container Depart from Facility

CNTR_ARRIVAL

Container Arrive at Facility

VSL_DEPARTURE

Vessel Departure

VSL_ARRIVAL

Vessel Arrival

CNTR_DISCHARGE

Discharged from Vessel

CNTR_PICKUP

Container to Consignee

CNTR_LOAD

Loaded on Board

CNTR_LOAD_ON_TRUCK

Loaded on Truck

CNTR_LOAD_ON_RAIL

Loaded on Rail

CNTR_LOAD_ON_BARGE

Loaded on Barge

CNTR_LOAD_ON_FEEDER

Loaded on Feeder

CNTR_DISCHARGE_FROM_TRUCK

Container Discharged from Truck

CNTR_DISCHARGE_FROM_RAIL

Container Discharged from Rail

CNTR_DISCHARGE_FROM_BARGE

Container Discharged from Barge

CNTR_DISCHARGE_FROM_FEEDER

Container Discharged from Feeder

MTY_RETURN

Empty Container Return to Depot

By default, API provides "Unify" version, but it also offers an option to filter particular version(s) to fulfill your usecase.

Version	Definition	Param for version	Recommend Scenarios
Unify	Return a combined version of booking carrier’s route and harmonized ETA (include predictive ETA) from ML model as well as detected ATA from AIS	UNI	Require most updated tracking data
Standard	Return raw route and events from booking carrier	STD	Require data from booking carrier only
Advance	Return enhanced route from multi sources and advanced event (like predictive ETA) from ML model	ADV	Require routing and ETA suggested by ML model
Default	Return Unify version	Not Specify

Version

Definition

Param for version

Recommend Scenarios

Unify

Return a combined version of booking carrier’s route and harmonized ETA (include predictive ETA) from ML model as well as detected ATA from AIS

UNI

Require most updated tracking data

Standard

Return raw route and events from booking carrier

STD

Require data from booking carrier only

Advance

Return enhanced route from multi sources and advanced event (like predictive ETA) from ML model

ADV

Require routing and ETA suggested by ML model

Default

Return Unify version

Not Specify

Choose between STD and ADV version for your usecase:

Consider the following scenario:

1	A shipment from Rotterdam to Al' Aqabah, booking carrier is indicating the container is travelling on CMA CGM VASCO DE GAMA with direct route in their website now.
2	Digital Twins consider schedule from multiple carriers and live vessel location, it detects CMA CGM VASCO DE GAMA is going to skip Al’ Aqabah. It suggests the container is going to T/S port in Jeddah and connect Al’ Aqabah with COSCO SHIPPING KILIMANJARO

Standard Version

Advance Version

1000

Always contains shipment route, container milestone and schedule from booking carrier at the moment

which may contain

1	Enriched shipment route and vessel recommendation ( e.g additional T/S port in Jeddah and vessel recommendation of COSCO SHIPPING KILIMANJARO in this example )
2	or Assoicate vessel schedule from multiple carriers which mentioned schedule for the schedule
3	or Predictive ETA/ETD