Getting started with the Container Tracking API
The Safecube Container Tracking API returns the tracking data of a maritime shipment from a single identifier: a container number, a bill of lading number or a booking number. One endpoint, GET /shipment, returns the shipment status, its ports of loading and discharge with estimated and actual dates, the vessels involved, every container event and the route of the shipment. The API covers more than 170 shipping lines.
Authenticate your requests
Every Container Tracking API request is authenticated with a Safecube API key, sent in a header named API_KEY.
- Get an API key — create a Safecube account, for free or with a paid plan, at
https://safecube.ai/sign-up/. - Find your API key — the key is displayed in the Safecube web application at
https://app.safecube.ai/api/credentials: open Developers in the sidebar, then the API Credentials tab. - Send your API key — add the header
API_KEY: <your API key>to every request, with noBearerprefix.
The Authentication page details the API key, its rotation and the mandatory HTTP headers.
Shipping line coverage
The Container Tracking API covers the tracking data of more than 170 shipping lines and freight forwarders. The endpoint GET /sealines returns the up-to-date list, with the SCAC codes of each line, the shipment types it accepts and whether it is under maintenance:
{
"sealines": [
{
"name": "AC Container Line",
"active": true,
"activeTypes": { "ct": true, "bl": true, "bk": true },
"maintenance": false,
"scacCodes": ["ALRB"],
"prefixes": []
}
]
}
Most shipping lines accept container (CT), bill of lading (BL) and booking (BK) numbers, but some accept only part of them: activeTypes gives the accepted types per line. The Supported shipping lines page lists every line with its SCAC codes.
Track your first shipment
The endpoint GET /shipment takes the shipment to track as query parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
shipmentNumber | string | Yes | Container number, bill of lading number or booking number. |
shipmentType | enum | No | CT for a container, BL for a bill of lading, BK for a booking. Autodetected when absent. |
sealine | string | No, but recommended | SCAC code of the shipping line. Specifying it shortens the response time and avoids a wrong shipping line detection. |
route | boolean | No, true by default | Returns the route segments: the array of coordinates following the path of the shipment from POL to POD. Set to false for a lighter payload and a faster response. |
ais | boolean | No, true by default | Returns the AIS data of the vessel when available. Works only when route is also true. |
The request below tracks the free test shipment ZZZZ0000000, which costs nothing to query:
curl "https://api.sinay.ai/container-tracking/api/v2/shipment?shipmentNumber=ZZZZ0000000&shipmentType=CT" \
-H "API_KEY: $SAFECUBE_API_KEY"
The Sandbox and test shipments page lists the other free test shipments, including ones that return errors or evolve every day.
Understand the response
A GET /shipment response is made of seven blocks: metadata, locations, route, facilities, vessels, containers and routeData. The excerpts below show one block each, taken from real responses and shortened. The GET /shipment reference documents the complete schema, field by field.
metadata
metadata holds the generic information on the shipment:
shipmentTypeandshipmentNumberecho the tracked shipment,shipmentTypebeing autodetected when the request does not set it;sealineandsealineNameidentify the shipping line, by SCAC code and by name;shippingStatusis the short status of the shipment:PLANNED,IN_TRANSIT,DELIVEREDorUNKNOWN;updatedAtis the time the data was last received from the shipping line.
{
"metadata": {
"shipmentType": "CT",
"shipmentNumber": "FANU1172910",
"sealine": "HLCU",
"sealineName": "Hapag-Lloyd",
"shippingStatus": "IN_TRANSIT",
"updatedAt": "2023-11-27T22:55:48Z"
}
}
locations
locations lists every location involved in the transport of the shipment: port of loading (POL), port of discharge (POD), transhipment ports and inland locations, in chronological order. Each location carries its name, country, UN/LOCODE, coordinates and time zone. The role of each location — POL, POD or other — is given by the route block.
{
"locations": [
{
"name": "Antwerp",
"state": "Flanders",
"country": "Belgium",
"countryCode": "BE",
"locode": "BEANR",
"coordinates": { "lat": 51.22047, "lng": 4.40026, "updatedAt": null },
"timezone": "Europe/Brussels"
},
{
"name": "Charleston",
"state": "South Carolina",
"country": "United States",
"countryCode": "US",
"locode": "USCHS",
"coordinates": { "lat": 32.77657, "lng": -79.93092, "updatedAt": null },
"timezone": "America/New_York"
}
]
}
route
route gives the key locations of the shipment and their dates: prepol (place of dispatch), pol (port of loading), pod (port of discharge) and postpod (destination).
datecan be estimated or actual, asactualtells. The date atpolis the ETD and the date atpodis the ETA.predictiveEtais provided for the POD only, when the container is within 3 days of its arrival. Safecube computes it from historical AIS data, live port congestion and weather data; it does not come from the shipping line.- A location the shipping line does not provide is
null, aspostpodin the excerpt below.
{
"route": {
"pol": {
"location": { "name": "Antwerp", "countryCode": "BE", "locode": "BEANR" },
"date": "2023-11-07T17:38:00Z",
"actual": true,
"predictiveEta": null
},
"pod": {
"location": { "name": "Charleston", "countryCode": "US", "locode": "USCHS" },
"date": "2023-11-27T13:18:00Z",
"actual": true,
"predictiveEta": null
},
"postpod": {
"location": null,
"date": null,
"actual": null,
"predictiveEta": null
}
}
}
In the excerpt, the location objects are shortened: in a response, each one carries the same fields as an entry of locations.
facilities
facilities lists the facilities associated with the locations of the shipment — terminals, depots — when the shipping line provides them. Each facility carries its name, country code, UN/LOCODE, BIC and SMDG codes, and coordinates. The same object appears in the facility field of a container event.
{
"facilities": [
{
"name": "Houston Barbours Cut Terminal",
"countryCode": "US",
"locode": "USUQF",
"bicCode": "USUQFGDQQ",
"smdgCode": null,
"coordinates": { "lat": null, "lng": null, "updatedAt": null }
}
]
}
vessels
vessels lists every vessel involved in the transport of the shipment, in chronological order, with its name, IMO number, call sign, MMSI and flag.
{
"vessels": [
{
"name": "MISSOURI EXPRESS",
"imo": 9349552,
"callSign": "WDM2203",
"mmsi": 367781000,
"flag": "US"
}
]
}
containers
containers holds, for each container of the shipment, its number, ISO type code, status and list of events.
- Each event has an
eventType, aneventCodeand astatus— gate in, gate out, loaded, discharged — with a date, a location and, at sea, a vessel and a voyage number. isActualtells whether the event date is actual or estimated.- New events are added along the journey of the shipment: calling the API regularly is what keeps the tracking data up to date.
{
"containers": [
{
"number": "FANU1172910",
"isoCode": "45G1",
"status": "IN_TRANSIT",
"events": [
{
"location": { "name": "Woerth am Rhein", "countryCode": "DE", "locode": "DEWOE" },
"facility": null,
"description": "Gate out empty",
"eventType": "EQUIPMENT",
"eventCode": "GTOT",
"status": "CEP",
"date": "2023-10-27T09:17:00Z",
"isActual": true,
"isAdditionalEvent": false,
"routeType": "LAND",
"transportType": "TRUCK",
"vessel": null,
"voyage": null
}
]
}
]
}
The Status and event codes page lists every event type, event code and status.
routeData
routeData is returned when the route parameter is true.
routeSegmentsis a succession of paths, each an array of coordinates with arouteType(SEAorLAND), drawing a possible route of the shipment from POL to POD.coordinatesis the current position of the shipment: the position of the vessel when the container is on board, otherwise the last known location of the container.aisholds the AIS data of the vessel — last vessel position, last event — when theaisparameter is alsotrue.
{
"routeData": {
"routeSegments": [
{
"path": [
{ "lat": 29.76328, "lng": -95.36327, "updatedAt": null },
{ "lat": 53.551052, "lng": 8.570912, "updatedAt": null },
{ "lat": 53.53615, "lng": 8.59298, "updatedAt": null }
],
"routeType": "SEA"
}
],
"coordinates": { "lat": 47.08643, "lng": -11.237754 }
}
}
The Shipment location and Shipment route pages explain how to use routeData to locate a shipment and draw its route on a map.
Best practices
These practices improve the response time of the Container Tracking API, the quality of its data and the cost of tracking.
Track by bill of lading
Tracking a shipment by its bill of lading number is charged as one shipment, whatever the number of containers under that bill of lading. Track by bill of lading whenever the number is available.
Specify the shipping line
Set the sealine parameter to the SCAC code of the shipping line whenever it is known. The response is faster and often more complete. Without it, the API autodetects the shipping line, and the autodetection can fail even when the shipment number is valid.
Retry failed requests
504timeout — when fetching the data from the shipping line takes too long, the API cancels the request and answers504. Retry within 60 minutes: the data will then be available in the Safecube cache.200withSEALINE_HASNT_PROVIDE_INFO— the shipping line found nothing for the shipment yet. Retry later: most of these requests return results once the shipping line publishes the data.
Poll regularly
The Container Tracking API collects its data from several sources, including the shipping lines directly, and refreshes it every 6 to 24 hours depending on the source. Calling the API every 6 hours for a shipment keeps its data as accurate as possible.
For a large number of shipments, the Safecube Webhooks API sends tracking updates to your own endpoint as soon as they are available, instead of polling. The Getting started with webhooks page shows how to set them up.
Handle errors
When a request fails, retry it, and set the optional parameters you know — the sealine SCAC code above all. The Error codes page lists every error returned by the Container Tracking API, its meaning and whether the request is charged.