ETAC API – Overview
What does ETAC mean ? ETAC stand for Estimated Time of Arrival Calculator.
Reliable ETAs help streamline operations, from initial purchase to delivery.
Computation principles
Our ETA-Calculator API allows you to request an ETA computation for a given Vessel from Sinay’s algorithm. Each API call will trigger a new calculation.
The ETA is computed at the waiting zone (neither at pilot boarding area nor berth). For ports that do not have a waiting zone, the ETA is given at port area.
For the moment, the ETA computed is computed with a direct route only (without intermediary stops).
Should I use Port to Port or Vessel to Port Calculation?
Our ETA-Calculator API enables you to get 2 different types of ETA Calculations.
When you want to compare 2 routes, or to get an ETA for a voyage that has not already started, use our Port-to-Port parameters set. This will allow you to enter a departure port and date, and to estimate an ETA based on those inputs.
When you wish to get an ETA for a voyage that has already started, taking into account real-time vessel data, use our Vessel-to-Port parameters set, and trust us to get the most accurate vessel information using our AIS data sources.
ETAC API Endpoints
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>
POST /compute-eta
Request
Request parameters are setup in the request body.
Real-time / Vessel to Port
To get an ETA for a real-time use case (when the vessel has already left the departure port), you will only have to use a limited number of parameters :
- Vessel ID
You must submit a request with a valid vessel id : either an IMO number or an MMSI number. (If you are not familiar with IMO or MMSI, you can find more information here https://sinay.ai/en/what-is-the-difference-between-imo-and-mmsi/)
- Arrival Port
You must identify the arrival port with its official UN/LOCODE. If you are not familiar with UN/LOCODEs, you can find more information here https://unece.org/trade/cefact/unlocode-code-list-country-and-territory.
{
"vessel": {
"imo": 9706906
},
"arrival": {
"portCode": "FRLEH"
}
}
{
"vessel": {
"mmsi": 209447000
},
"arrival": {
"portCode": "FRLEH"
}
}
If you wish to compute an ETA while the vessel has not yet left the departure port, you will use the same parameters as above + departure information.
- Departure date
You must specify the departure date in the UTC format (if you are not familiar with that format, you can find more information here : https://www.w3.org/TR/NOTE-datetime-970915.html)
- Departure port
You must identify the departure port with its official UN/LOCODE.
{
"vessel": {
"imo": 9706906
},
"departure": {
"date": "2020-01-10T10:00:00.000Z",
"portCode": "FRLEH"
},
"arrival": {
"portCode": "ESBCN"
}
}
Advanced : Speed
If you have an idea of the vessel speed over its voyage, or if you wish to estimate the impact of the vessel speed on its ETA, you can specify the vessel speed in knots.
Warning : this field is for advanced use only. ETAs provided by Sinay are based upon AI models which automatically estimates the vessel speed based on historical and recent AIS data. Overriding that speed value can lead to deceiving results if the chosen speed is incorrect.
{
"vessel": {
"imo": 9706906,
"speed": 17
},
"departure": {
"date": "2020-01-10T10:00:00.000Z",
"portCode": "FRLEH"
},
"arrival": {
"portCode": "ESBCN"
}
}
{
"vessel": {
"imo": 9706906,
"speed": 17
},
"arrival": {
"portCode": "FRLEH"
}
}
Response
The response body for this endpoint will display the following results fields :
- arrivalTime : ETA in UTC format
- etaRemainingTime : time to go in hours
- remainingDistance : distance from departure point (departure port or vessel position) in nautical miles
- confidence : integer between 1 and 5, estimating our own confidence in the provided estimation, 5 meaning high confidence
- etaErrorMarginValue : estimated error margin value of our prediction, in hours. This value will decrease over time, hence the recommendation to update Sinay’s ETA regularly
The response will also display a reminder of the request fields : their value will be null if they were not specified in the request.
- vessel imo : will be null if the mmsi was used to identify the vessel
- vessel mmsi : will be null if the imo was used to identify the vessel
- vessel speed : if you have not specified a vessel speed in your request, this field will be null. It does not mean that we took into account a speed of 0 in our computation : the default value is generated by our internal routing system.
- Departure date : if you have not specified a departure in your request, this field will not appear
- Departure port : if you have not specified a departure in your request, this field will not appear
- Arrival port
//Example whe no departure and no vessel in speed request :
{
"arrivalTime": "2023-04-06T21:17:22Z",
"vessel": {
"imo": 9706906,
"mmsi": null,
"speed": null
},
"departure": null,
"arrival": {
"portCode": "FRLEH"
},
"confidence": 2,
"remainingTime": 405.7080917592836,
"errorMarginValue": 105.48,
"remainingDistance": 10068.808110739048
}
//Example when departure port and dates are specified
{
"arrivalTime": "2020-01-15T21:31:00Z",
"vessel": {
"imo": 9706906,
"mmsi": null,
"speed": null
},
"departure": {
"date": "2020-01-10T10:00:00Z",
"portCode": "FRLEH"
},
"arrival": {
"portCode": "ESBCN"
},
"confidence": 3,
"remainingTime": 131.5218030685246,
"errorMarginValue": 14.47,
"remainingDistance": 1709.7834398908199
}
//Example when all fields (including speed are specified :
{
"arrivalTime": "2020-01-16T08:28:00Z",
"vessel": {
"imo": 9706906,
"mmsi": null,
"speed": 12
},
"departure": {
"date": "2020-01-10T10:00:00Z",
"portCode": "FRLEH"
},
"arrival": {
"portCode": "ESBCN"
},
"confidence": 3,
"remainingTime": 142.48195332423498,
"errorMarginValue": 15.67,
"remainingDistance": 1709.7834398908199
}
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
Without query params
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.
With query params
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.
{
"apis": {
"etac": {
"allCalls": 1713,
"successCalls": 1295,
"clientErrorCalls": 418,
"serverErrorCalls": 0,
"consumedApiUnits": 0,
"periodicUsages": {
"2023-01": {
"allCalls": 8,
"successCalls": 8,
"clientErrorCalls": 0,
"serverErrorCalls": 0,
"consumedApiUnits": 0
},
"2023-02": {
"allCalls": 654,
"successCalls": 436,
"clientErrorCalls": 218,
"serverErrorCalls": 0,
"consumedApiUnits": 0
}
}
}
}
Call frequency recommendation
When you request an ETA Port-to-Port (with the use of the “departure” parameters), the ETA will not vary until you change any of the request parameters.
Unless you wish to edit your request parameters (departure port, vessel, departure time…), it is therefore not recommended to refresh the ETA with another API request.
Real-time / Vessel to port
When you request an ETA Vessel-to-Port (without using any of the “departure” parameters), we will take into account the latest AIS message that we received for the vessel. With those new information, the ETA can vary. We therefore recommend to send a new request regularly.
To get the most of our API, and to take into account the vessel speed and trajectory variations, we suggest refreshing the ETA Calculation every 6 hours when the vessel is at least 7 days away (etaRemainingTime > 168), every 3 hours when the vessel is at least 3 days away (etaRemainingTime > 72) and every hour below that threshold.
Useful Links
Find more information in our swagger and postman documentations :
- https://api.sinay.ai/doc/index.html
- https://www.postman.com/sinayapi/workspace/sinay/overview
- ETAC Module
Do you have a question that is not covered in our guide ? Please contact [email protected] or submit a contact form in https://developers.sinay.ai
