MarineTraffic logo

MarineTraffic Container Tracking API (V2)

Download OpenAPI specification:Download

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

Introduction

The MarineTraffic Container Tracking API 2.0 is your way to access state-of-the-art real-time visibility for your container shipments. For more information, please visit the solution landing page.

Get your API key

To get access to the solution, please reach out to sales@kpler.com If you have already issued one, sign in to marinetraffic.com and go to My API Services page to retrieve it. The API key must be specified in all requests as the value of the API header X-Container-Tracking-API-Key.

Supported Shipping Lines / Freight Forwarders & SCAC List

The list of supported shipping lines and freight forwarders is available in this dedicated page.

Tracking Requests

Create Tracking Requests to start your visibility experience.

Create tracking requests

Create Tracking Requests to start your visibility experience. Up to 100 tracking requests can be created in the same call.

SecurityApiKeyAuth
Request
Request Body schema: application/json
required
required
Array of objects (CreateTrackingRequestBody)
Responses
200

Successful operation

400

Bad request

422

Unable to process request

500

Internal Server Error

post/tracking-requests
Request samples
application/json
{
  • "data": [
    ]
}
Response samples
application/json
{}

List tracking requests

Retrieve a list of the tracking requests created. The list can be filtered by reference number and tags. The list is divided into pages of 50 entries each. Pagination links are provided for easy navigation.

SecurityApiKeyAuth
Request
query Parameters
object

Structure that can be used as payload when calling the Tracking Request list endpoint. When the filters contain values that return no results, an empty response will be sent. Filters can be applied to reference Number, reference number types, scac and tags.

Responses
200

successful operation

500

Internal Server Error

get/tracking-requests
Request samples 
const request = require('request');

const options = {
    method: 'GET',
    url: 'https://api.kpler.com/v1/logistics/container-tracking/tracking-requests',
    qs: {filter: { scac: ['TXZJ', 'LMCU'] }},
    headers: {'X-Container-Tracking-API-Key': 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
    if (error) throw new Error(error);

    console.log(body);
});
Response samples
application/json
{}

Fetch a Tracking Request

Retrieve a specific tracking request and all associated information.

SecurityApiKeyAuth
Request
path Parameters
trackingRequestId
required
string

Id of Tracking Request to return

Responses
200

successful operation

404

Tracking request not found

500

Internal Server Error

get/tracking-requests/{trackingRequestId}
Request samples 
const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.kpler.com/v1/logistics/container-tracking/tracking-requests/%7BtrackingRequestId%7D',
  headers: {'X-Container-Tracking-API-Key': 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
Response samples
application/json
{}

Shipments

Get visibility data for your shipments.

List shipments

Retrieve a list of your shipments. The list can be filtered by reference number, scac, tags, departure and arrival date range, origin and destination port.

SecurityApiKeyAuth
Request
query Parameters
object

Structure that can be used as payload when calling the Shipment list endpoint. When the filters contain values that return no results, an empty response will be sent. Filters can be applied to reference Number, reference number types, scac, tags date ranged for arrival and departure, as well as origin and destination of a shipment.

Responses
200

successful operation

500

Internal Server Error

get/shipments
Request samples 
const request = require('request');

const options = {
    method: 'GET',
    url: 'https://api.kpler.com/v1/logistics/container-tracking/shipments',
    qs: {filter: { scac: ['TXZJ', 'LMCU'] }},
    headers: {'X-Container-Tracking-API-Key': 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
    if (error) throw new Error(error);

    console.log(body);
});
Response samples
application/json
{}

Track Shipment

Retrieve a specific shipment and a comprehensive summary of all associated information.

SecurityApiKeyAuth
Request
path Parameters
shipmentId
required
string

Id of Shipment to return

Responses
200

successful operation

400

Bad request

404

Shipment not found

422

Unable to process request

500

Internal Server Error

get/shipments/{shipmentId}
Request samples 
const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.kpler.com/v1/logistics/container-tracking/shipments/%7BshipmentId%7D',
  headers: {'X-Container-Tracking-API-Key': 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
Response samples
application/json
{
  • "data": {
    },
  • "meta": {}
}

Shipment Transportation Timeline

Retrieve all milestones, locations and vessels associated with a specific shipment.

SecurityApiKeyAuth
Request
path Parameters
shipmentId
required
string

ID of Shipment to return the associated transportation timeline

Responses
200

successful operation

400

Bad request

404

Shipment not found

422

Unable to process request

500

Internal Server Error

get/shipments/{shipmentId}/transportation-timeline
Request samples 
const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.kpler.com/v1/logistics/container-tracking/shipments/%7BshipmentId%7D/transportation-timeline',
  headers: {'X-Container-Tracking-API-Key': 'REPLACE_KEY_VALUE'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
Response samples
application/json
{
  • "data": {
    },
  • "meta": {}
}

Replace Shipment Tags

Replace all shipment tags

SecurityApiKeyAuth
Request
path Parameters
shipmentId
required
string

ID of Shipment to update the associated tags

Request Body schema: application/json
required

Replace all the existing tags with a new list of tags.

required
Array of objects (ShipmentTagsRequestBody)
Responses
200

successful operation

400

Bad request

404

Shipment not found

422

Unable to process request

500

Internal Server Error

post/shipment/{shipmentId}/sync-tags
Request samples
application/json
{
  • "data": [
    ]
}
Response samples
application/json
{
  • "data": {
    }
}

Add Shipment Tags

Add new tags to a shipment

SecurityApiKeyAuth
Request
path Parameters
shipmentId
required
string

ID of Shipment to add tags to.

Request Body schema: application/json
required

Add listed tags to the shipment.

Array of objects (ShipmentTagsRequestBody)
Responses
200

successful operation

400

Bad request

404

Shipment not found

422

Unable to process request

500

Internal Server Error

post/shipment/{shipmentId}/add-tags
Request samples
application/json
{
  • "data": [
    ]
}
Response samples
application/json
{
  • "data": {
    }
}

Remove Shipment Tags

Remove tags from a shipment

SecurityApiKeyAuth
Request
path Parameters
shipmentId
required
string

ID of Shipment to remove tags from.

Request Body schema: application/json
required

Remove listed tags from the shipment.

Array of objects (ShipmentTagsRequestBody)
Responses
200

successful operation

400

Bad request

404

Shipment not found

422

Unable to process request

500

Internal Server Error

post/shipment/{shipmentId}/remove-tags
Request samples
application/json
{
  • "data": [
    ]
}
Response samples
application/json
{
  • "data": {
    }
}

Webhooks (Release end of 2024)

The Webhooks feature is under active development and will be released by end of 2024.

Introduction

The Webhook API enables your system to subscribe to specific container tracking events and receive real-time updates about them. The current version supports the following events:

  • shipment_updated: Triggered when one of your shipment has been updated.
  • tracking_request_succeeded: Triggered when your tracking request has been successfully processed and the underlying shipment successfully created.
  • tracking_request_failed: Triggered when your tracking request has failed.

To start receiving webhook events, reach out to get a webhook URL that will receive the event updates.

Getting Started

To begin using the Webhook API, follow these steps:

  1. Register for the service: Contact your account manager to register for the Webhook service.
  2. Webhook URL Setup: Your account manager will provide you a webhook URL you'll have to integrate in your system. This will be the endpoint where all event notifications will be sent.

Important: Only one URL is supported per user in the current version, and all events will be pushed to this URL.

Webhook Security

To ensure that the events you receive are from the Webhook API and not from unauthorized sources, we recommend the following security measures:

  • IP Whitelisting: You may choose to only allow requests from our specific IP ranges (provided upon request).

Error Handling

In the event that your system cannot process a webhook request, ensure your endpoint responds with a 500 HTTP status code. The system will attempt a limited number of retries in case of failures.

shipment_updatedWebhook

The event is triggered when the shipment has been updated. The webhook includes the new version of the shipment.

SecurityApiKeyAuth
Request
Request Body schema: application/json
required
object
required
Array of objects (Shipment)
Responses
200

Return a 200 status to indicate that the data was received successfully.

500

Return a 500 status to indicate that the data was not received successfully.

Request samples
application/json
{
  • "data": {},
  • "included": [
    ]
}

tracking_requested_succeededWebhook

The event is triggered when your tracking request has been successfully processed and the underlying shipment has been successfully created.

SecurityApiKeyAuth
Request
Request Body schema: application/json
required
object
required
Array of objects (TrackingRequest)
Responses
200

Return a 200 status to indicate that the data was received successfully.

500

Return a 500 status to indicate that the data was not received successfully.

Request samples
application/json
{}

tracking_requested_failedWebhook

The event is triggered when your tracking request has failed. It contains details about the failing reason.

SecurityApiKeyAuth
Request
Request Body schema: application/json
required
object
required
Array of objects (TrackingRequest)
Responses
200

Return a 200 status to indicate that the data was received successfully.

500

Return a 500 status to indicate that the data was not received successfully.

Request samples
application/json
{}