The Sinay logo representing a dolphin

How to use ETAC API to predict Vessel Estimated Time of Arrival

Discover how to use SINAY ETA Calculator API to predict via API when a vessel will arrive and scale vessel estimated time of arrival in your own systems
[ no_toc ]
overview of the ETA api

Table of content

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/)

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"
  }
}

				
			

Scheduling / Port to Port

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)

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

Scheduling / Port to Port

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 :

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