Premiers pas avec la Container Tracking API
La Container Tracking API de Safecube renvoie les données de suivi d'une expédition maritime à partir d'un seul identifiant : un numéro de conteneur, un numéro de connaissement ou un numéro de booking. Un seul endpoint, GET /shipment, renvoie le statut de l'expédition, ses ports de chargement et de déchargement avec leurs dates estimées et réelles, les navires impliqués, chaque event des conteneurs et la route de l'expédition. L'API couvre plus de 170 compagnies maritimes.
Authentifier vos requêtes
Chaque requête à la Container Tracking API est authentifiée par une clé d'API Safecube, envoyée dans un en-tête nommé API_KEY.
- Obtenir une clé d'API — créez un compte Safecube, gratuit ou avec un plan payant, à l'adresse
https://safecube.ai/sign-up/. - Trouver votre clé d'API — la clé est affichée dans l'application web Safecube à l'adresse
https://app.safecube.ai/api/credentials: ouvrez Developers dans la barre latérale, puis l'onglet API Credentials. - Envoyer votre clé d'API — ajoutez l'en-tête
API_KEY: <your API key>à chaque requête, sans préfixeBearer.
La page Authentification détaille la clé d'API, son renouvellement et les en-têtes HTTP obligatoires.
Compagnies maritimes couvertes
La Container Tracking API couvre les données de suivi de plus de 170 compagnies maritimes et transitaires. L'endpoint GET /sealines renvoie la liste à jour, avec les codes SCAC de chaque compagnie, les types d'expédition qu'elle accepte et si elle est en maintenance :
{
"sealines": [
{
"name": "AC Container Line",
"active": true,
"activeTypes": { "ct": true, "bl": true, "bk": true },
"maintenance": false,
"scacCodes": ["ALRB"],
"prefixes": []
}
]
}
La plupart des compagnies maritimes acceptent les numéros de conteneur (CT), de connaissement (BL) et de booking (BK), mais certaines n'en acceptent qu'une partie : activeTypes donne les types acceptés par compagnie. La page Compagnies maritimes prises en charge liste chaque compagnie avec ses codes SCAC.
Suivre votre première expédition
L'endpoint GET /shipment reçoit l'expédition à suivre en paramètres de requête :
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
shipmentNumber | string | Oui | Numéro de conteneur, numéro de connaissement ou numéro de booking. |
shipmentType | enum | Non | CT pour un conteneur, BL pour un connaissement, BK pour un booking. Détecté automatiquement s'il est absent. |
sealine | string | Non, mais recommandé | Code SCAC de la compagnie maritime. Le préciser raccourcit le temps de réponse et évite une mauvaise détection de la compagnie. |
route | boolean | Non, true par défaut | Renvoie les segments de route : le tableau de coordonnées qui suit le trajet de l'expédition du POL au POD. Passez-le à false pour un payload plus léger et une réponse plus rapide. |
ais | boolean | Non, true par défaut | Renvoie les données AIS du navire quand elles sont disponibles. Ne fonctionne que si route vaut aussi true. |
La requête ci-dessous suit l'expédition de test gratuite ZZZZ0000000, dont l'interrogation ne coûte rien :
curl "https://api.sinay.ai/container-tracking/api/v2/shipment?shipmentNumber=ZZZZ0000000&shipmentType=CT" \
-H "API_KEY: $SAFECUBE_API_KEY"
La page Sandbox et expéditions de test liste les autres expéditions de test gratuites, dont certaines renvoient des erreurs ou évoluent chaque jour.
Comprendre la réponse
Une réponse de GET /shipment se compose de sept blocs : metadata, locations, route, facilities, vessels, containers et routeData. Les extraits ci-dessous montrent un bloc chacun, tirés de réponses réelles et raccourcis. La référence de GET /shipment documente le schéma complet, champ par champ.
metadata
metadata contient les informations générales de l'expédition :
shipmentTypeetshipmentNumberreprennent l'expédition suivie,shipmentTypeétant détecté automatiquement quand la requête ne le précise pas ;sealineetsealineNameidentifient la compagnie maritime, par son code SCAC et par son nom ;shippingStatusest le statut résumé de l'expédition :PLANNED,IN_TRANSIT,DELIVEREDouUNKNOWN;updatedAtest l'heure de la dernière réception des données depuis la compagnie maritime.
{
"metadata": {
"shipmentType": "CT",
"shipmentNumber": "FANU1172910",
"sealine": "HLCU",
"sealineName": "Hapag-Lloyd",
"shippingStatus": "IN_TRANSIT",
"updatedAt": "2023-11-27T22:55:48Z"
}
}
locations
locations liste chaque lieu impliqué dans le transport de l'expédition : port de chargement (POL), port de déchargement (POD), ports de transbordement et lieux à l'intérieur des terres, dans l'ordre chronologique. Chaque lieu porte son nom, son pays, son UN/LOCODE, ses coordonnées et son fuseau horaire. Le rôle de chaque lieu — POL, POD ou autre — est donné par le bloc route.
{
"locations": [
{
"name": "Antwerp",
"state": "Flanders",
"country": "Belgium",
"countryCode": "BE",
"locode": "BEANR",
"coordinates": { "lat": 51.22047, "lng": 4.40026, "updatedAt": null },
"timezone": "Europe/Brussels"
},
{
"name": "Charleston",
"state": "South Carolina",
"country": "United States",
"countryCode": "US",
"locode": "USCHS",
"coordinates": { "lat": 32.77657, "lng": -79.93092, "updatedAt": null },
"timezone": "America/New_York"
}
]
}
route
route donne les lieux clés de l'expédition et leurs dates : prepol (lieu d'expédition), pol (port de chargement), pod (port de déchargement) et postpod (destination).
datepeut être estimée ou réelle, comme l'indiqueactual. La date aupolest l'ETD, et la date aupodest l'ETA.predictiveEtan'est fourni que pour le POD, quand le conteneur est à moins de 3 jours de son arrivée. Safecube le calcule à partir de l'historique des données AIS, de la congestion portuaire en temps réel et des données météo ; il ne vient pas de la compagnie maritime.- Un lieu que la compagnie maritime ne fournit pas vaut
null, commepostpoddans l'extrait ci-dessous.
{
"route": {
"pol": {
"location": { "name": "Antwerp", "countryCode": "BE", "locode": "BEANR" },
"date": "2023-11-07T17:38:00Z",
"actual": true,
"predictiveEta": null
},
"pod": {
"location": { "name": "Charleston", "countryCode": "US", "locode": "USCHS" },
"date": "2023-11-27T13:18:00Z",
"actual": true,
"predictiveEta": null
},
"postpod": {
"location": null,
"date": null,
"actual": null,
"predictiveEta": null
}
}
}
Dans l'extrait, les objets location sont raccourcis : dans une réponse, chacun porte les mêmes champs qu'une entrée de locations.
facilities
facilities liste les installations associées aux lieux de l'expédition — terminaux, dépôts — quand la compagnie maritime les fournit. Chaque installation porte son nom, son code pays, son UN/LOCODE, ses codes BIC et SMDG, et ses coordonnées. Le même objet apparaît dans le champ facility d'un event de conteneur.
{
"facilities": [
{
"name": "Houston Barbours Cut Terminal",
"countryCode": "US",
"locode": "USUQF",
"bicCode": "USUQFGDQQ",
"smdgCode": null,
"coordinates": { "lat": null, "lng": null, "updatedAt": null }
}
]
}
vessels
vessels liste chaque navire impliqué dans le transport de l'expédition, dans l'ordre chronologique, avec son nom, son numéro IMO, son indicatif d'appel, son MMSI et son pavillon.
{
"vessels": [
{
"name": "MISSOURI EXPRESS",
"imo": 9349552,
"callSign": "WDM2203",
"mmsi": 367781000,
"flag": "US"
}
]
}
containers
containers contient, pour chaque conteneur de l'expédition, son numéro, son code de type ISO, son statut et sa liste d'events.
- Chaque event a un
eventType, uneventCodeet unstatus— gate in, gate out, chargé, déchargé — avec une date, un lieu et, en mer, un navire et un numéro de voyage. isActualindique si la date de l'event est réelle ou estimée.- De nouveaux events s'ajoutent au fil du trajet de l'expédition : c'est en appelant l'API régulièrement que les données de suivi restent à jour.
{
"containers": [
{
"number": "FANU1172910",
"isoCode": "45G1",
"status": "IN_TRANSIT",
"events": [
{
"location": { "name": "Woerth am Rhein", "countryCode": "DE", "locode": "DEWOE" },
"facility": null,
"description": "Gate out empty",
"eventType": "EQUIPMENT",
"eventCode": "GTOT",
"status": "CEP",
"date": "2023-10-27T09:17:00Z",
"isActual": true,
"isAdditionalEvent": false,
"routeType": "LAND",
"transportType": "TRUCK",
"vessel": null,
"voyage": null
}
]
}
]
}
La page Codes de statut et d'event liste chaque type d'event, code d'event et statut.
routeData
routeData est renvoyé quand le paramètre route vaut true.
routeSegmentsest une succession de trajets, chacun un tableau de coordonnées avec unrouteType(SEAouLAND), qui dessinent une route possible de l'expédition du POL au POD.coordinatesest la position actuelle de l'expédition : la position du navire quand le conteneur est à bord, sinon le dernier lieu connu du conteneur.aiscontient les données AIS du navire — dernière position du navire, dernier event — quand le paramètreaisvaut aussitrue.
{
"routeData": {
"routeSegments": [
{
"path": [
{ "lat": 29.76328, "lng": -95.36327, "updatedAt": null },
{ "lat": 53.551052, "lng": 8.570912, "updatedAt": null },
{ "lat": 53.53615, "lng": 8.59298, "updatedAt": null }
],
"routeType": "SEA"
}
],
"coordinates": { "lat": 47.08643, "lng": -11.237754 }
}
}
Les pages Position d'une expédition et Route d'une expédition expliquent comment utiliser routeData pour localiser une expédition et tracer sa route sur une carte.
Bonnes pratiques
Ces pratiques améliorent le temps de réponse de la Container Tracking API, la qualité de ses données et le coût du suivi.
Suivre par connaissement
Suivre une expédition par son numéro de connaissement est facturé comme une seule expédition, quel que soit le nombre de conteneurs sous ce connaissement. Suivez par connaissement chaque fois que le numéro est disponible.
Préciser la compagnie maritime
Renseignez le paramètre sealine avec le code SCAC de la compagnie maritime chaque fois qu'il est connu. La réponse est plus rapide et souvent plus complète. Sans lui, l'API détecte automatiquement la compagnie maritime, et cette détection peut échouer même quand le numéro d'expédition est valide.
Relancer les requêtes en échec
- Timeout
504— quand la récupération des données auprès de la compagnie maritime prend trop de temps, l'API annule la requête et répond504. Relancez-la dans les 60 minutes : les données seront alors disponibles dans le cache de Safecube. 200avecSEALINE_HASNT_PROVIDE_INFO— la compagnie maritime n'a encore rien trouvé pour l'expédition. Relancez plus tard : la plupart de ces requêtes renvoient des résultats une fois que la compagnie maritime publie les données.
Interroger régulièrement
La Container Tracking API collecte ses données auprès de plusieurs sources, dont les compagnies maritimes directement, et les rafraîchit toutes les 6 à 24 heures selon la source. Appeler l'API toutes les 6 heures pour une expédition garde ses données aussi exactes que possible.
Pour un grand nombre d'expéditions, la Webhooks API de Safecube envoie les mises à jour de suivi vers votre propre endpoint dès qu'elles sont disponibles, sans interrogation régulière. La page Premiers pas avec les webhooks montre comment les configurer.
Gérer les erreurs
Quand une requête échoue, relancez-la, et renseignez les paramètres facultatifs que vous connaissez — le code SCAC sealine avant tout. La page Codes d'erreur liste chaque erreur renvoyée par la Container Tracking API, sa signification et si la requête est facturée.