Port Congestion API

The Port Congestion API gives you real-time insight into how busy a port is. For any port (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 (min / median / max).
• Vessels in port — the current number of vessels present, by type.

Use it to anticipate delays, optimise port-call planning, and feed congestion status into your Track & Trace, ETA and routing workflows.

Coverage

Base URL: https://api.sinay.ai/congestion/api/v1

Getting started

Every request must be authenticated with your API key, passed in the API_KEY header, together with the standard HTTP headers.

GET /congestion/api/v1/congestion/FRLEH HTTP/1.1
Host: api.sinay.ai
API_KEY: <your-api-key>

See Mandatory Headers for the full list of required HTTP headers.

A request with a missing, invalid or expired key — or a key without access to the Congestion product — is rejected (401 / 403) and does not consume any credit.

Endpoints

Single port

GET /congestion/api/v1/congestion/FRLEH
API_KEY: <your-api-key>

Batch (up to 10 ports)

POST /congestion/api/v1/congestion/batch
API_KEY: <your-api-key>
Content-Type: application/json

{ "portCodes": ["FRLEH", "NLRTM", "DEHAM"] }

Full request/response schemas are available in the API reference: Retrieve aggregated congestion for a port.

How credits are counted

Access to the Congestion API is credit-based. The rule is simple:

You are charged 1 credit per port for which data is actually returned.

Every response exposes the exact billing on three headers, so you always know what you paid for:

Single port

A call to GET /congestion/{portCode} costs 1 credit.

X-Requested-Count: 1
X-Found-Count: 1      → 1 credit charged

Batch

For POST /congestion/batch:

• X-Requested-Count is the number of unique ports requested. If the same port appears twice in your list, it is counted once.
• X-Found-Count is the number of ports for which data was actually returned — this is what you are charged.
• Ports with no data are skipped and not charged. You only pay for results you actually receive.

Example — you request 3 ports, but one has no data available:

X-Requested-Count: 3
X-Found-Count: 2      → 2 credits charged, not 3

Good to know

• Failed requests are free. Authentication errors, malformed port codes, and quota-exceeded responses never consume credits.
• Congestion credits are a dedicated credit type and are independent from your other products (Shipment, Schedule, …).

Quotas and rate limiting

Two independent protections can stop a request:

• Credit quota reached → 403 Forbidden. The request is blocked before processing — no credit is consumed. Top up or wait for your next period.
• Too many requests in a short window → 429 Too Many Requests. A maximum call rate of 10 requests per 10 seconds per API key applies. Simply retry shortly after.

See Rate Limit for details.

Tracking your consumption

To check your balance without consuming a credit:

GET /congestion/api/v1/consumption/current-period
API_KEY: <your-api-key>

Typical fields returned:

To retrieve the full history of your periods, use /consumption/periods.

See Current consumption period and Consumption periods.

Request lifecycle at a glance

1. You call the API with your API_KEY.
2. The gateway checks your access rights and your credit balance. If insufficient → 403, nothing is charged.
3. The API fetches and aggregates congestion data for the requested ports.
4. The response tells you, via X-Found-Count, exactly how many credits were charged.
5. Only ports that actually returned data are billed; misses are free.

Error responses

All errors share a common body:

{
  "errorCode": 404,
  "message": "unable to retrieve congestion",
  "details": [],
  "time": "2026-06-24T10:30:00Z"
}