--- updatedAt: 2026-07-21T08:26:48.000Z agentTools: projectIndex: https://documentation.safecube.ai/llms.txt --- # Congestion # 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](congestion-api-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. ```http GET /congestion/api/v1/congestion/FRLEH HTTP/1.1 Host: api.sinay.ai API_KEY: ``` See [Mandatory Headers](https://documentation.safecube.ai/reference/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 | Method | Endpoint | Description | | ------ | ----------------------------- | ------------------------------------------------------------------ | | `GET` | `/congestion/{portCode}` | Aggregated congestion for a single port | | `POST` | `/congestion/batch` | Aggregated congestion for several ports in one call (**up to 10**) | | `GET` | `/consumption/current-period` | Your remaining credits for the current period | | `GET` | `/consumption/periods` | Your full consumption history | ### Single port ```http GET /congestion/api/v1/congestion/FRLEH API_KEY: ``` ### Batch (up to 10 ports) ```http POST /congestion/api/v1/congestion/batch 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](https://documentation.safecube.ai/reference/retrievecongestionaggregate). *** ## 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: | Response header | Meaning | | ------------------- | ----------------------------------------------------------------------------- | | `X-Resource-Type` | The type of resource billed (`PORT_CONGESTION`) | | `X-Requested-Count` | Number of ports requested (duplicates removed) | | `X-Found-Count` | **Number of ports actually returned — this is the number of credits charged** | ### 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](https://documentation.safecube.ai/reference/rate-limit) for details. *** ## Tracking your consumption To check your balance **without consuming a credit**: ```http GET /congestion/api/v1/consumption/current-period API_KEY: ``` Typical fields returned: | 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 | To retrieve the full history of your periods, use `/consumption/periods`. See [Current consumption period](https://documentation.safecube.ai/reference/retrievecurrentconsumptionperiod) and [Consumption periods](https://documentation.safecube.ai/reference/retrieveconsumptionperiods). *** ## 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: ```json { "errorCode": 404, "message": "unable to retrieve congestion", "details": [], "time": "2026-06-24T10:30:00Z" } ``` | Status | Meaning | | --------------------------- | ---------------------------------------------------------------------------------------------- | | `400 Bad Request` | Invalid input (e.g. 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 — see [Rate Limit](https://documentation.safecube.ai/reference/rate-limit) | | `500 Internal Server Error` | An error occurred on the server side |