MarineTraffic Containers API (1.0.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": [{"type": "tracking_request",
"attributes": {"referenceNumberType": "container",
"referenceNumber": "MEDUPE268513",
"scac": "MEDU",
"tags": ["one tag",
"second tag"
]
}
}
]
}

Response samples

application/json

{"data": [{"type": "tracking_request",
"trackingRequestId": "01hkz69f0m9vxcmgpyrq50dfsg",
"attributes": {"referenceNumberType": "container",
"referenceNumber": "MEDUPE268513",
"carrier": {"scac": "MEDU",
"name": "Maersk Line"
},
"status": "success",
"failed_reason": null,
"tags": [{"id": "01hkz69f0m9vxcmgpyrq50dfsg",
"label": "Tag one"
}
],
"owned": true,
"created": "2024-01-01T00:00:00.000Z"
},
"links": {"self": "https://api.kpler.com/v1/logistics/containers/tracking-requests/01hkz69f0m9vxcmgpyrq50dfsg"
},
"relationships": {"shipment": {"data": {"type": "shipment",
"shipmentId": "01j0qv3jmyete3zwe08nn2dzpa"
},
"links": {"related": "https://api.kpler.com/v1/logistics/containers/shipments/01j0qv3jmyete3zwe08nn2dzpa"
}
}
}
}
],
"errors": [{"status": 400,
"code": "DATA_VALIDATION_FAILED",
"description": "Data validation failed",
"source": {"pointer": "/data/0/attributes/scac"
}
}
]
}

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

{"data": [{"type": "tracking_request",
"trackingRequestId": "01hkz69f0m9vxcmgpyrq50dfsg",
"attributes": {"referenceNumberType": "container",
"referenceNumber": "MEDUPE268513",
"carrier": {"scac": "MEDU",
"name": "Maersk Line"
},
"status": "success",
"failed_reason": null,
"tags": [{"id": "01hkz69f0m9vxcmgpyrq50dfsg",
"label": "Tag one"
}
],
"owned": true,
"created": "2024-01-01T00:00:00.000Z"
},
"links": {"self": "https://api.kpler.com/v1/logistics/containers/tracking-requests/01hkz69f0m9vxcmgpyrq50dfsg"
},
"relationships": {"shipment": {"data": {"type": "shipment",
"shipmentId": "01j0qv3jmyete3zwe08nn2dzpa"
},
"links": {"related": "https://api.kpler.com/v1/logistics/containers/shipments/01j0qv3jmyete3zwe08nn2dzpa"
}
}
}
}
],
"links": {"self": "https://api.kpler.com/v1/logistics/containers/tracking-requests/?page=2",
"first": "https://api.kpler.com/v1/logistics/containers/tracking-requests/?page=1",
"prev": "https://api.kpler.com/v1/logistics/containers/tracking-requests/?page=1",
"next": "https://api.kpler.com/v1/logistics/containers/tracking-requests/?page=3",
"last": "https://api.kpler.com/v1/logistics/containers/tracking-requests/?page=10"
}
}

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

{"data": {"type": "tracking_request",
"trackingRequestId": "01hkz69f0m9vxcmgpyrq50dfsg",
"attributes": {"referenceNumberType": "container",
"referenceNumber": "MEDUPE268513",
"carrier": {"scac": "MEDU",
"name": "Maersk Line"
},
"status": "success",
"failed_reason": null,
"tags": [{"id": "01hkz69f0m9vxcmgpyrq50dfsg",
"label": "Tag one"
}
],
"owned": true,
"created": "2024-01-01T00:00:00.000Z"
},
"links": {"self": "https://api.kpler.com/v1/logistics/containers/tracking-requests/01hkz69f0m9vxcmgpyrq50dfsg"
},
"relationships": {"shipment": {"data": {"type": "shipment",
"shipmentId": "01j0qv3jmyete3zwe08nn2dzpa"
},
"links": {"related": "https://api.kpler.com/v1/logistics/containers/shipments/01j0qv3jmyete3zwe08nn2dzpa"
}
}
}
}
}

(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": {"type": "tracking_request_archive",
"attributes": {"list": ["01hkz69f0m9vxcmgpyrq50dfsg"
]
}
}
}

Response samples

application/json

{"errors": [{"status": 400,
"code": "DATA_VALIDATION_FAILED",
"description": "Data validation failed",
"source": {"pointer": "/data/0/attributes/scac"
}
}
]
}

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

{"data": [{"type": "shipment",
"shipmentId": "01j0qv3jmyete3zwe08nn2dzpa",
"attributes": {"referenceNumberType": "container",
"referenceNumber": "MEDUPE268513",
"carrier": {"scac": "MEDU",
"name": "Maersk Line"
},
"tags": [{"id": "01hkz69f0m9vxcmgpyrq50dfsg",
"label": "Tag one"
}
],
"owned": true,
"created": "2024-01-01T00:00:00.000Z"
},
"relationships": {"trackingRequest": {"data": {"type": "tracking_request",
"trackingRequestId": "01hkz69f0m9vxcmgpyrq50dfsg"
},
"links": {"related": "https://api.kpler.com/v1/logistics/containers/tracking-requests/01hkz69f0m9vxcmgpyrq50dfsg"
}
}
},
"links": {"self": "https://api.kpler.com/v1/logistics/containers/shipments/01j0qv3jmyete3zwe08nn2dzpa",
"related": "https://api.kpler.com/v1/logistics/containers/shipments/01j0qv3jmyete3zwe08nn2dzpa/trasnportation-timeline"
}
}
],
"links": {"self": "https://api.kpler.com/v1/logistics/containers/shipments/?page=2",
"first": "https://api.kpler.com/v1/logistics/containers/shipments/?page=1",
"prev": "https://api.kpler.com/v1/logistics/containers/shipments/?page=1",
"next": "https://api.kpler.com/v1/logistics/containers/shipments/?page=3",
"last": "https://api.kpler.com/v1/logistics/containers/shipments/?page=10"
}
}

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": {"type": "shipment",
"shipmentId": "01j0qv3jmyete3zwe08nn2dzpa",
"attributes": {"referenceNumberType": "container",
"referenceNumber": "MEDUPE268513",
"carrier": {"scac": "MEDU",
"name": "Maersk Line"
},
"transportationStatus": "booked",
"containers": [{"id": "01hnahef5ym5x2jfndgma4kc6q",
"number": "HLXU1234567",
"isoCode": "22G1",
"type": "General purpose container",
"size": {"length": 20,
"height": 8.6
}
}
],
"insights": {"arrivalDelayDays": 3,
"rollover": [{"initialVessel": {"id": "01hkz69f0m9vxcmgpyrq50dfsg",
"mtId": 12345,
"name": "Madrid Maersk",
"imo": 9778791,
"mmsi": 219836000
},
"newVessel": {"id": "01hkz69f0m9vxcmgpyrq50dfsg",
"mtId": 12345,
"name": "Madrid Maersk",
"imo": 9778791,
"mmsi": 219836000
},
"atPort": {"id": "01hkz69f0m9vxcmgpyrq50dfsg",
"mtId": 12345,
"unlocode": "GRPIR",
"name": "Piraeus",
"country": "Greece",
"lat": -19.88327,
"lon": 5.713717,
"terminal": {"id": null,
"name": null,
"smdg": null,
"operator": null
}
},
"detectedAt": "2024-01-01T00:00:00.000Z",
"initialDepartureDate": {"timestamp": "2024-01-01T00:00:00.000Z",
"localTimeOffset": -3
},
"newDepartureDate": {"timestamp": "2024-01-01T00:00:00.000Z",
"localTimeOffset": -3
}
}
],
"portOfLoadingChange": [{"initialPort": {"id": "01hkz69f0m9vxcmgpyrq50dfsg",
"mtId": 12345,
"unlocode": "GRPIR",
"name": "Piraeus",
"country": "Greece",
"lat": -19.88327,
"lon": 5.713717,
"terminal": {"id": null,
"name": null,
"smdg": null,
"operator": null
}
},
"newPort": {"id": "01hkz69f0m9vxcmgpyrq50dfsg",
"mtId": 12345,
"unlocode": "GRPIR",
"name": "Piraeus",
"country": "Greece",
"lat": -19.88327,
"lon": 5.713717,
"terminal": {"id": null,
"name": null,
"smdg": null,
"operator": null
}
},
"detectedAt": "2024-01-01T00:00:00.000Z",
"initialDepartureDate": {"timestamp": "2024-01-01T00:00:00.000Z",
"localTimeOffset": -3
},
"newDepartureDate": {"timestamp": "2024-01-01T00:00:00.000Z",
"localTimeOffset": -3
}
}
],
"portOfDischargeChange": [{"initialPort": {"id": "01hkz69f0m9vxcmgpyrq50dfsg",
"mtId": 12345,
"unlocode": "GRPIR",
"name": "Piraeus",
"country": "Greece",
"lat": -19.88327,
"lon": 5.713717,
"terminal": {"id": null,
"name": null,
"smdg": null,
"operator": null
}
},
"newPort": {"id": "01hkz69f0m9vxcmgpyrq50dfsg",
"mtId": 12345,
"unlocode": "GRPIR",
"name": "Piraeus",
"country": "Greece",
"lat": -19.88327,
"lon": 5.713717,
"terminal": {"id": null,
"name": null,
"smdg": null,
"operator": null
}
},
"detectedAt": "2024-01-01T00:00:00.000Z",
"initialArrivalDate": {"timestamp": "2024-01-01T00:00:00.000Z",
"localTimeOffset": -3
},
"newArrivalDate": {"timestamp": "2024-01-01T00:00:00.000Z",
"localTimeOffset": -3
}
}
],
"initialCarrierEta": "2021-01-01T00:00:00Z"
},
"portOfLoading": {"port": {"id": "01hkz69f0m9vxcmgpyrq50dfsg",
"mtId": 12345,
"unlocode": "GRPIR",
"name": "Piraeus",
"country": "Greece",
"lat": -19.88327,
"lon": 5.713717,
"terminal": {"id": "01hkz69f0m9vxcmgpyrq50dfsg",
"name": "Piraeus Container terminal",
"smdg": null,
"operator": null
}
},
"departureDate": {"timestamp": "2024-01-01T00:00:00.000Z",
"status": "actual",
"localTimeOffset": -3
},
"loadingVessel": {"id": "01hkz69f0m9vxcmgpyrq50dfsg",
"mtId": 12345,
"name": "Madrid Maersk",
"imo": 9778791,
"mmsi": 219836000
},
"voyageNumber": "123A"
},
"portsOfTransshipment": [{"port": {"id": "01hkz69f0m9vxcmgpyrq50dfsg",
"mtId": 12345,
"unlocode": "GRPIR",
"name": "Piraeus",
"country": "Greece",
"lat": -19.88327,
"lon": 5.713717,
"terminal": {"id": "01hkz69f0m9vxcmgpyrq50dfsg",
"name": "Piraeus Container terminal",
"smdg": null,
"operator": null
}
},
"arrivalDate": {"timestamp": "2024-01-01T00:00:00.000Z",
"status": "actual",
"localTimeOffset": -3
},
"departureDate": {"timestamp": "2024-01-01T00:00:00.000Z",
"status": "actual",
"localTimeOffset": -3
},
"loadingVessel": {"id": "01hkz69f0m9vxcmgpyrq50dfsg",
"mtId": 12345,
"name": "Madrid Maersk",
"imo": 9778791,
"mmsi": 219836000
},
"voyageNumber": "123A",
"sequenceNumber": 1
}
],
"portOfDischarge": {"port": {"id": "01hkz69f0m9vxcmgpyrq50dfsg",
"mtId": 12345,
"unlocode": "GRPIR",
"name": "Piraeus",
"country": "Greece",
"lat": -19.88327,
"lon": 5.713717,
"terminal": {"id": "01hkz69f0m9vxcmgpyrq50dfsg",
"name": "Piraeus Container terminal",
"smdg": null,
"operator": null
}
},
"arrivalDate": {"timestamp": "2024-01-01T00:00:00.000Z",
"status": "actual",
"localTimeOffset": -3
}
},
"currentVessel": {"operationalStatus": "slow_steaming_open_sea",
"latestPosition": {"lat": 12.3456,
"lon": 78.9012,
"geographicalArea": "Mediterranean",
"heading": 90,
"speed": 12.5
},
"id": "01hkz69f0m9vxcmgpyrq50dfsg",
"mtId": 12345,
"name": "Madrid Maersk",
"imo": 9778791,
"mmsi": 219836000
},
"tags": [{"id": "01hkz69f0m9vxcmgpyrq50dfsg",
"label": "Tag one"
}
],
"owned": true,
"updated": "2024-01-01T00:00:00.000Z",
"created": "2024-01-01T00:00:00.000Z"
},
"relationships": {"trackingRequest": {"data": {"type": "tracking_request",
"trackingRequestId": "01hkz69f0m9vxcmgpyrq50dfsg"
},
"links": {"related": "https://api.kpler.com/v1/logistics/containers/tracking-requests/01hkz69f0m9vxcmgpyrq50dfsg"
}
}
},
"links": {"self": "https://api.kpler.com/v1/logistics/containers/shipments/01j0qv3jmyete3zwe08nn2dzpa",
"related": "https://api.kpler.com/v1/logistics/containers/shipments/01j0qv3jmyete3zwe08nn2dzpa/trasnportation-timeline"
}
},
"meta": {"webViewLink": "https://www.marinetraffic.com/containers/track-shipment?id=01j0qv3jmyete3zwe08nn2dzpa"
}
}

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": {"type": "transportation-timeline",
"shipmentId": "01j0qv3jmyete3zwe08nn2dzpa",
"attributes": {"containers": [{"id": "01hnahef5ym5x2jfndgma4kc6q",
"number": "HLXU1234567",
"isoCode": "22G1",
"type": "General purpose container",
"size": {"length": 20,
"height": 8.6
}
}
],
"equipmentEvents": [{"id": "01hkz69f0m9vxcmgpyrq50dfsg",
"equipmentEventTypeName": "load",
"eventClassifierCode": "actual",
"equipmentReference": ["01hnahef5ym5x2jfndgma4kc6q"
],
"eventDateTime": "2024-01-01T00:00:00.000Z",
"locationId": "01hkz69f0m9vxcmgpyrq50dfsg",
"vesselId": "01hkz69f0m9vxcmgpyrq50dfsg",
"modeOfTransport": "maritime_transport",
"equipmentEmptyIndicator": "laden",
"eventOrder": 1
}
],
"locations": [{"id": "01hkz69f0m9vxcmgpyrq50dfsg",
"mtId": 12345,
"type": "port_of_Loading",
"unlocode": "GRPIR",
"name": "Piraeus",
"country": "Greece",
"lat": -19.88327,
"lon": 5.713717,
"localTimeOffset": -3,
"terminal": {"id": "01hkz69f0m9vxcmgpyrq50dfsg",
"name": "Piraeus Container terminal",
"smdg": null,
"operator": null
}
}
],
"transportEvents": [{"id": "01hkz69f0m9vxcmgpyrq50dfsg",
"transportEventTypeName": "departure",
"eventClassifierCode": "actual",
"eventDateTime": "2024-01-01T00:00:00.000Z",
"locationId": "01hkz69f0m9vxcmgpyrq50dfsg",
"vesselId": "01hkz69f0m9vxcmgpyrq50dfsg",
"modeOfTransport": "maritime_transport",
"eventOrder": 1
}
],
"vessels": [{"voyageNumber": "123A",
"id": "01hkz69f0m9vxcmgpyrq50dfsg",
"mtId": 12345,
"name": "Madrid Maersk",
"imo": 9778791,
"mmsi": 219836000
}
]
},
"links": {"self": "https://api.kpler.com/v1/logistics/containers/shipments/01j0qv3jmyete3zwe08nn2dzpa/trasnportation-timeline"
}
},
"meta": {"webViewLink": "https://www.marinetraffic.com/containers/track-shipment?id=01j0qv3jmyete3zwe08nn2dzpa"
}
}

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": [{"type": "tag",
"attributes": {"name": "tag 1"
}
}
]
}

Response samples

application/json

{"data": {"shipmentTags": [{"type": "shipment",
"shipmentId": "01j0qv3jmyete3zwe08nn2dzpa",
"attributes": {"name": "tag 1"
}
}
]
}
}

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": [{"type": "tag",
"attributes": {"name": "tag 1"
}
}
]
}

Response samples

application/json

{"data": {"shipmentTags": [{"type": "shipment",
"shipmentId": "01j0qv3jmyete3zwe08nn2dzpa",
"attributes": {"name": "tag 1"
}
}
]
}
}

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": [{"type": "tag",
"attributes": {"name": "tag 1"
}
}
]
}

Response samples

application/json

{"data": {"shipmentTags": [{"type": "shipment",
"shipmentId": "01j0qv3jmyete3zwe08nn2dzpa",
"attributes": {"name": "tag 1"
}
}
]
}
}

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

{"data": [{"type": "event",
"id": "4838690-117-1748361600-departure",
"attributes": {"eventType": "arrival",
"eventStatus": "planned",
"eventTime": "2025-03-20 14:00:00Z"
},
"relationships": {"vessel": {"data": {"type": "vessel",
"id": 4838690
}
},
"port": {"data": {"type": "port",
"id": 117
}
}
}
}
],
"links": {"self": "https://api.kpler.com/v1/logistics/containers/shipping/schedule-events?page=2",
"first": "https://api.kpler.com/v1/logistics/containers/shipping/schedule-events?page=1",
"prev": "https://api.kpler.com/v1/logistics/containers/shipping/schedule-events?page=1",
"next": "https://api.kpler.com/v1/logistics/containers/shipping/schedule-events?page=3"
},
"included": [{"id": "01hkz69f0m9vxcmgpyrq50dfsg",
"mtId": 12345,
"name": "Madrid Maersk",
"imo": 9778791,
"mmsi": 219836000
}
]
}

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:

Register for the service: Contact your account manager to register for the Webhook service.
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

Payload

application/json

{"data": {"type": "webhook_event",
"id": "01j7k957597bmt6x9t6v4nh1gk",
"attributes": {"eventType": "shipment_updated",
"status": "success",
"createdAt": "2024-09-13T12:10:00Z"
},
"relationships": {"trackingRequest": {"data": {"type": "tracking_request",
"id": "01j7k957597bmt6x9t6v4nh1gc"
},
"links": {"self": "https://api.kpler.com/v1/logistics/containers/tracking-requests/01j7k957597bmt6x9t6v4nh1gc"
}
},
"shipment": {"data": {"type": "shipment",
"id": "01j7k95jfkft4bkd6adnf8hwtp"
},
"links": {"self": "https://api.kpler.com/v1/logistics/containers/shipments/01j7k95jfkft4bkd6adnf8hwtp"
}
}
}
},
"included": [{"type": "shipment",
"shipmentId": "01j0qv3jmyete3zwe08nn2dzpa",
"attributes": {"referenceNumberType": "container",
"referenceNumber": "MEDUPE268513",
"carrier": {"scac": "MEDU",
"name": "Maersk Line"
},
"transportationStatus": "booked",
"containers": [{"id": "01hnahef5ym5x2jfndgma4kc6q",
"number": "HLXU1234567",
"isoCode": "22G1",
"type": "General purpose container",
"size": {"length": 20,
"height": 8.6
}
}
],
"insights": {"arrivalDelayDays": 3,
"rollover": [{"initialVessel": {"id": null,
"mtId": null,
"name": null,
"imo": null,
"mmsi": null
},
"newVessel": {"id": null,
"mtId": null,
"name": null,
"imo": null,
"mmsi": null
},
"atPort": {"id": null,
"mtId": null,
"unlocode": null,
"name": null,
"country": null,
"lat": null,
"lon": null,
"terminal": null
},
"detectedAt": "2024-01-01T00:00:00.000Z",
"initialDepartureDate": {"timestamp": null,
"localTimeOffset": null
},
"newDepartureDate": {"timestamp": null,
"localTimeOffset": null
}
}
],
"portOfLoadingChange": [{"initialPort": {"id": null,
"mtId": null,
"unlocode": null,
"name": null,
"country": null,
"lat": null,
"lon": null,
"terminal": null
},
"newPort": {"id": null,
"mtId": null,
"unlocode": null,
"name": null,
"country": null,
"lat": null,
"lon": null,
"terminal": null
},
"detectedAt": "2024-01-01T00:00:00.000Z",
"initialDepartureDate": {"timestamp": null,
"localTimeOffset": null
},
"newDepartureDate": {"timestamp": null,
"localTimeOffset": null
}
}
],
"portOfDischargeChange": [{"initialPort": {"id": null,
"mtId": null,
"unlocode": null,
"name": null,
"country": null,
"lat": null,
"lon": null,
"terminal": null
},
"newPort": {"id": null,
"mtId": null,
"unlocode": null,
"name": null,
"country": null,
"lat": null,
"lon": null,
"terminal": null
},
"detectedAt": "2024-01-01T00:00:00.000Z",
"initialArrivalDate": {"timestamp": null,
"localTimeOffset": null
},
"newArrivalDate": {"timestamp": null,
"localTimeOffset": null
}
}
],
"initialCarrierEta": "2021-01-01T00:00:00Z"
},
"portOfLoading": {"port": {"id": "01hkz69f0m9vxcmgpyrq50dfsg",
"mtId": 12345,
"unlocode": "GRPIR",
"name": "Piraeus",
"country": "Greece",
"lat": -19.88327,
"lon": 5.713717,
"terminal": {"id": "01hkz69f0m9vxcmgpyrq50dfsg",
"name": "Piraeus Container terminal",
"smdg": null,
"operator": null
}
},
"departureDate": {"timestamp": "2024-01-01T00:00:00.000Z",
"status": "actual",
"localTimeOffset": -3
},
"loadingVessel": {"id": "01hkz69f0m9vxcmgpyrq50dfsg",
"mtId": 12345,
"name": "Madrid Maersk",
"imo": 9778791,
"mmsi": 219836000
},
"voyageNumber": "123A"
},
"portsOfTransshipment": [{"port": {"id": "01hkz69f0m9vxcmgpyrq50dfsg",
"mtId": 12345,
"unlocode": "GRPIR",
"name": "Piraeus",
"country": "Greece",
"lat": -19.88327,
"lon": 5.713717,
"terminal": {"id": null,
"name": null,
"smdg": null,
"operator": null
}
},
"arrivalDate": {"timestamp": "2024-01-01T00:00:00.000Z",
"status": "actual",
"localTimeOffset": -3
},
"departureDate": {"timestamp": "2024-01-01T00:00:00.000Z",
"status": "actual",
"localTimeOffset": -3
},
"loadingVessel": {"id": "01hkz69f0m9vxcmgpyrq50dfsg",
"mtId": 12345,
"name": "Madrid Maersk",
"imo": 9778791,
"mmsi": 219836000
},
"voyageNumber": "123A",
"sequenceNumber": 1
}
],
"portOfDischarge": {"port": {"id": "01hkz69f0m9vxcmgpyrq50dfsg",
"mtId": 12345,
"unlocode": "GRPIR",
"name": "Piraeus",
"country": "Greece",
"lat": -19.88327,
"lon": 5.713717,
"terminal": {"id": "01hkz69f0m9vxcmgpyrq50dfsg",
"name": "Piraeus Container terminal",
"smdg": null,
"operator": null
}
},
"arrivalDate": {"timestamp": "2024-01-01T00:00:00.000Z",
"status": "actual",
"localTimeOffset": -3
}
},
"currentVessel": {"operationalStatus": "slow_steaming_open_sea",
"latestPosition": {"lat": 12.3456,
"lon": 78.9012,
"geographicalArea": "Mediterranean",
"heading": 90,
"speed": 12.5
},
"id": "01hkz69f0m9vxcmgpyrq50dfsg",
"mtId": 12345,
"name": "Madrid Maersk",
"imo": 9778791,
"mmsi": 219836000
},
"tags": [{"id": "01hkz69f0m9vxcmgpyrq50dfsg",
"label": "Tag one"
}
],
"owned": true,
"updated": "2024-01-01T00:00:00.000Z",
"created": "2024-01-01T00:00:00.000Z"
},
"relationships": {"trackingRequest": {"data": {"type": "tracking_request",
"trackingRequestId": "01hkz69f0m9vxcmgpyrq50dfsg"
},
"links": {"related": "https://api.kpler.com/v1/logistics/containers/tracking-requests/01hkz69f0m9vxcmgpyrq50dfsg"
}
}
},
"links": {"self": "https://api.kpler.com/v1/logistics/containers/shipments/01j0qv3jmyete3zwe08nn2dzpa",
"related": "https://api.kpler.com/v1/logistics/containers/shipments/01j0qv3jmyete3zwe08nn2dzpa/trasnportation-timeline"
}
}
]
}

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

Payload

application/json

{"data": {"type": "webhook_event",
"id": "01j7k957597bmt6x9t6v4nh1gk",
"attributes": {"eventType": "tracking_request_succeeded",
"status": "success",
"createdAt": "2024-09-13T12:10:00Z"
},
"relationships": {"trackingRequest": {"data": {"type": "tracking_request",
"id": "01j7k957597bmt6x9t6v4nh1gc"
},
"links": {"self": "https://api.kpler.com/v1/logistics/containers/tracking-requests/01j7k957597bmt6x9t6v4nh1gc"
}
},
"shipment": {"data": {"type": "shipment",
"id": "01j7k95jfkft4bkd6adnf8hwtp"
},
"links": {"self": "https://api.kpler.com/v1/logistics/containers/shipments/01j7k95jfkft4bkd6adnf8hwtp"
}
}
}
},
"included": [{"type": "tracking_request",
"trackingRequestId": "01hkz69f0m9vxcmgpyrq50dfsg",
"attributes": {"referenceNumberType": "container",
"referenceNumber": "MEDUPE268513",
"carrier": {"scac": "MEDU",
"name": "Maersk Line"
},
"status": "success",
"failed_reason": null,
"tags": [{"id": "01hkz69f0m9vxcmgpyrq50dfsg",
"label": "Tag one"
}
],
"owned": true,
"created": "2024-01-01T00:00:00.000Z"
},
"links": {"self": "https://api.kpler.com/v1/logistics/containers/tracking-requests/01hkz69f0m9vxcmgpyrq50dfsg"
},
"relationships": {"shipment": {"data": {"type": "shipment",
"shipmentId": "01j0qv3jmyete3zwe08nn2dzpa"
},
"links": {"related": "https://api.kpler.com/v1/logistics/containers/shipments/01j0qv3jmyete3zwe08nn2dzpa"
}
}
}
}
]
}

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

Payload

application/json

{"data": {"type": "webhook_event",
"id": "01j7k957597bmt6x9t6v4nh1gk",
"attributes": {"eventType": "tracking_request_failed",
"status": "failed",
"createdAt": "2024-09-13T12:10:00Z"
},
"relationships": {"trackingRequest": {"data": {"type": "tracking_request",
"id": "01j7k957597bmt6x9t6v4nh1gc"
},
"links": {"self": "https://api.kpler.com/v1/logistics/containers/tracking-requests/01j7k957597bmt6x9t6v4nh1gc"
}
}
}
},
"included": [{"type": "tracking_request",
"trackingRequestId": "01hkz69f0m9vxcmgpyrq50dfsg",
"attributes": {"referenceNumberType": "container",
"referenceNumber": "MEDUPE268513",
"carrier": {"scac": "MEDU",
"name": "Maersk Line"
},
"status": "success",
"failed_reason": null,
"tags": [{"id": "01hkz69f0m9vxcmgpyrq50dfsg",
"label": "Tag one"
}
],
"owned": true,
"created": "2024-01-01T00:00:00.000Z"
},
"links": {"self": "https://api.kpler.com/v1/logistics/containers/tracking-requests/01hkz69f0m9vxcmgpyrq50dfsg"
},
"relationships": {"shipment": {"data": {"type": "shipment",
"shipmentId": "01j0qv3jmyete3zwe08nn2dzpa"
},
"links": {"related": "https://api.kpler.com/v1/logistics/containers/shipments/01j0qv3jmyete3zwe08nn2dzpa"
}
}
}
}
]
}

2025-06-17

Update

Documentation: Reset OpenAPI version to 1.0.0 to align with the /v1/ server path.

No change in functionality.

2025-06-10

Updates

Documentation: Updated code samples to use the correct server URL https://api.kpler.com/v1/logistics/containers
Documentation: Updated the attribute name from portOfTranshipment to portsOfTransshipment in the GET /shipments/{shipmentId} endpoint to match the actual API response.

2025-05-26

New

API: New Endpoint, Container Shipping, Get schedule events GET /shipping/schedule-events
API: New Server URL, https://api.kpler.com/v1/logistics/containers
API: New API Key Header, X-Container-API-Key
Documentation: Changelog introduction

Deprecated

The following items are deprecated.

API: Server URL, https://api.kpler.com/v1/logistics/container-tracking
API: API Key Header, X-Container-Tracking-API-Key

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.

Updates

Documentation: Global reorganization with the introduction of the Shipping schedules endpoint.

MarineTraffic Containers API (1.0.0)

Introduction

Get your API key

Supported Shipping Lines / Freight Forwarders & SCAC List

Rate Limits

IP Whitelisting

Tracking requests

Create tracking requests

Request Body schema: application/jsonrequired

List tracking requests

query Parameters

Get tracking request details

path Parameters

(Un)Archive tracking requests

path Parameters

Request Body schema: application/jsonrequired

Shipments

List shipments

query Parameters

Get shipment summary

path Parameters

Get shipment detailed milestones

path Parameters

Replace all shipment tags

path Parameters

Request Body schema: application/jsonrequired

Add tags to a shipment

path Parameters

Request Body schema: application/jsonrequired

Remove tags from a shipment

path Parameters

Request Body schema: application/jsonrequired

Schedules

Get schedule events for a container vessel or a port

query Parameters

Webhook events

Introduction

Getting Started

Webhook Security

Error Handling

shipment_updatedWebhook

Request Body schema: application/json

tracking_requested_succeededWebhook

Request Body schema: application/json

tracking_requested_failedWebhook

Request Body schema: application/json

2025-06-17

Update

2025-06-10

Updates

2025-05-26

New

Deprecated

Updates

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required