POSTNo key

Public one-off lookup

POSTapi.trackingmcp.com/v1/track/public

Resolve a single container, bill of lading or booking without an account. No key required. Rate-limited, and intended for a quick check rather than a portfolio.

Request body

referencestringrequired

Container number (4 letters + 7 digits), bill of lading, or booking reference.

reference_typestring

Optional client-side guess: container_id, bill_of_lading or booking_number. The server refines it and returns what it actually resolved.

carrier_codestring

Optional SCAC hint. Omit it and we resolve the line ourselves.

Response fields

Derived from the example response.

okboolean

Whether the request succeeded.

dataobject

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

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.carrier_codestring

Carrier SCAC.

data.carrier_namestring

Carrier name.

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.etastring

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

data.eta_is_estimatedboolean

True when the ETA is still a forecast, false when it is the actual arrival, null when there is no ETA at all. Never read a date alone as a promise.

data.originstring

Origin code (airport IATA or UN/LOCODE).

data.destinationstring

Destination code (airport IATA or UN/LOCODE).

data.vesselobject

Vessel currently carrying the container, or null when we hold neither a name nor an IMO. Its lat and lng are always null here; the keyed endpoints carry the live position under vessel_position.

data.vessel.namestring

Human-readable name.

data.vessel.latnull

Latitude.

data.vessel.lngnull

Longitude.

data.eventsobject[]

Milestone timeline, oldest to newest.

data.events[].descriptionstring

The carrier own phrasing for the event, falling back to our word for the code.

data.events[].locationstring

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

data.events[].event_codestring

Machine-readable event code, for example LOAD, DISC, GTIN, GTOT, ARRI, DEPA. Null when the carrier sent none.

data.events[].unlocodestring

UN/LOCODE port code. On a tracking event it is canonicalised, and null when the carrier named no port.

data.events[].datetimestring

Event timestamp (ISO 8601), or null when the carrier gave none.

data.events[].actualboolean

True when the event happened. False means it is planned or estimated, so never read it as a fact.

data.observabilityobject

Which of the four lenses we can offer on this shipment, and how many are active.

data.observability.lensesobject

actuals (carrier milestones), position (the vessel), plan (a schedule) and probability (a confidence figure).

data.observability.lenses.actualsboolean

True when we hold carrier milestones.

data.observability.lenses.positionboolean

True when we hold a vessel.

data.observability.lenses.planboolean

On LoadingMCP, the computed load plan. Inside a tracking observability lens, true when we hold a schedule for the shipment.

data.observability.lenses.probabilityboolean

True when the ETA can carry a confidence figure.

data.observability.active_countnumber

How many of the four lenses are present.

Errors

A failure on an open endpoint answers { "ok": false } with a human-readable message. Branch on the status code.

reference is required400

The body carried no reference. Open endpoints answer { "ok": false, "message": … } rather than the coded envelope.

not found404

We could not resolve the reference with any line. The message explains what we tried, and suggests a corrected check digit when the number is one digit off.

gated429

Over the per-IP daily cap. The body carries "gated": true. Anything portfolio-shaped belongs on the keyed surface.

Try it No key

reference * body reference_type body carrier_code body

curl -X POST 'https://api.trackingmcp.com/v1/track/public' \
  -H "Content-Type: application/json" \
  -d '{"reference":"MEDU1234562"}'

const res = await fetch("https://api.trackingmcp.com/v1/track/public", {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "reference": "MEDU1234562"
  })
});
const data = await res.json();

import requests

res = requests.post(
    "https://api.trackingmcp.com/v1/track/public",
    json={
      "reference": "MEDU1234562"
    },
)
data = res.json()

Sample response example

{
  "ok": true,
  "data": {
    "identifier": "MEDU1234562",
    "identifier_type": "container_id",
    "carrier_code": "MSCU",
    "carrier_name": "MSC",
    "status": "in_transit",
    "eta": "2026-07-03T06:00:00Z",
    "eta_is_estimated": true,
    "origin": "Ningbo",
    "destination": "Rotterdam",
    "vessel": { "name": "MSC TERESA", "lat": null, "lng": null },
    "events": [
      {
        "description": "Loaded on vessel",
        "location": "Ningbo",
        "event_code": "LOAD",
        "unlocode": "CNNGB",
        "datetime": "2026-06-18T22:10:00Z",
        "actual": true
      }
    ],
    "observability": {
      "lenses": { "actuals": true, "position": true, "plan": true, "probability": true },
      "active_count": 4
    }
  }
}

This preview uses documented example data and makes no live request. Get a key to run live.