Aller au contenu
Sections de la documentation

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éthodeEndpointDescription
GET/congestion/{portCode}Congestion agrégée d'un port
POST/congestion/batchCongestion agrégée de 10 ports au plus en un seul appel
GET/consumption/current-periodCrédits restants pour la période en cours
GET/consumption/periodsHistorique 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éponseSignification
X-Resource-TypeType de ressource facturée : PORT_CONGESTION
X-Requested-CountNombre de ports demandés, doublons retirés
X-Found-CountNombre 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-Count est le nombre de ports uniques demandés : un port listé deux fois est compté une fois ;
  • X-Found-Count est 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>
ChampSignification
creditsInitialCrédits alloués au début de la période
creditsCrédits restants
periodStart / periodEndDébut et fin de la période en cours
expiredIndique 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

  1. Le client appelle la Congestion API avec son API_KEY.
  2. 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 403 et rien n'est facturé.
  3. L'API récupère et agrège les données de congestion des ports demandés.
  4. L'en-tête de réponse X-Found-Count indique combien de crédits ont été facturés.
  5. 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"
}
StatutSignification
400 Bad RequestEntrée invalide, comme un code de port qui ne compte pas 5 caractères alphanumériques
401 UnauthorizedÉchec de l'authentification
403 ForbiddenLimite d'utilisation atteinte
404 Not FoundAucune donnée de congestion trouvée pour la ressource demandée
429 Too Many RequestsLimite de requêtes dépassée
500 Internal Server ErrorUne erreur est survenue côté serveur