MarineTraffic logo

MarineTraffic Containers API (2.1.0)

Download OpenAPI specification:Download

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

Introduction

The MarineTraffic Containers API is your way to access state-of-the-art real-time visibility for containers logistics.
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-API-Key.

Supported Shipping Lines / Freight Forwarders & SCAC List

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

Rate Limits

The API enforces a rate limit of 200 requests per minute.
Exceeding this limit will result in a 429 Too Many Requests HTTP response.

  • Authenticated requests are tracked based on the associated API key.
  • Unauthenticated requests are monitored based on the originating IP address.

IP Whitelisting

To enhance network security, you may whitelist the following IP addresses:

  • API Requests: All requests to the API will be directed exclusively to the following IP address(es): 13.248.154.30, 76.223.25.242.
  • Webhooks: Webhooks will only be dispatched from the following IP address(es): 3.251.15.122, 52.215.44.244, 54.195.123.104.

Tracking requests

Create tracking requests to start your container tracking experience.

Create tracking requests

Create tracking requests to start your container tracking 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, tags and more.
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/containers/tracking-requests',
    qs: {filter: { scac: ['TXZJ', 'LMCU'] }},
    headers: {'X-Container-API-Key': 'REPLACE_KEY_VALUE'}
};

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

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

Get tracking request details

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/containers/tracking-requests/%7BtrackingRequestId%7D',
  headers: {'X-Container-API-Key': 'REPLACE_KEY_VALUE'}
};

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

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

(Un)Archive tracking requests

(Un)Archive tracking requests and their related shipment.

SecurityApiKeyAuth
Request
path Parameters
operation
required
string

The operation that will be executed.

Enum: "add" "remove"
Request Body schema: application/json
required

(Un)Archive the Tracking Requests id list.

object (ArchiveTrackingRequestsRequestBody)
Responses
204

successful operation

400

Bad request

422

Unable to process request

500

Internal Server Error

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

Shipments

Access and manage your container tracking data.

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/containers/shipments',
    qs: {filter: { scac: ['TXZJ', 'LMCU'] }},
    headers: {'X-Container-API-Key': 'REPLACE_KEY_VALUE'}
};

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

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

Get shipment summary

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/containers/shipments/%7BshipmentId%7D',
  headers: {'X-Container-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": {}
}

Get shipment detailed milestones

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/containers/shipments/%7BshipmentId%7D/transportation-timeline',
  headers: {'X-Container-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 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/shipments/{shipmentId}/sync-tags
Request samples
application/json
{
  • "data": [
    ]
}
Response samples
application/json
{
  • "data": {
    }
}

Add 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/shipments/{shipmentId}/add-tags
Request samples
application/json
{
  • "data": [
    ]
}
Response samples
application/json
{
  • "data": {
    }
}

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/shipments/{shipmentId}/remove-tags
Request samples
application/json
{
  • "data": [
    ]
}
Response samples
application/json
{
  • "data": {
    }
}

Schedules

Get schedule events for container vessels and ports

Get schedule events for a container vessel or a port

Returns a list of events with optional filtering and included related resources.
You must provide either an IMO number or a UN-locode filter.

SecurityApiKeyAuth
Request
query Parameters
filter[imo]
required
string

Filter events by vessel IMO number.
Required unless UN-locode is provided.

Example: filter[imo]=9943865
filter[unlocode]
required
string

Filter by a related port's UN-locode.
Required unless IMO number is provided.

Example: filter[unlocode]=2
include
string

Comma-separated list of related resources to include in the response.

Enum: "ports" "vessels" "ports,vessels"
Example: include=ports,vessels
page
integer >= 1
Default: 1

Page number for pagination

Responses
200

A list of events.

422

Unable to process request

500

Internal Server Error

get/shipping/schedule-events
Request samples 
const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.kpler.com/v1/logistics/containers/shipping/schedule-events',
  qs: {
    filter: { imo: 9943865 },
    include: 'ports,vessels'
  },
  headers: {'X-Container-API-Key': 'REPLACE_KEY_VALUE'}
};

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

  console.log(body);
});
Response samples
{}

Webhook events

Introduction

The Webhook API enables your system to subscribe to specific container tracking events and receive realtime 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 faild. 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: You should provide us the URL where you'd like to receive our webhook events and payloads.

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
{}

2025-05-26

New

Deprecated

The following items are deprecated.

They remains functional and we have not set yet a removal date.
We encourage you to migrate to the new server URL and API key header defined above as soon as possible.

Updated

  • API documentation reorganization with the introduction of the Shipping schedules endpoint.