Aller au contenu
Sections de la documentation

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éfixe Bearer.

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ètreTypeObligatoireDescription
shipmentNumberstringOuiNuméro de conteneur, numéro de connaissement ou numéro de booking.
shipmentTypeenumNonCT pour un conteneur, BL pour un connaissement, BK pour un booking. Détecté automatiquement s'il est absent.
sealinestringNon, 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.
routebooleanNon, true par défautRenvoie 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.
aisbooleanNon, true par défautRenvoie 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 :

  • shipmentType et shipmentNumber reprennent l'expédition suivie, shipmentType étant détecté automatiquement quand la requête ne le précise pas ;
  • sealine et sealineName identifient la compagnie maritime, par son code SCAC et par son nom ;
  • shippingStatus est le statut résumé de l'expédition : PLANNED, IN_TRANSIT, DELIVERED ou UNKNOWN ;
  • updatedAt est 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).

  • date peut être estimée ou réelle, comme l'indique actual. La date au pol est l'ETD, et la date au pod est l'ETA.
  • predictiveEta n'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, comme postpod dans 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, un eventCode et un status — gate in, gate out, chargé, déchargé — avec une date, un lieu et, en mer, un navire et un numéro de voyage.
  • isActual indique 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.

  • routeSegments est une succession de trajets, chacun un tableau de coordonnées avec un routeType (SEA ou LAND), qui dessinent une route possible de l'expédition du POL au POD.
  • coordinates est la position actuelle de l'expédition : la position du navire quand le conteneur est à bord, sinon le dernier lieu connu du conteneur.
  • ais contient les données AIS du navire — dernière position du navire, dernier event — quand le paramètre ais vaut aussi true.
{
  "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épond 504. Relancez-la dans les 60 minutes : les données seront alors disponibles dans le cache de Safecube.
  • 200 avec SEALINE_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.