MarineTraffic logo

MarineTraffic Container Tracking API (1.2.1)

Download OpenAPI specification:Download

E-mail: info@marinetraffic.com License: Apache 2.0 Terms of Service

Overview

This API is part of the MarineTraffic Container Tracking Solution, which provides access to track your container shipments both via MarineTraffic Web solution and integration to your own systems through this set of API resources.

More specifically, the solution allows you to get a real-time predictive ETA to every stop until the final destination for your shipments from more than 160 Carriers and Freight Forwarders, with full transportation plan visibility, including container events and vessel schedules. It combines Carrier’s Track & Trace, Operational Vessel Schedules and AIS, and utilises Machine Learning and real-time AIS Intelligence to give you the most accurate ETA and carrier-independent visibility.

More information for the solution is available at the solution landing page here.

Charging

The solution supports two different types of subscriptions. The paid period-based subscriptions, with annual commitment of shipments and, a free of charge period-based subscription with 10 available shipments to track within a year.

In both type of subscriptions the charge unit is per shipment and covers tracking the shipment until completion. When subscribing a shipment with a bill of lading or booking reference transport document number, you will be charged for one shipment even if this document number refers to more than one containers. When subscribing based on a container number, each container number will be considered a separate shipment and charged separately. Please note that this means also every duplicate container you subscribe to will be charged. While the system is designed to prevent multiple charges for Bill of Lading and Booking References by linking to the previous subscription, it does not currently offer the same safeguard for Container Numbers. This is because Container Numbers, unlike Bill of Lading or Booking References, can be reused for multiple shipments. This enables you to track the same container again when it is involved in different shipments - and you subscribe using same Container Number and Carrier (SCAC). With Bill of Lading or Booking Reference this is not the case, since they are unique.

Each shipment is pre-charged against your annual subscription limit upon subscription of a shipment, but will be refunded if the system has finished all possible retries and is unable to successfully fetch track & trace information.

Based on your needs you can purschase a paid or free annual plan here.

NOTE:
  • If track & trace information is available but ETA to the final destination cannot be calculated for other reasons (e.g. a vessel's next port does not match the expected one), charging will apply.
  • In case you implement the solution to subscribe your shipments using a Container Number, please make sure to do it once for every shipment you want to track. You will be charged for each Container Number that is subscribed to.

    • TIP: In a vfcShipment resource request, if the system responds with a 200 (SUCCESS) response, then charging has been applied, while a 4xx or 5xx (ERROR) response indicates a refund has/will be applied.

    Get your API key

    To issue an API service key:

    1. register at MarineTraffic platform ,
    2. add a shipment via My Shipments page,
    3. get your API key at My API Services page.

    To issue an API service key, to track more than 1000 shipments whithin a year just contact sales@marinetraffic.com.

    If you have already issued one, sign in to marinetraffic.com and go to My API Services page to retrieve it.

    Supported Shipping Lines / Freight Forwarders & SCAC List

    View a complete updated list of supported shipping lines and freight forwarders here. In case of a missing Shipping Line / Freight Forwarder in the list, contact us to assess whether we can support the extra Carrier.

    Quick Start Guide

    Just follow this quick start guide and you'll be up and running in no-time.

    Step 1. Subscribing your shipment for visibility tracking

  • First subscribe your shipment of interest for visibility tracking using the /vfcsubscribe resource (or /vfcSubscribeMany for subscribing to many shipments with one call)

    • In order to subscribe to a shipment for visibility tracking you need two pieces of information for that shipment, along with your API key.

    • the Carrier’s SCAC code (a full list of supported SCAC codes is available above - note that if you use a different SCAC code, you will receive an explanatory error message and you will not be charged).

    AND one of the following three transport document numbers

    • Carrier-issued Bill of Lading (BL), or
    • Carrier-issued Booking Reference (BK), or
    • Container Number (CN)

    In case of subscriptions based on Container Number (CN), SCAC can be also set to AUTO for automatic matching the respective SCAC code. In this case the system will attempt to match the proper SCAC code based on the first three characters of the container number.

    TIP: Auto-detect works well in Carrier owned containers, but will not work well in third party owned or leased containers, and might lead to return of tracking information of a past shipment that used the specific container.

    Other not supported document numbers:

    • Customs entry numbers
    • Seal numbers
    • Internally generated numbers, for example PO numbers or customer reference numbers.

  • The system responds that it has successfully registered your request, and gives you a shipmentId number that uniquely identifies each of the subscribed shipment within our system. This shipmentId together with your API service key will be used in the next step to request the latest shipment tracking information.

    • Step 2: Requesting the latest shipment tracking information

  • Then just ask for the latest shipment tracking information using the /vfcshipment resource.

    • The only requirement is that you have a valid shipmentId (from step 1 above), along with your API key. At the time of receiving your request, the system combines the latest information available to identify the current status of your shipment, and predict ETAs to every port until final port.The system responds with the updated visibility tracking information.

    Integration notes:

    • Please allow at least 10 minutes between Step 1 and Step 2 in order to ensure that the Track & Trace fetching is complete. If after 10 minutes you still get a pending response, the initial fetching was unsuccessful, and the system will retry every hour for the next 24 hours, and then once per day for another 4 days to successfully fetch track & trace data.
    • We propose a 24-hourly or 6-hourly request frequency. It is also possible to trigger different frequency of updates as the vessel draws closer to the final port of discharge by utilising the "distance to go" response field when the next port is the final port.

    Subscribe

    Subscribe shipment(s) for real-time visibility tracking

    Subscribe to a single shipment per API call

    Resource Overview

    This resource allows you to subscribe to a single shipment per API call. It returns the subscribed shipment details, with the unique ShipmentId that is required to be used in the vfcShipment resource for getting tracking information and updates.

    Parameter Validation & Error Messages

  • The system expects BLs/BKs/CNs to be 7-20 alphanumeric characters. If you have a Carrier issued code that does not follow this standard, please contact datasupport@marinetraffic.com with the details and we’ll try to help.
  • Please do not enter more than one type of transport document types (i.e. BL,BK,CN), as that will return an 402 error message.
  • If the SCAC code is not supported, you will get a 400 error message.
  • If you have less than 1 shipments available in the account associated, a 402 error message will appear.
    • Request
    path Parameters
    apiKey
    required
    string (apiKey) = 40 characters

    API Key

    Example: 75493a4cfdf0814961fe2d12519d5bc66690077e
    query Parameters
    scac
    required
    string (scac) = 4 characters

    SCAC Code

    Example: scac=MAEU
    tdId
    required
    string (transportDocumentId) [ 7 .. 20 ] characters

    Transport Document ID. Input the available transport document number. Can be a Bill of Lading, a Booking Reference, or a Container Number.

    Example: tdId=ABCD421911263977
    tdType
    required
    string (transportDocumentType)

    Transport Document Type. Input 'BL' for Bill of Lading, 'BK' for Booking Reference, or 'CN' for Container Number, to match the input in Transport Document ID.

    Enum: "BL" "BK" "CN"
    Responses
    200

    Success

    400

    Bad Request

    402

    Charging Error

    500

    Internal Server Error

    get/vfcsubscribe/{apiKey}
    Response samples
    application/json
    {
    • "shipmentId": "UTIDC7GLFZQO0NXA",
    • "scac": "MAEU",
    • "transportDocumentId": "ABCD421911263977",
    • "transportDocumentType": "BL"
    }

    Subscribe to multiple shipments per API call

    Resource Overview

    This resource allows you to subscribe to up to 500 shipments per API call. It returns a list of the subscribed shipments, with their unique ShipmentId's that is required to be used in the vfcShipment resource for getting tracking information and updates.

    It also returns the status of each shipment subscription (i.e. whether the subscription was successful or failed). It also allows you to input tags per shipment.

    Parameter Validation & Error Messages

    Since this resource responses refers to multiple shipments, the error messages do not apply to the overall response, but to the individual shipment where parameter validation failed.

    • The system expects BLs/BKs/CNs to be 7-20 alphanumeric characters. If you have a Carrier issued code that does not follow this standard, please contact datasupport@marinetraffic.com with the details and we’ll try to help.
    • Please do not enter more than one type of transport document types (i.e. BL,BK,CN), as that will return an 402 error message within the specific shipment array.
    • If the SCAC code is not supported, you will get a 400 error message within the specific shipment array.
    • If you have less than 1 shipments available in the account associated, a 402 error message will appear within the specific shipment array.
    • In case a shipment that is already subscribed is identified, it will be marked as duplicate.
    Request
    path Parameters
    apiKey
    required
    string (apiKey) = 40 characters

    Api Key

    Example: 75493a4cfdf0814961fe2d12519d5bc66690077e
    Request Body schema: application/json
    required
    Array
    scac
    string (scac) = 4 characters

    SCAC stands for Standard Carrier Alpha Code and is a unique identifier for a specific Carrier. Please refer to the list of supported Carriers and SCAC codes at http://.

    tdId
    string (transportDocumentId) [ 7 .. 20 ] characters

    The transportDocumentId is an identifier that links to a shipment, i.e. a Bill of Lading (BL) or a Booking Reference (BK), which are legal documents issued by each Carrier to their customers as proof of receipt and shipment of cargo. Alternatively, you can use the Container Number (CN).

    tdType
    string (transportDocumentType)

    The transportDocumentType is used to identify which type of document, the value of transportDocumentId represents. The values available are - BL (Bill of Lading) - BK (Booking Reference) - CN (Container Number)

    Enum: "BL" "BK" "CN"
    tags
    Array of strings (tag)
    Responses
    200

    Success

    500

    Internal Server Error

    post/vfcsubscribemany/{apiKey}
    Request samples
    application/json
    [
    • {
      },
    • {
      },
    • {
      }
    ]
    Response samples
    application/json
    [
    • {
      },
    • {
      },
    • {
      }
    ]

    Shipment tracking

    Get visibility tracking data for a shipment

    Get tracking information and ETAs for a single shipment

    Resource Overview

    This resource returns all tracking information and ETAs for a single shipment, updated in real-time at the time of the call based on the latest AIS information and intelligence.

    The successful response includes:

    • a header section with: shipment identification data, container id's & iso codes of each container, tags, shipment origin and destination data, current shipment status and vessel information, as well as the ETA prediction to the final port, or the actual arrival date-time and terminal information if the shipment has arrived at destination port.
    • a transportationPlan section that includes all carrier track & trace events (in the events section), all relevant vessel schedules (in the transport legs section), all participating vessels and locations (in the respective sections), and all routes.

    NOTE: Since the events timestamps represent the Carrier's reality, while the transportLegs timestamps represent the MarineTraffic (i.e. AIS and Machine Learning models) reality, they do not always match.

    Parameter Validation & Error Messages

    • In case of missing ShipmentId, a 400 error will be returned
    • In case of erroneous ShipmentId, a 404 error will be returned
    Request
    path Parameters
    apiKey
    required
    string (apiKey) = 40 characters

    MT api key

    Example: 75493a4cfdf0814961fe2d12519d5bc66690077e
    query Parameters
    shipmentId
    required
    string (shipmentId) = 16 characters

    The unique identifier of each shipment issued by MarineTraffic, and used internally and by the user to track the shipment throughout its lifecycle

    Example: shipmentId=UTIDC7GLFZQO0NXA
    Responses
    200

    successful operation

    400

    Bad Request

    404

    Not Found

    500

    System Error

    get/vfcshipment/{apiKey}
    Response samples
    application/json
    {
    • "shipmentId": "E07PWLP1PN2C5IPI",
    • "scac": "MAEU",
    • "carrier": "Maersk",
    • "transportDocumentId": "G9O2KF9IC9",
    • "transportDocumentType": "BL",
    • "containers": [
      ],
    • "tags": [
      ],
    • "shipmentStatus": 5,
    • "plannedEta": "2023-01-18T08:00:00Z",
    • "originPortId": 1010,
    • "originPortName": "TANJUNG PELEPAS",
    • "originPortUnlocode": "MYTPP",
    • "originPortCountry": "MALAYSIA",
    • "originPortLocalTimeOffset": 8,
    • "originPortPredictiveDepartureUtc": "2022-02-01T04:18:00Z",
    • "originPortActualDepartureUtc": "2022-02-01T10:32:00Z",
    • "finalPortId": 87,
    • "finalPortName": "LOS ANGELES",
    • "finalPortUnlocode": "USLAX",
    • "finalPortCountry": "USA",
    • "finalPortLocalTimeOffset": -7,
    • "finalPortPredictiveArrivalUtc": "2022-03-27T13:00:00Z",
    • "finalPortPredictiveArrivalUtcLast": "2022-03-27T13:00:00Z",
    • "finalPortActualArrivalUtc": null,
    • "finalPortAnchorageActualArrivalUtc": null,
    • "finalPortTerminalActualArrivalUtc": "2022-11-29T11:21:00Z",
    • "finalPortTerminalActualArrivalName": "Halterm Container Terminal",
    • "finalPortTerminalActualArrivalSMDG": "HAFXT",
    • "vesselName": "MAERSK ENSENADA",
    • "vesselIMONumber": 9502958,
    • "vesselShipId": 199849,
    • "vesselVoyageStatus": "22",
    • "vesselArea": "WMED - West Mediterranean",
    • "currentPortId": 4324,
    • "currentPortName": "CARDIFF",
    • "currentPortUnlocode": "GBCDF",
    • "currentCarrierVoyageNumber": "206N",
    • "nextPortId": 87,
    • "nextPortName": "LOS ANGELES",
    • "nextPortUnlocode": "USLAX",
    • "nextPortDistanceToGo": 2643,
    • "nextPortPredictiveArrivalUtc": "2022-03-27T13:00:00Z",
    • "webViewUrl": "https://www.marinetraffic.com/track-shipment?id=ΧΧΧΧΧΧ",
    • "lastCarrierUpdatedTimestamp": "2023-03-03T01:12:06Z",
    • "transportationPlan": {
      }
    }

    Get Carrier events information for all containers of a shipment

    Resource Overview

    This resource returns all Carrier container milestone events for each container number included in the specific shipment.

    The successful response includes:

    • container number, container ISO code and the list of all Carrier container milestone events.

      Parameter Validation & Error Messages

      • In case of missing ShipmentId, a 400 error will be returned
      • Use a specific container number (i.e. containerNo parameter) to limit the response to the events of a specific container included in the specific shipmentId

      NOTE: Use vfcshipment resource to map the port and vessel information included in this resource.

    Request
    path Parameters
    apiKey
    required
    string (apiKey) = 40 characters

    MT api key

    Example: 75493a4cfdf0814961fe2d12519d5bc66690077e
    query Parameters
    shipmentId
    required
    string (shipmentId) = 16 characters

    The unique identifier of each shipment issued by MarineTraffic, and used internally and by the user to track the shipment throughout its lifecycle

    Example: shipmentId=UTIDC7GLFZQO0NXA
    containerNo
    string (containerNo) = 11 characters

    The unique identifier of each container

    Example: containerNo=APHU6252773
    Responses
    200

    successful operation

    400

    Bad Request

    500

    System Error

    get/vfccontainers/{apiKey}
    Response samples
    application/json
    [
    • {
      }
    ]

    Insights

    Get insights for a subscribed shipment including possible rollover events as well as Port of Loading (POL) and Port of Discharge (POD) changes

    Get change insights about your shipments

    Resource Overview

    This resource returns detected possible rollover events and changes of Port of Loading (POL) or Port of Discharge (POD) for a single shipment. To start using it you need to have your API key and a valid ShipmentId that you get by using the Subscribe endpoint. At the time of receiving your request, the system will collect and combine all the insights available for your shipment and respond with the whole history of the detected insights for your shipment.

    The successful response includes:

    • A portChanges section which will be updated with new entries whenever we have detected a change on a planned event related to the Port of Loading (POL) or the Port of Discharge (POD) on a shipment.
    • A rollover section which will be updated with new entries whenever we have detected on planned events a possible rollover event that might happen in the Port of Loading (POL) or in a Transshipment port (TS) through the lifecycle of a shipment.

    NOTE: Since the events timestamps represent the Carrier's reality, while the transportLegs timestamps represent the MarineTraffic (i.e. AIS and Machine Learning models) reality, they do no always match.

    Parameter Validation & Error Messages

    • In case of missing ShipmentId, a 400 error will be returned
    • In case of erroneous ShipmentId, a 404 error will be returned
    Request
    path Parameters
    apiKey
    required
    string (apiKey) = 40 characters

    MT api key

    Example: 75493a4cfdf0814961fe2d12519d5bc66690077e
    query Parameters
    shipmentId
    required
    string (shipmentId) = 16 characters

    The unique identifier of each shipment issued by MarineTraffic, and used internally and by the user to track the shipment throughout its lifecycle

    Example: shipmentId=UTIDC7GLFZQO0NXA
    Responses
    200

    successful operation

    400

    Bad Request

    404

    Not Found

    500

    System Error

    get/vfcinsights/{apiKey}
    Response samples
    application/json
    {
    • "shipmentId": "E07PWLP1PN2C5IPI",
    • "portChanges": [
      ],
    • "rollovers": [
      ]
    }

    Supported Carrier list

    List supported carriers

    List supported carriers,

    List supported carriers,

    Responses
    200

    successful operation

    get/vfccarrierlist
    Response samples
    application/json
    [
    • {
      }
    ]