Container tracking API – Overview
Sinay’s Container tracking API allows you to track your shipments by retrieving your container location, eta and events.
Sinay retrieves information from the shipping line, and transmits it in a standard format, so that you don’t have to. To give you access to your container location, we retrieve the vessel position via satellite AIS.
For each endpoint, you will be requested to input either a container number or a document id in order to identify the container you are looking for. If you are not familiar with container numbers, we suggest to use the corresponding BL or BK endpoints, which will allow you to track your shipment based on the Booking number or Bill of Lading.
Authentication and Headers
Sinay ETAC API uses the same API Framework as all the other Sinay APIs. Authorization is completed via an API key that is added to the API request header.
To know more about Sinay APIs authorization and headers, follow <insert doc link>
Call frequency recommendation
Shipping lines usually update their data every 12 to 24h. Therefore, we recommend updating every day the data retrieved via the endpoints /events /eta and /status.
Vessel location does change much faster, and our satellite AIS data is refreshed at least every 30min. Therefore, we recommend updating data retrieved via our /location endpoint every 3 to 6 hours.
Endpoints
GET /eta/container
This endpoint is used to retrieve the eta of a given container. It will return both the ETA at the next port of discharge and at the last port of discharge. If there are no expected transshipments, next and last will return the same value.
Request
You must specify the container number as a query parameter. A container number is a unique combination of four letters followed by seven numbers for identifying containers internationally.
Response
The response will remind you of the container id, and either show ETA for the next port of discharge and for the port of Arrival (if the ETA is in the future), or display the following message “Container has already arrived at his final port of destination” (if the container has already arrived).
//example of response when the container is underway
{
"containerId": "MEDU5897970",
"lastEvent": {
"code": "CLL",
"text": "Export Loaded on Vessel",
"portCode": "CNNGB",
"location": "Ningbo",
"date": "2023-03-12T00:00:00Z"
},
"nextEvent": {
"code": "VAD",
"text": "Estimated Time of Arrival",
"portCode": "BEANR",
"location": "Antwerp",
"date": "2023-04-15T00:00:00Z"
}
}
//example of response when the container has already arrived
{
"containerId": "FANU1172910",
"nextPortArrival": null,
"lastPortArrival": null,
"complementaryMessage": "The container has already arrived at his final port destination"
}
For each event, you will find
- the Date and Time of discharge in standard UTC format (find here the corresponding documentation https://www.w3.org/TR/NOTE-datetime-970915.html)
- the UN/LOCODE of the port (find here the UN/LOCODE documentation https://unece.org/trade/cefact/unlocode-code-list-country-and-territory).
The ETA we return is the expected time of arrival at the transshipment or discharge port. If no vessel arrival events are returned by the shipping line, we return the expected time of container transshipment or discharge.
GET /eta/blorbk
This endpoint is used to retrieve the ETA of every container in a given booking or bill of lading. For each container, it will return both the ETA at the next port of discharge and at the last port of discharge. If there are no expected transshipments, next and last will return the same value.
Request
You must specify, as query parameters, the following inputs :
- Document type : 2 letters depending of the document type you wish to track : BL for Bill of Lading, and BK for Booking number
- Document number : depending on the document type, either the booking number (usually two letters plus six numbers) or the bill of lading number (ten digits number)
- Sealine code : 4 characters uniquely identifying the sealine. Use or GET /sealines endpoint to retrieve the complete list of supported sealines.
Response
The response will show you a list, each element of the list giving you the container id and the ETA for the next port of discharge and for the port of Arrival, for each container in the booking or on the Bill of Lading.
//example of response when container can be located
{
"containerId": "FANU1172910",
"location": {
"longitude": -0.39362358826455934,
"latitude": 49.20156472251085
}
}
//example of response when container cannot be located (not at sea anymore)
{
"containerId": "FANU1172910",
"location": null
}
GET /location/blorbk
This endpoint is used to retrieve the locations of every container in a given booking or bill or lading on the given sealine. Depending on the location of the container (at a port or onboard a ship), it will return the latitude and longitude of the last known position of the vessel or the one of the port.
It will not be able to give you a position of the container is neither onboard a ship or in a port.
Request
You must specify, as query parameters, the following inputs :
- Document type : 2 letters depending of the document type you wish to track : BL for Bill of Lading, and BK for Booking number
- Document number : depending on the document type, either the booking number (usually two letters plus six numbers) or the bill of lading number (ten digits number)
- Sealine code : 4 characters uniquely identifying the sealine. Use or GET /sealines endpoint to retrieve the complete list of supported sealines.
Response
The response will be a list of container locations, for each container it will give you the container id and its latitude and longitude.
[
{
"containerId": "TCLU8738299",
"location": {
"longitude": 8.779871940612793,
"latitude": 44.41938781738281
}
}
]
GET /status/container
This endpoint is used to retrieve the status of a given container. It will return both the last event and the next event of the container.
Request
You must specify the container number as a query parameter. A container number is a unique combination of four letters followed by seven numbers for identifying containers internationally.
Response
In the response, you will find a reminder of the container id you entered, and the last event and next event data for this container.
//example of response when container has not arrived yet
{
"containerId": "FANU1172910",
"lastEvent": {
"code": "CER",
"text": "Gate in empty",
"portCode": "FRBOD",
"location": "Antwerp",
"date": "2023-04-11T10:33:00Z"
},
"nextEvent": {
"code": "CER",
"text": "Gate in empty",
"portCode": "FRBOD",
"location": "Antwerp",
"date": "2023-04-15T17:33:00Z"
}
}
//example of response when container voyage is fully completed (last event in the past)
{
"containerId": "FANU1172910",
"lastEvent": {
"code": "CER",
"text": "Gate in empty",
"portCode": "KRSEL",
"location": "Seoul",
"date": "2023-04-11T10:33:00Z"
},
"nextEvent": null
}
In each event you will find :
- The event code
- The event text (a translation of the code in simple text)
- The location in plain text
- The port code (find here the UN/LOCODE documentation https://unece.org/trade/cefact/unlocode-code-list-country-and-territory). This field can be null if the shipping line hasn’t specified it. In this case please refer to the location field.
- And the timestamp of the event in standard UTC format (find here the corresponding documentation https://www.w3.org/TR/NOTE-datetime-970915.html)
GET /status/blorbk
Request
You must specify, as query parameters, the following inputs :
- Document type : 2 letters depending of the document type you wish to track : BL for Bill of Lading, and BK for Booking number
- Document number : depending on the document type, either the booking number (usually two letters plus six numbers) or the bill of lading number (ten digits number)
- Sealine code : 4 characters uniquely identifying the sealine. Use or GET /sealines endpoint to retrieve the complete list of supported sealines.
Response
In the response, you will find the list of events for all containers in your document. For each container, you will find the container id, and the last event and next event data for this container.
//example of response when container has not arrived yet
[
{
"containerId": "FANU1172910",
"lastEvent": {
"code": "CER",
"text": "Gate in empty",
"portCode": "FRBOD",
"location": "Antwerp",
"date": "2023-04-11T10:33:00Z"
},
"nextEvent": {
"code": "CER",
"text": "Gate in empty",
"portCode": "FRBOD",
"location": "Antwerp",
"date": "2023-04-15T17:33:00Z"
}
}
]
//example of response when container voyage is fully completed (last event in the past)
[
{
"containerId": "FANU1172910",
"lastEvent": {
"code": "CER",
"text": "Gate in empty",
"portCode": "KRSEL",
"location": "Seoul",
"date": "2023-04-11T10:33:00Z"
},
"nextEvent": null
}
]
In each event you will find :
- The event code
- The event text (a translation of the code in simple text)
- The location in plain text
- The port code (find here the UN/LOCODE documentation https://unece.org/trade/cefact/unlocode-code-list-country-and-territory). This field can be null if the shipping line hasn’t specified it. In this case please refer to the location field.
- And the timestamp of the event in standard UTC format (find here the corresponding documentation https://www.w3.org/TR/NOTE-datetime-970915.html)
GET /events/container
This endpoint is used to retrieve all events of a given container, in the past of the future.
Request
You must specify the container number as a query parameter. A container number is a unique combination of four letters followed by seven numbers for identifying containers internationally.
Response
The response will give you a reminder of the container id you entered, and a list of events for this container.
{
"containerId": "MEDU5897970",
"events": [
{
"code": "CEP",
"text": "Empty to Shipper",
"portCode": "CNNGB",
"location": "Ningbo",
"date": "2023-03-04T00:00:00Z"
},
{
"code": "CGI",
"text": "Export received at CY",
"portCode": "CNNGB",
"location": "Ningbo",
"date": "2023-03-04T00:00:00Z"
},
{
"code": "CLL",
"text": "Export Loaded on Vessel",
"portCode": "CNNGB",
"location": "Ningbo",
"date": "2023-03-12T00:00:00Z"
},
{
"code": "VAD",
"text": "Estimated Time of Arrival",
"portCode": "BEANR",
"location": "Antwerp",
"date": "2023-04-15T00:00:00Z"
}
]
}
In each event, you will find :
- The event code
- The event text (a translation of the code in simple text)
- The location in plain text
- The port code (find here the UN/LOCODE documentation https://unece.org/trade/cefact/unlocode-code-list-country-and-territory). This field can be null if the shipping line hasn’t specified it. In this case please refer to the location field.
- And the timestamp of the event in standard UTC format (find here the corresponding documentation https://www.w3.org/TR/NOTE-datetime-970915.html)
GET /events/blorbk
Request
You must specify, as query parameters, the following inputs :
- Document type : 2 letters depending of the document type you wish to track : BL for Bill of Lading, and BK for Booking number
- Document number : depending on the document type, either the booking number (usually two letters plus six numbers) or the bill of lading number (ten digits number)
- Sealine code : 4 characters uniquely identifying the sealine. Use or GET /sealines endpoint to retrieve the complete list of supported sealines.
Response
In the response, you will find the list of events for all containers in your document. For each container, you will find the container id, and a list of events for this container.
[
{
"containerId": "TCLU8738299",
"events": [
{
"code": "CEP",
"text": "Gate out empty",
"portCode": "CNZUH",
"location": "Zhuhai",
"date": "2023-02-27T09:03:00Z"
},
{
"code": "VDL",
"text": "Vessel departed",
"portCode": "CNZUH",
"location": "Zhuhai",
"date": "2023-03-01T22:30:00Z"
},
{
"code": "CLL",
"text": "Loaded",
"portCode": "CNZUH",
"location": "Zhuhai",
"date": "2023-03-01T23:10:00Z"
},
{
"code": "CDT",
"text": "Discharged",
"portCode": "CNSHK",
"location": "Shekou",
"date": "2023-03-03T01:24:00Z"
},
{
"code": "CLT",
"text": "Loaded",
"portCode": "CNSHK",
"location": "Shekou",
"date": "2023-03-05T14:25:00Z"
},
{
"code": "VDT",
"text": "Vessel departed",
"portCode": "CNSHK",
"location": "Shekou",
"date": "2023-03-05T22:24:00Z"
},
{
"code": "VAD",
"text": "Vessel arrived",
"portCode": "FRFOS",
"location": "Fos-sur-Mer",
"date": "2023-04-12T02:48:00Z"
},
{
"code": "CDD",
"text": "Discharge",
"portCode": "FRFOS",
"location": "Fos-sur-Mer",
"date": "2023-04-12T02:48:00Z"
}
]
}
]
In each event, you will find :
- The event code
- The event text (a translation of the code in simple text)
- The location in plain text
- The port code (find here the UN/LOCODE documentation https://unece.org/trade/cefact/unlocode-code-list-country-and-territory). This field can be null if the shipping line hasn’t specified it. In this case please refer to the location field.
- And the timestamp of the event in standard UTC format (find here the corresponding documentation https://www.w3.org/TR/NOTE-datetime-970915.html)
GET /sealines
The endpoint allows you to retrieve supported sealines. It will return a list of sealines containing :
- The sealine code (4 digits used to identify the sealine in our container tracking API)
- The sealine official name
//example of response (shortened for clarity)
[
{
"code": "AUTO",
"name": "Automatically detect the sealine for container request, do not work for bl or bk"
},
{
"code": "ALRB",
"name": "AC Container Line"
},
{
"code": "ADMU",
"name": "Admiral Container Lines"
},
{
"code": "ALXP",
"name": "Aladin Express"
},
{
"code": "ANRM",
"name": "Alianca"
}
]
GET /usages
This endpoint allows you to retrieve the number of calls that were made with this API key to that API in a given period of time. In other words : to retrieve the same information that you can retrieve from the monitoring page in Sinay’s Developers Platform https://developers.sinay.ai/monitoring.
Request
If you send that request without any query params, you will get all API calls made with that key on that API since the key creation, month by month.
You can also specify the startTime and/or endTime as query params (in UTC format – more detailed information on that format here : https://www.w3.org/TR/NOTE-datetime-970915.html)
If you do so, the response given will include only the calls made during that time period.
Response
The response will show all calls made during that period, detailed by status, and then a detailed report of those calls and status, month by month.
{
"allCalls": 15,
"successCalls": 13,
"clientErrorCalls": 1,
"serverErrorCalls": 1,
"consumedApiUnits": 25,
"periodicUsages": {
"2022-05": {
"allCalls": 15,
"successCalls": 13,
"clientErrorCalls": 1,
"serverErrorCalls": 1,
"consumedApiUnits": 25
}
}
}
