Getting started with the Congestion API
The Safecube Congestion API gives real-time insight into how busy a port is. For any port, identified by its UN/LOCODE, it returns three families of indicators:
- Rate of occupation — how full the port is, broken down by vessel type (commercial, cargo, tanker, roro), with the gap against the historical mean;
- Time in port — statistics on how long vessels stay in the port: minimum, median and maximum;
- Vessels in port — the current number of vessels in the port, by type.
Use it to anticipate delays, optimise port-call planning, and feed congestion status into track and trace, ETA and routing workflows. The Congestion API coverage page lists the 205 covered ports.
The base URL of the Congestion API is https://api.sinay.ai/congestion/api/v1.
Authentication
Every Congestion API request is authenticated with your Safecube API key, sent in the API_KEY header, together with the standard HTTP headers. The API key must have access to the Congestion product.
GET /congestion/api/v1/congestion/FRLEH HTTP/1.1
Host: api.sinay.ai
API_KEY: <your API key>
A request with a missing, invalid or expired key, or with a key without access to the Congestion product, is rejected with 401 or 403 and consumes no credit. The Authentication page lists the mandatory HTTP headers.
Endpoints
| Method | Endpoint | Description |
|---|---|---|
GET | /congestion/{portCode} | Aggregated congestion of one port |
POST | /congestion/batch | Aggregated congestion of up to 10 ports in one call |
GET | /consumption/current-period | Remaining credits for the current period |
GET | /consumption/periods | Full consumption history |
Congestion of one port
GET /congestion/api/v1/congestion/FRLEH
API_KEY: <your API key>
Congestion of several ports
POST /congestion/batch takes up to 10 port codes in one call:
POST /congestion/api/v1/congestion/batch
API_KEY: <your API key>
Content-Type: application/json
{ "portCodes": ["FRLEH", "NLRTM", "DEHAM"] }
The reference page of each endpoint documents its full request and response schemas.
How credits are counted
Access to the Congestion API is credit-based, with one rule: one credit is charged per port for which data is actually returned.
Every response states its exact billing in three headers:
| Response header | Meaning |
|---|---|
X-Resource-Type | Type of resource billed: PORT_CONGESTION |
X-Requested-Count | Number of ports requested, duplicates removed |
X-Found-Count | Number of ports actually returned — the number of credits charged |
Credits for one port
A call to GET /congestion/{portCode} costs 1 credit:
X-Requested-Count: 1
X-Found-Count: 1 → 1 credit charged
Credits for several ports
For POST /congestion/batch:
X-Requested-Countis the number of unique ports requested: a port listed twice is counted once;X-Found-Countis the number of ports for which data was actually returned, and the number of credits charged;- a port with no data is skipped and not charged.
A batch request for 3 ports, one of which has no data available, is charged 2 credits:
X-Requested-Count: 3
X-Found-Count: 2 → 2 credits charged, not 3
Requests that cost nothing
- Failed requests are free: authentication errors, malformed port codes and quota-exceeded responses never consume credits.
- Congestion credits are a dedicated credit type, independent from the credits of the other Safecube products.
Quotas and rate limiting
Two independent protections can stop a Congestion API request:
- Credit quota reached — the request is answered with
403 Forbidden. It is blocked before processing and consumes no credit. Top up the credits or wait for the next period. - Too many requests in a short window — the request is answered with
429 Too Many Requests. The rate limit is 10 requests per 10 seconds per API key; retry shortly after.
The Rate limits page details the rate limit shared by every Safecube API.
Track your consumption
To check the credit balance without consuming a credit, call GET /consumption/current-period:
GET /congestion/api/v1/consumption/current-period
API_KEY: <your API key>
| Field | Meaning |
|---|---|
creditsInitial | Credits allocated at the start of the period |
credits | Remaining credits |
periodStart / periodEnd | Start and end of the current period |
expired | Whether the period has expired |
GET /consumption/periods returns the full history of the consumption periods.
Request lifecycle
- The client calls the Congestion API with its
API_KEY. - The gateway checks the access rights and the credit balance of the key. When the balance is insufficient, the request is answered with
403and nothing is charged. - The API fetches and aggregates the congestion data of the requested ports.
- The
X-Found-Countresponse header states how many credits were charged. - Only the ports that returned data are billed; ports without data are free.
Error responses
Every Congestion API error shares the same body:
{
"errorCode": 404,
"message": "unable to retrieve congestion",
"details": [],
"time": "2026-06-24T10:30:00Z"
}
| Status | Meaning |
|---|---|
400 Bad Request | Invalid input, such as a port code that is not 5 alphanumeric characters |
401 Unauthorized | Authentication failed |
403 Forbidden | Usage limit reached |
404 Not Found | No congestion data found for the requested resource |
429 Too Many Requests | Rate limit exceeded |
500 Internal Server Error | An error occurred on the server side |