MarineTraffic logo

MarineTraffic Containers API (1.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.

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.

Terminal Congestion

Access near real-time terminal congestion insights including:

  • Live Congestion: Vessel queues and congestion index.
  • Performance Metrics: 7d average waiting and stay times, performance index.
  • Carrier / Services Information: List of carriers operating at the terminal and their services.
  • Related Data: Associated port and terminal details when requested.

Data is updated every 30 minutes to provide near real-time terminal conditions.

List terminal congestions

Retrieve a list of terminal congestion data with live metrics and performance insights.
The list can be filtered using the following filter groups:

  • Performance Insights: performanceIndex, avgWaitingTime, avgStayTime
  • Live Metrics: congestionIndex, vesselsWaiting
  • Terminal Properties: id, smdgCode
  • Port Properties: id, unlocode

Results are paginated with 50 entries per page.

SecurityApiKeyAuth
Request
query Parameters
filter[performanceInsights.performanceIndex]
number [ 0 .. 10 ]

Filter by performance index (0-10).

Example: filter[performanceInsights.performanceIndex]=7.5
filter[performanceInsights.performanceIndex][operator]
number [ 0 .. 10 ]

Filter by performance index (0-10). Supported operators: eq, gte, lte.

Example: filter[performanceInsights.performanceIndex][operator]=7.5
filter[performanceInsights.avgWaitingTime]
number [ 0 .. 10000 ]

Filter by average waiting time in hours (0-10000).

Example: filter[performanceInsights.avgWaitingTime]=12.5
filter[performanceInsights.avgWaitingTime][operator]
number [ 0 .. 10000 ]

Filter by average waiting time in hours (0-10000). Supported operators eq, gte, lte.

Example: filter[performanceInsights.avgWaitingTime][operator]=12.5
filter[performanceInsights.avgStayTime]
number [ 0 .. 10000 ]

Filter by average stay time in hours (0-10000).

Example: filter[performanceInsights.avgStayTime]=48.3
filter[performanceInsights.avgStayTime][operator]
number [ 0 .. 10000 ]

Filter by average stay time in hours (0-10000). Supported operators: eq, gte, lte.

Example: filter[performanceInsights.avgStayTime][operator]=48.3
filter[liveMetrics.congestionIndex]
number [ 0 .. 10 ]

Filter by congestion index (0-10).

Example: filter[liveMetrics.congestionIndex]=6.2
filter[liveMetrics.congestionIndex][operator]
number [ 0 .. 10 ]

Filter by congestion index (0-10). Supported operators: eq, gte, lte.

Example: filter[liveMetrics.congestionIndex][operator]=6.2
filter[liveMetrics.vesselsWaiting]
integer [ 0 .. 10000 ]

Filter by number of vessels currently waiting (0-10000).

Example: filter[liveMetrics.vesselsWaiting]=5
filter[liveMetrics.vesselsWaiting][operator]
integer [ 0 .. 10000 ]

Filter by number of vessels currently waiting (0-10000). Supported operators: eq, gte, lte.

Example: filter[liveMetrics.vesselsWaiting][operator]=5
filter[terminal.id]
string [ 1 .. 9 ] characters ^[1-9]\d*$

Filter by terminal MT ID, exact match.

Example: filter[terminal.id]=101
filter[terminal.id][]
Array of integers <= 5 items

Filter by terminal MT IDs (max 5 values, no leading zeros), exact match only.

Example: filter[terminal.id][]=101&filter[terminal.id][]=102&filter[terminal.id][]=103
filter[terminal.smdgCode]
string [ 3 .. 6 ] characters ^[A-Za-z0-9]+$

Filter by terminal SMDG code, exact match only.

Example: filter[terminal.smdgCode]=HTG
filter[terminal.smdgCode][]
Array of strings <= 5 items

Filter by terminal SMDG code (exact match only, max 5 values).

Example: filter[terminal.smdgCode][]=HTG&filter[terminal.smdgCode][]=AET
filter[port.id]
string [ 1 .. 9 ] characters ^[1-9]\d*$

Filter by port MT ID.

Example: filter[port.id]=202
filter[port.id][]
Array of strings <= 5 items

Filter by port MT IDs (max 5 values, no leading zeros)

Example: filter[port.id][]=201&filter[port.id][]=202&filter[port.id][]=203
filter[port.name]
string [ 2 .. 50 ] characters ^[A-Za-z0-9\s\-]+$

Filter by port name. Exact match only.

Example: filter[port.name]=Hamburg
filter[port.name][operator]
string [ 2 .. 50 ] characters ^[A-Za-z0-9\s\-]+$

Filter by port name. Supported operators: eq (exact), contains (partial match)

Example: filter[port.name][operator]=Hamburg
filter[port.name][]
Array of strings <= 5 items

Filter by port name (max 5 values, exact match only).

Example: filter[port.name][]=Hamburg&filter[port.name][]=Rotterdam
filter[port.unlocode]
string = 5 characters ^[A-Z0-9]+$

Filter by port UN/LOCODE, exact match only.

Example: filter[port.unlocode]=DEHAM
filter[port.unlocode][]
Array of strings <= 5 items

Filter by port UN/LOCODE (exact match only, max 5 values)

Example: filter[port.unlocode][]=DEHAM&filter[port.unlocode][]=BEANR
include
string

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

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

Page number for pagination

Example: page=1
header Parameters
Accept
string

Specify the desired response format.

  • For JSON responses (JsonAPI standard), use application/vnd.api+json, application/json or */*.
  • For CSV responses, use text/csv.

If not specified, the response will be in application/vnd.api+json format.

Enum: "*/*" "application/vnd.api+json" "application/json" "text/csv"
Example: application/vnd.api+json
Responses
200

A list of terminal congestion data

422

Validation error

500

Internal Server Error

get/terminal-congestions
Request samples 
const axios = require('axios');

const API_KEY = 'API_KEY';

const params = {
  'filter[performanceInsights.performanceIndex][gte]': 5,
  'filter[performanceInsights.avgStayTime][lte]': 100,
  'filter[performanceInsights.avgWaitingTime][gte]': 4,
  'filter[liveMetrics.congestionIndex][gte]': 5,
  'filter[liveMetrics.vesselsWaiting][gte]': 2,
  'filter[port.name][contains]': 'HAM',
  'filter[port.unlocode]': ['DEHAM', 'BEANR'],
  include: 'ports,terminals'
};

axios.get('https://api.kpler.com/v1/logistics/containers/terminal-congestions', {
  headers: {
    'Accept': 'application/vnd.api+json',
    'X-Container-API-Key': API_KEY
  },
  params
})
.then(response => {
  console.dir(response.data, {depth:null});
})
.catch(error => {
  if (error.response) {
    console.dir(error.response.data, {depth:null});
  } else {
    console.error('Request failed:', error.message);
  }
});
Response samples
{}

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]=NLRTM
include
string

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

Enum: "ports" "vessels" "terminals" "ports,vessels" "ports,terminals" "vessels,terminals" "ports,vessels,terminals"
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
{}

Tracking requests

Introduction

Create tracking requests to start your container tracking experience.

Supported Shipping Lines / Freight Forwarders & SCAC List

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

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

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-09-17 (1.1.0)

NEW FEATURE: Container Intelligence API | Terminal Congestion

  • New endpoint GET /terminal-congestions to get insights on terminal congestion.
  • Reorganized documentation to include a new "Container Intelligence API" section and product description.

DOCUMENTATION FIX

DEVELOPER NOTICE | CODEGEN IMPACT
This documentation update may impact generated client libraries.
Please regenerate your SDKs to ensure compatibility.

  • Fixed the schema of Port and Terminal in the shipping/schedule-events endpoint.

2025-08-22 (1.0.3)

DOCUMENTATION FIX

DEVELOPER NOTICE | CODEGEN IMPACT
This documentation fix may impact generated client libraries.
Please regenerate your SDKs to ensure compatibility.

  • Added 5 values missing from API documentation for the equipmentEventTypeName enum: customs_released, customs_selected_for_inspection, customs_selected_for_scan, inspected, received.

2025-07-16 (1.0.2)

DOCUMENTATION UPDATE

  • Added a relevant filter[unlocode] example for the shipping/schedule-events endpoint.

2025-07-02 (1.0.1)

DOCUMENTATION FIX

DEVELOPER NOTICE | CODEGEN IMPACT
This documentation fix may impact generated client libraries.
Please regenerate your SDKs to ensure compatibility.

  • Added terminal in the shipping/schedule-events endpoint.
  • Fixed the schema of the included attribute in the shipping/schedule-events endpoint.

2025-06-17 (1.0.0)

DOCUMENTATION UPDATE

Reset documentation version to 1.0.0 to align with the API version (/v1/). No change in functionality.

2025-06-10

DOCUMENTATION FIX

DEVELOPER NOTICE | CODEGEN IMPACT
This documentation fix may impact generated client libraries.
Please regenerate your SDKs to ensure compatibility.

  • Updated the attribute name from portOfTranshipment to portsOfTransshipment in the GET /shipments/{shipmentId} endpoint to match the actual API response.

DOCUMENTATION UPDATE

2025-05-26

NEW FEATURE

DEPRECATED

The following items are deprecated.

IMPORTANT | MIRATION ACTION REQUIRED We encourage you to migrate to the new server URL and API key header defined above as soon as possible. The old server URL and API key header remain functional. We have not set a removal date yet.

DOCUMENTATION UPDATE

  • Changelog introduction
  • Global reorganization with the introduction of the Shipping schedules endpoint.