GETAPI key

Look up by identifier

GETapi.trackingmcp.com/v1/containers/lookup/{identifier}

Resolve a container number, bill of lading or booking straight to its record, without holding the UUID. Handy when your own system keys on the carrier reference. One thing to know before you loop over it: an identifier you are not tracking yet is registered on the spot, which consumes a shipment slot exactly as an add would, and the call answers 202 with TRACKING_IN_PROGRESS while the carrier is asked.

Path parameters

identifierstringrequired

The container number, bill of lading or booking you tracked.

Response fields

Derived from the example response.

okboolean

Whether the request succeeded.

dataobject

The payload. Everything an endpoint returns sits under this key.

data.idstring

Stable identifier for the record. On the tracking endpoints this is the container UUID, except on a portfolio summary row, where it is the container number.

data.identifierstring

The container number, bill of lading or booking this record tracks.

data.identifier_typestring

What the identifier is. The keyed surface uses container_id, bill_of_lading or booking; the public tracker returns booking_number for the third.

data.container_numberstring

The container number, or null when the record was tracked by a bill of lading or booking that has not yet resolved to a box.

data.bl_numbernull

The bill of lading, or null when the record was not tracked by one.

data.booking_numbernull

The booking reference, or null when the record was not tracked by one.

data.child_containersnull

The boxes a bill of lading or booking resolves to, each with its own timeline. Null on a plain container lookup.

data.statusstring

Current normalised status of the shipment. Ocean lifecycle order: discharged, available, delivered, returned_empty. Two values end a shipment, delivered and returned_empty, and returned_empty outranks delivered.

data.carrierstring

Carrier name, falling back to the SCAC when we hold no name.

data.vessel_namestring

Name of the carrying vessel, or null when the carrier named none.

data.vessel_imostring

IMO number of the carrying vessel, or null when unknown.

data.vessel_positionobject

Live AIS position of the carrying vessel. Null when we hold no IMO or no fix yet.

data.vessel_position.latnumber

Latitude.

data.vessel_position.lngnumber

Longitude.

data.origin_namestring

Origin port name, falling back to its UN/LOCODE.

data.destination_namestring

Destination port name, falling back to its UN/LOCODE.

data.etastring

Arrival time (ISO 8601). Null when the carrier publishes none and we cannot predict one.

data.eta_confidence_pctnumber

How often this lane arrives on time, as a percentage. Null on a lane too thin to score.

data.last_updated_atstring

The more recent of the carrier check and the AIS fix: when we last learned anything about this shipment.

data.last_updated_sourcestring

Which of the two produced last_updated_at: carrier_poll or ais_vessel_position. Null when neither has happened yet.

data.demurrage_free_days_leftnull

Days of free time left, or null when no terms are on file.

data.ai_narrativenull

Reserved for a written summary of the shipment. Currently always null.

data.eventsobject[]

Milestone timeline, oldest to newest.

data.events[].typestring

Event code, for example DEPA or LOAD.

data.events[].classifierstring

DCSA classifier: ACT for actual, EST for estimated, PLN for planned.

data.events[].is_actualboolean

True when the event happened. False means planned or estimated.

data.events[].labelstring

The event in plain words. A non-actual event is tagged "(planned)".

data.events[].timestampstring

Event timestamp (ISO 8601).

data.events[].locationstring

UN/LOCODE for the event, or null when the carrier gave no place.

Errors

A failure carries { "ok": false, "error": { "code", "message", "severity" } }. Branch on the code, and log the message.

TRACKING_IN_PROGRESS202

Not a failure and not a not-found. The identifier is registered and the carrier has not answered yet. The body carries retry_after_seconds. Poll again rather than adding the box a second time. Note that ok is false on a 202 here, so branch on the status, not on ok alone.

UNAUTHORIZED401

The key is missing, malformed or revoked.

REFERENCE_NOT_RESOLVABLE404

No line recognises this reference. Check the check digit before retrying: a wrong one keeps failing.

DB_ERROR500

We could not read the record. Retry.

curl 'https://api.trackingmcp.com/v1/containers/lookup/MEDU1234562' \
  -H "Authorization: Bearer tmcp_YOUR_API_KEY"

const res = await fetch("https://api.trackingmcp.com/v1/containers/lookup/MEDU1234562", {
  headers: {
    "Authorization": "Bearer tmcp_YOUR_API_KEY"
  }
});
const data = await res.json();

import requests

res = requests.get(
    "https://api.trackingmcp.com/v1/containers/lookup/MEDU1234562",
    headers={"Authorization": "Bearer tmcp_YOUR_API_KEY"},
)
data = res.json()

Response

{
  "ok": true,
  "data": {
    "id": "8f1c2d4e-6a3b-4f52-9c70-11ab22cd33ef",
    "identifier": "MEDU1234562",
    "identifier_type": "container_id",
    "container_number": "MEDU1234562",
    "bl_number": null,
    "booking_number": null,
    "child_containers": null,
    "status": "in_transit",
    "carrier": "MSC",
    "vessel_name": "MSC TERESA",
    "vessel_imo": "9754105",
    "vessel_position": { "lat": 36.12, "lng": 14.55 },
    "origin_name": "Ningbo",
    "destination_name": "Rotterdam",
    "eta": "2026-07-03T06:00:00Z",
    "eta_confidence_pct": 78,
    "last_updated_at": "2026-08-07T08:40:00Z",
    "last_updated_source": "carrier_poll",
    "demurrage_free_days_left": null,
    "ai_narrative": null,
    "events": [
      {
        "type": "DEPA",
        "classifier": "ACT",
        "is_actual": true,
        "label": "Departed",
        "timestamp": "2026-06-18T22:10:00Z",
        "location": "CNNGB"
      }
    ]
  }
}