Congestion API – Overview
The congestion API allows you to retrieve congestion levels for a selected number of ports in the world, and for the ship type of your choice.
Find on the below map the list of the covered ports. More can be added on request : for a list of covered port, or to request additions, please contact our team.
The congestion level is expressed in terms of percentage of port capacity used, and of difference with the average port occupation. Port occupation is computed in the port area (polygon including all berths, but excluding waiting zones and pilot boarding area).
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 General Documentation
Refresh interval
Congestion is computed every hour. Therefore, you can iterate your call at the same frequency to get the shortest refresh interval.
In practice, congestion levels change slowly : calling the API every 3 to 6 hours should be enough for most use cases.
Endpoints
GET /congestion
This endpoint allows you to retrieve the current congestion level for a specific port.
Request
You must specify in query parameters the UN/LOCODE of the port you wish to get the congestion levels. 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.
You can also specify the vessel type if you have one. If your request does not specify a vessel type, all vessel of AIS type cargo and tanker will be taken into account in the congestion calculation. The supported vessel type values are {cargo, tanker, roro}.
#example of query for cargos in <a href="https://sinay.ai/en/maritime-glossary/port/" class="glossary-only-link">port</a> of Rotterdam
curl -X 'GET' \
'https://api.sinay.ai/congestion/api/v1/congestion?portCode=NLRTM&vesselType=cargo' \
-H 'accept: application/json' \
-H 'API_KEY: 000000000-0000-000000000000000000’
#example of query in <a href="https://sinay.ai/en/maritime-glossary/port/" class="glossary-only-link">port</a> of Rotterdam, without any vessel type specified
curl -X 'GET' \
'https://api.sinay.ai/congestion/api/v1/congestion?portCode=NLRTM' \
-H 'accept: application/json' \
-H 'API_KEY: 000000000-00000-000000000000000’
Response
The response will deliver both the congestion level in percentage, and the gap with the mean congestion.
{
"congestion": 113.84615384615384,
"gapWithMean": 52.3076923076923
}
Example :
If the maximum number of vessels (cargos and tankers) in my port is 30 and the mean number of vessels is 20, and if there are currently 25 vessels in my port, the API values will be
- congestion : 25/30 = 83.3333333333333%
the “congestion” value measures how occupied the port is at the moment - gap with mean = current congestion – mean congestion = 25/30 – 20/30 = 24,3333333333 %
the “gap with mean” measure if the port is more occupied than usual. This value can be negative.
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
}
}
}
