# Getting started with the Congestion API

> The Congestion API returns real-time congestion indicators for a port — rate of occupation, time in port and vessels in port — and charges one credit per port for which data is actually returned.

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](/en/api/congestion/guides/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.

```http
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](/en/api/getting-started/authentication) page lists the mandatory HTTP headers.

## Endpoints

| Method | Endpoint                                                                                         | Description                                                    |
| ------ | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- |
| `GET`  | [`/congestion/{portCode}`](/en/api/congestion/reference/retrieve-congestion-aggregate)            | Aggregated congestion of one port                              |
| `POST` | [`/congestion/batch`](/en/api/congestion/reference/retrieve-congestion-aggregate-batch)           | Aggregated congestion of up to 10 ports in one call            |
| `GET`  | [`/consumption/current-period`](/en/api/congestion/reference/retrieve-current-consumption-period) | Remaining credits for the current period                       |
| `GET`  | [`/consumption/periods`](/en/api/congestion/reference/retrieve-consumption-periods)               | Full consumption history                                       |

### Congestion of one port

```http
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:

```http
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:

```text
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:

```text
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](/en/api/getting-started/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`](/en/api/congestion/reference/retrieve-current-consumption-period):

```http
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`](/en/api/congestion/reference/retrieve-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:

```json
{
  "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                                     |
