Skip to content
Documentation sections

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

MethodEndpointDescription
GET/congestion/{portCode}Aggregated congestion of one port
POST/congestion/batchAggregated congestion of up to 10 ports in one call
GET/consumption/current-periodRemaining credits for the current period
GET/consumption/periodsFull 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 headerMeaning
X-Resource-TypeType of resource billed: PORT_CONGESTION
X-Requested-CountNumber of ports requested, duplicates removed
X-Found-CountNumber 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-Count is the number of unique ports requested: a port listed twice is counted once;
  • X-Found-Count is 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>
FieldMeaning
creditsInitialCredits allocated at the start of the period
creditsRemaining credits
periodStart / periodEndStart and end of the current period
expiredWhether the period has expired

GET /consumption/periods returns the full history of the consumption periods.

Request lifecycle

  1. The client calls the Congestion API with its API_KEY.
  2. The gateway checks the access rights and the credit balance of the key. When the balance is insufficient, the request is answered with 403 and nothing is charged.
  3. The API fetches and aggregates the congestion data of the requested ports.
  4. The X-Found-Count response header states how many credits were charged.
  5. 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"
}
StatusMeaning
400 Bad RequestInvalid input, such as a port code that is not 5 alphanumeric characters
401 UnauthorizedAuthentication failed
403 ForbiddenUsage limit reached
404 Not FoundNo congestion data found for the requested resource
429 Too Many RequestsRate limit exceeded
500 Internal Server ErrorAn error occurred on the server side