Premiers pas avec la Congestion API
La Congestion API de Safecube donne une vue en temps réel de l'activité d'un port. Pour tout port, identifié par son UN/LOCODE, elle renvoie trois familles d'indicateurs :
- Taux d'occupation — le niveau de remplissage du port, ventilé par type de navire (commercial, cargo, tanker, roro), avec l'écart à la moyenne historique ;
- Temps au port — des statistiques sur la durée de séjour des navires dans le port : minimum, médiane et maximum ;
- Navires au port — le nombre actuel de navires dans le port, par type.
Utilisez-la pour anticiper les retards, optimiser la planification des escales et alimenter les workflows de track and trace, d'ETA et de routage avec l'état de la congestion. La page Couverture de la Congestion API liste les 205 ports couverts.
L'URL de base de la Congestion API est https://api.sinay.ai/congestion/api/v1.
Authentification
Chaque requête à la Congestion API est authentifiée par votre clé d'API Safecube, envoyée dans l'en-tête API_KEY, avec les en-têtes HTTP standard. La clé d'API doit avoir accès au produit Congestion.
GET /congestion/api/v1/congestion/FRLEH HTTP/1.1
Host: api.sinay.ai
API_KEY: <your API key>
Une requête dont la clé est absente, invalide ou expirée, ou dont la clé n'a pas accès au produit Congestion, est rejetée avec 401 ou 403 et ne consomme aucun crédit. La page Authentification liste les en-têtes HTTP obligatoires.
Endpoints
| Méthode | Endpoint | Description |
|---|---|---|
GET | /congestion/{portCode} | Congestion agrégée d'un port |
POST | /congestion/batch | Congestion agrégée de 10 ports au plus en un seul appel |
GET | /consumption/current-period | Crédits restants pour la période en cours |
GET | /consumption/periods | Historique complet de la consommation |
Congestion d'un port
GET /congestion/api/v1/congestion/FRLEH
API_KEY: <your API key>
Congestion de plusieurs ports
POST /congestion/batch accepte jusqu'à 10 codes de port en un seul appel :
POST /congestion/api/v1/congestion/batch
API_KEY: <your API key>
Content-Type: application/json
{ "portCodes": ["FRLEH", "NLRTM", "DEHAM"] }
La page de référence de chaque endpoint documente ses schémas complets de requête et de réponse.
Décompte des crédits
L'accès à la Congestion API fonctionne par crédits, avec une règle : un crédit est facturé par port pour lequel des données sont effectivement renvoyées.
Chaque réponse indique sa facturation exacte dans trois en-têtes :
| En-tête de réponse | Signification |
|---|---|
X-Resource-Type | Type de ressource facturée : PORT_CONGESTION |
X-Requested-Count | Nombre de ports demandés, doublons retirés |
X-Found-Count | Nombre de ports effectivement renvoyés — le nombre de crédits facturés |
Crédits pour un port
Un appel à GET /congestion/{portCode} coûte 1 crédit :
X-Requested-Count: 1
X-Found-Count: 1 → 1 crédit facturé
Crédits pour plusieurs ports
Pour POST /congestion/batch :
X-Requested-Countest le nombre de ports uniques demandés : un port listé deux fois est compté une fois ;X-Found-Countest le nombre de ports pour lesquels des données ont effectivement été renvoyées, et le nombre de crédits facturés ;- un port sans données est ignoré et n'est pas facturé.
Une requête batch sur 3 ports, dont l'un n'a aucune donnée disponible, est facturée 2 crédits :
X-Requested-Count: 3
X-Found-Count: 2 → 2 crédits facturés, pas 3
Requêtes gratuites
- Les requêtes en échec sont gratuites : les erreurs d'authentification, les codes de port mal formés et les réponses de quota dépassé ne consomment jamais de crédits.
- Les crédits de congestion sont un type de crédit dédié, indépendant des crédits des autres produits Safecube.
Quotas et limite de requêtes
Deux protections indépendantes peuvent bloquer une requête à la Congestion API :
- Quota de crédits atteint — la requête reçoit la réponse
403 Forbidden. Elle est bloquée avant traitement et ne consomme aucun crédit. Rechargez les crédits ou attendez la période suivante. - Trop de requêtes sur une courte fenêtre — la requête reçoit la réponse
429 Too Many Requests. La limite de requêtes est de 10 requêtes par 10 secondes et par clé d'API ; réessayez peu après.
La page Limites de requêtes détaille la limite de requêtes commune à toutes les API Safecube.
Suivre votre consommation
Pour consulter le solde de crédits sans consommer de crédit, appelez GET /consumption/current-period :
GET /congestion/api/v1/consumption/current-period
API_KEY: <your API key>
| Champ | Signification |
|---|---|
creditsInitial | Crédits alloués au début de la période |
credits | Crédits restants |
periodStart / periodEnd | Début et fin de la période en cours |
expired | Indique si la période a expiré |
GET /consumption/periods renvoie l'historique complet des périodes de consommation.
Cycle de vie d'une requête
- Le client appelle la Congestion API avec son
API_KEY. - La passerelle vérifie les droits d'accès et le solde de crédits de la clé. Quand le solde est insuffisant, la requête reçoit la réponse
403et rien n'est facturé. - L'API récupère et agrège les données de congestion des ports demandés.
- L'en-tête de réponse
X-Found-Countindique combien de crédits ont été facturés. - Seuls les ports qui ont renvoyé des données sont facturés ; les ports sans données sont gratuits.
Réponses d'erreur
Toutes les erreurs de la Congestion API partagent le même corps :
{
"errorCode": 404,
"message": "unable to retrieve congestion",
"details": [],
"time": "2026-06-24T10:30:00Z"
}
| Statut | Signification |
|---|---|
400 Bad Request | Entrée invalide, comme un code de port qui ne compte pas 5 caractères alphanumériques |
401 Unauthorized | Échec de l'authentification |
403 Forbidden | Limite d'utilisation atteinte |
404 Not Found | Aucune donnée de congestion trouvée pour la ressource demandée |
429 Too Many Requests | Limite de requêtes dépassée |
500 Internal Server Error | Une erreur est survenue côté serveur |