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 schema

57 fields

Nested exactly as the JSON is. Open a branch to read its fields; hover a name for the full dot-path.

api_versionstring

The response contract this build answers, as a date. Pin it in your client and nothing in the shape below moves under you.

okboolean

False on a non-hit. The HTTP status is still 200, so branch on this and not on the status code.

dataobject

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

identifierstring

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

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.

carrier_codestring

Carrier SCAC.

carrier_namestring

Carrier name.

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.

etastring

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

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.

originstring

Origin code (airport IATA or UN/LOCODE).

destinationstring

Destination code (airport IATA or UN/LOCODE).

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.

namestring

Human-readable name.

latnumber | null

Latitude.

lngnumber | null

Longitude.

eventsobject[]

Milestone timeline, oldest to newest.

events[]object

descriptionstring

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

locationstring

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

event_codestring

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

unlocodestring

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

datetimestring

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

actualboolean

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

equipmentobject

Equipment and cargo particulars, present only when the line publishes at least one of them. Absent entirely on a line that publishes none, which is not the same as a block full of nulls.

size_typestring

Equipment size and type as the carrier writes it, for example 40HC.

iso_codestring

ISO 6346 size and type code as the carrier filed it, for example 45G1. Null when the carrier stated none.

seal_numberstring | null

Carrier seal on the box. Null unless the carrier publishes it, which most do not on a track response.

move_typestring

The scope of the move the carrier is performing, for example port to port or door to door. Null when unstated.

vgm_kgnumber | null

Verified gross mass, kilograms. Null until the shipper files a VGM and the carrier publishes it.

gross_weight_kgnumber

Gross weight of the loaded box, kilograms. Null when the carrier publishes none.

package_countnumber

Pieces inside the box. Null when the carrier publishes no cargo particulars.

package_unitstring

Unit the package count is in, for example CTN or PLT. Null with the count.

measurement_cbmnumber | null

Cargo volume, cubic metres. Null when the carrier publishes none.

service_requirementstring | null

A special handling requirement filed on the shipment, for example a reefer set point. Null when none.

not_published_by_carrierstring[]

The particulars we asked for and this carrier does not publish. Read it as "the line does not expose this", never as "the shipment has none".

observabilityobject

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

lensesobject

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

actualsboolean

True when we hold carrier milestones.

positionboolean

True when we hold a vessel.

planboolean

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

probabilityboolean

True when the ETA can carry a confidence figure.

active_countnumber

How many of the four lenses are present.

line_correctionobject

Present only when you named one carrier and the reference turned out to belong to another: what you searched, and what we found it under. Absent on a normal answer.

searched_codestring

The SCAC you named.

searched_namestring

That line by name.

found_codestring

The SCAC the reference actually belongs to.

found_namestring

That line by name.

messagestring

The one sentence to show a user on a non-hit, already written for that purpose.

diagnosisobject

Why there is no answer, machine-readable, on every non-hit. It is the difference between a mistyped number and a real reference the line has not published yet.

ref_typestring

What the reference was read as: container, bl or booking.

iso6346string

Whether a container number passes the ISO 6346 check digit: valid, invalid, or not_applicable on a bill of lading or booking.

ownerstring | null

The registered owner behind the prefix, when the prefix is registered. Null when it is not.

owner_classstring | null

What that owner is: carrier, leasing, soc for a shipper-owned box, or unknown.

likelystring

Our best single explanation: check_digit_typo, incomplete_reference, carrier_no_live_events, leased_needs_bl, soc_needs_bl, house_bl or unidentified_line.

recommendationstring

What to do about it, in one sentence you can show a user as is.

suggestionsstring[]

Corrected container numbers, present only on a check-digit typo. At most two, and each one passes the check digit.

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

{
  "api_version": "2026-08-04",
  "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
      }
    ],
    "equipment": {
      "size_type": "40HC",
      "iso_code": "45G1",
      "seal_number": null,
      "move_type": "CY/CY",
      "vgm_kg": null,
      "gross_weight_kg": 24680,
      "package_count": 1120,
      "package_unit": "CTN",
      "measurement_cbm": null,
      "service_requirement": null
    },
    "not_published_by_carrier": [
      "seal_number"
    ],
    "observability": {
      "lenses": {
        "actuals": true,
        "position": true,
        "plan": true,
        "probability": true
      },
      "active_count": 4
    }
  },
  "line_correction": {
    "searched_code": "HLCU",
    "searched_name": "Hapag-Lloyd",
    "found_code": "MSCU",
    "found_name": "MSC"
  }
}

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