Look up by 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.
Counted: REST: 1 call per keyed request, whatever the route answers; a quota refusal is not counted. MCP: 10 Navo Tokens when the answer carries data; free on 202 STILL_RESOLVING, 404 REFERENCE_NOT_RESOLVABLE and 404 AUTO_CANT_FIND_INFO. A reference new to us is added (250). See what counts as a successful request.
Path parameters
The container number, bill of lading or booking you tracked.
Response schema
211 fields
Generated from the OpenAPI spec. Nested exactly as the JSON is. Open a branch to read its fields; hover a name for the full dot-path.
Whether the request succeeded.
The response contract this build answers, as a date.
data
The payload.
Stable identifier for the record.
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.
The bill of lading, or null when the record was not tracked by one.
The container number, bill of lading or booking this record tracks.
What the identifier is.
The booking reference, or null when the record was not tracked by one.
Equipment size, for example 40HC.
Equipment family as the carrier names it.
The type half of the ISO 6346 code (G1 for a general-purpose box, R1 for a reefer).
The boxes a bill of lading or booking resolves to, each with its own timeline and its own status (with status_source: tracked when your organisation also tracks the box on its own line, line when read from the events the line filed for that box on this document, document when the document holds no per-box events and none of its events names another box, so the box shows the document's own status, which can be a stage read from the vessel's AIS, such as at_berth or at_anchor; both null when none has reported one).
child_containers[]
Container number of the box, or TBA for a group of boxes the line has not numbered yet.
ISO equipment type code of the box, for example 45G1.
The line's own size and type label for the box.
The box's own status, which can differ from the status of the document. One of: pre_departure, in_transit, at_transshipment, arriving, at_anchor, at_berth, discharged, customs_hold, available, delivered, returned_empty.
Where the box status came from: its own tracked row, the line's events for that box, or the document status.
The box's own timeline; an empty array when no per-box timeline is known yet.
events[]
Milestone code of the move, for example GTIN, LOAD, DEPA, ARRI, DISC or GTOT.
Readable name of the move, the same wording the dashboard shows.
Family the move belongs to.
Conveyance the line stated for the move.
True when the move has happened, false when it is planned or estimated.
True when a planned move is served as done because a later actual move proves it happened.
When the move happened or is planned, as a UTC instant when the port time zone is known.
The same moment on the port wall clock, without an offset.
IANA time zone of the port, for example Asia/Shanghai.
Minutes to add to UTC to get the port wall clock.
How the timestamp was obtained, so a client knows whether it is a true instant. One of: carrier_offset, tz_resolved, date_only, local_unplaced, legacy_unknown.
UN/LOCODE of the place of the move.
Where the served UN/LOCODE came from. One of: carrier, matched_in_country, matched_port_name, corrected, not_determined, recorded.
Place name as the line wrote it.
Terminal, depot or other facility name as the line wrote it.
Name of the ship for this move.
IMO number of the ship for this move, as a string.
Voyage number the line stated for this move.
The line's own wording for the move.
The line's own status remark for the move.
Whether the box was empty or laden at this move.
Who stated the fill state: the line, or nobody.
What a gate-out did: moved the box on, or handed it to the consignee. One of: transfer, consignee_delivery, not_reported.
Current normalised status of the shipment.
Carrier name, falling back to the SCAC when we hold no name.
Name of the carrying vessel, or null when the carrier named none.
IMO number of the carrying vessel, or null when unknown.
planned_vessel
The ship the box is waiting for: before its first actual load while its planned load at the port of loading is still ahead or at most 3 days past, or at a transshipment hub before the reload.
Name of the planned ship.
IMO number of the planned ship, as a string.
Voyage number of the planned sailing.
position
Latest AIS position of the planned ship; null when the fix is older than 48 hours, the plan has lapsed, or the ship has already left the load port.
Latitude of the ship.
Longitude of the ship.
When the ship was observed at this position.
heading_to
The port where the box is planned to load.
UN/LOCODE of the planned load port.
Name of the planned load port.
When the box is planned to load onto this ship.
Always planned.
vessel_position
Live AIS position of the carrying vessel.
Latitude.
Longitude.
Origin port name, falling back to its UN/LOCODE.
Destination port name, falling back to its UN/LOCODE.
Arrival time (ISO 8601) of the vessel (the ARRI event) at the port in destination_unlocode: planned until it arrives, actual after (see eta_is_estimated).
How often this lane arrives on time, as a percentage.
The more recent of the carrier check and the AIS fix: when we last learned anything about this shipment.
Which of the two produced last_updated_at: carrier_poll or ais_vessel_position.
When we last asked the carrier (ISO 8601).
When the vessel was last actually observed by AIS, or null when we hold no fix.
field_provenance
Per-field account of WHY a declared field is empty, keyed by field name.
{field}
Why the field stands where it does: resolved, contract_required, not_published, not_applicable or awaiting_carrier.
What would change the state: supply_terms, wait, or do_not_expect when nothing will.
Where the answer on this call came from: direct_carrier or warm_db.
On a card, whether the slot partners agree with each other.
The reasoning behind the state, in one sentence, so a support answer does not need our source.
Days of free time left, or null when no terms are on file.
Reserved for a written summary of the shipment.
Milestone timeline, oldest to newest.
events[]
Event code, for example DEPA or LOAD.
DCSA classifier: ACT for actual, EST for estimated, PLN for planned.
True when the event happened.
The event in plain words.
Event timestamp (ISO 8601).
The port wall-clock for the same moment, naive and with no offset, exactly as a terminal prints it.
Minutes to add to the UTC instant to reach the local wall-clock.
IANA zone of the port, which survives a DST change in a way a bare offset cannot.
True when the carrier published a calendar date with no time of day.
The calendar date, YYYY-MM-DD, when date_only is true.
UN/LOCODE for the event, or null when the carrier gave no place.
EMPTY or LADEN, on equipment events.
Who stated the fill state of an equipment event: carrier when the line reported EMPTY or LADEN, not_reported when it did not.
What a gate-out did, in the line's own words: transfer when the line says the box moved on (to another terminal, a rail ramp or a train), consignee_delivery when it says the consignee took the box, not_reported when it says neither.
The container the event happened to.
Name of the ship for this move.
IMO number of the ship for this move, as a string.
Voyage number the line stated for this move.
True on a past plan the line left behind a later actual move.
True when the line named a terminal, hub or depot for this arrival.
carrier_document_reply
Latest retained, exact-reference OOCL document reply.
carrier_notice
Latest reference-specific reply from the named carrier.
One of: other_carrier, temporarily_unavailable, not_found, invalid_reference, SHIPMENT_CANCELLED, no_longer_available.
True when the boxes of a multi-box document are at different stages; null when it cannot be worked out.
True when some but not all boxes of a multi-box document have been discharged; null when it cannot be worked out.
Our own arrival forecast when it differs from the ETA served in eta; null when we have none, when it equals eta, or once the arrival is a fact.
ais_pol_departure
AIS saw the vessel carrying the box leave its port of loading while the line has not reported a departure there: the box's last actual load at that port names the vessel, nothing has discharged it there since, and the vessel's call at that port spans the load.
When the ship left the port of loading, by our AIS port call record.
UN/LOCODE of the port of loading.
Name of the port of loading.
IANA time zone of the port of loading.
IMO number of the ship.
Name of the ship.
Always ais.
A sentence you can show as-is.
When tracking stopped. Only on status 202, 400, 401, 402, 403, 404, 409, 429, 500, 503 and 504.
Null when your account archived it, otherwise the reason our archiver closed it. Only on status 202, 400, 401, 402, 403, 404, 409, 429, 500, 503 and 504.
resume
Only on status 202, 400, 401, 402, 403, 404, 409, 429, 500, 503 and 504.
body
The reference to add again.
error
Only on status 202, 400, 401, 402, 403, 404, 409, 429, 500, 503 and 504.
Machine readable error code.
Human readable explanation.
How serious the error is.
True.
The reference.
Seconds to wait.
Offending fields.
CONTAINER_QUOTA_EXCEEDED only.
Tokens this request needs.
Tokens the wallet holds.
Where to top up.
Plans on offer.
packages[]
Plan key.
Tokens per month.
Monthly price in USD.
CARRIER_NOT_IDENTIFIED only.
CARRIER_NOT_IDENTIFIED, timed out only.
The member cycle limit.
Tokens the member has used this cycle.
Tokens left for the member.
Seconds until the next refresh is allowed.
progress
One of: SEALINE_HASNT_PROVIDE_INFO, NO_EVENTS, WRONG_NUMBER, REFERENCE_REQUIRED, LINE_NOT_SUPPORTED, PENDING, UNRESOLVED.
previous_trip
The trip before yours for this box, when the line still reports it.
The line that answered, as its SCAC.
last_event
events[]
A note for leasing-company accounts when no line holds the box yet.
One of: in_progress, not_supported, connected, reference_required.
carrier_notice
Latest reference-specific reply from the named carrier. Only on status 202, 400, 401, 402, 403, 404, 409, 429, 500, 503 and 504.
One of: other_carrier, temporarily_unavailable, not_found, invalid_reference, SHIPMENT_CANCELLED, no_longer_available.
Present when the line named was not used. Only on status 202, 400, 401, 402, 403, 404, 409, 429, 500, 503 and 504.
Known line that cannot be asked. Only on status 202, 400, 401, 402, 403, 404, 409, 429, 500, 503 and 504.
upgrade
CONTAINER_QUOTA_EXCEEDED only. Only on status 202, 400, 401, 402, 403, 404, 409, 429, 500, 503 and 504.
Next plan.
Monthly price.
Annual price.
Why the line named was not used. Only on status 202, 400, 401, 402, 403, 404, 409, 429, 500, 503 and 504.
Errors
A failure carries { "ok": false, "error": { "code", "message", "severity" } }. Branch on the code, and log the message.
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.
The key is missing, malformed or revoked.
MCP calls on Navo Tokens only: your balance cannot pay for this call. Nothing is charged and no data is returned. Besides code and message, the error carries credits_required, credits_balance, top_up_url and packages (see Navo Tokens on the TrackingMCP reference page). A REST call on your API key never meets this.
No line recognises this reference. Check the check digit before retrying: a wrong one keeps failing.
We could not read the record. Retry.
curl 'https://api.navo24.com/v1/tracking/containers/lookup/MEDU1234562' \
-H "Authorization: Bearer tmcp_YOUR_API_KEY"const res = await fetch("https://api.navo24.com/v1/tracking/containers/lookup/MEDU1234562", {
headers: {
"Authorization": "Bearer tmcp_YOUR_API_KEY"
}
});
const data = await res.json();import requests
res = requests.get(
"https://api.navo24.com/v1/tracking/containers/lookup/MEDU1234562",
headers={"Authorization": "Bearer tmcp_YOUR_API_KEY"},
)
data = res.json(){
"api_version": "2026-08-04",
"ok": true,
"data": {
"id": "8f1c2d4e-6a3b-4f52-9c70-11ab22cd33ef",
"container_number": "ONEU1234567",
"bl_number": null,
"identifier": "ONEU1234567",
"identifier_type": "container_id",
"booking_number": null,
"container_size": "40HC",
"equipment_type": "High Cube Dry",
"iso_type_code": "45G1",
"child_containers": null,
"status": "discharged",
"carrier": "Maersk",
"vessel_name": "MAERSK NORDDAL",
"vessel_imo": "9894674",
"vessel_position": {
"lat": 21.37788,
"lng": 91.643204
},
"origin_name": "XIAMEN",
"destination_name": "CHITTAGONG",
"eta": "2026-08-14T07:24:00+00:00",
"eta_confidence_pct": 97,
"last_updated_at": "2026-08-16T11:20:18+00:00",
"last_updated_source": "ais_position",
"last_polled_at": "2026-08-16T03:50:21.692+00:00",
"last_ais_fix_at": "2026-08-16T11:20:18+00:00",
"field_provenance": {
"last_updated_at": {
"state": "resolved",
"action": "none",
"source": "ais_vessel_position",
"confidence": "exact",
"evidence": "The vessel carrying this shipment was observed at a position at 2026-08-16T11:20:18+00:00, more recently than our last carrier check at 2026-08-16T03:50:21.692+00:00. A position fix locates the ship; it does not report container milestones, so the carrier is still polled on its own cadence."
}
},
"demurrage_free_days_left": null,
"ai_narrative": null,
"events": [
{
"type": "GTOT",
"classifier": "ACT",
"is_actual": true,
"label": "Gate out",
"timestamp": "2026-07-25T04:05:00+00:00",
"event_local_datetime": "2026-07-25T12:05:00",
"utc_offset_minutes": 480,
"event_timezone": "Asia/Shanghai",
"date_only": false,
"event_date": null,
"location": "CNXMN"
},
{
"type": "GTIN",
"classifier": "ACT",
"is_actual": true,
"label": "Gate in",
"timestamp": "2026-07-25T11:05:00+00:00",
"event_local_datetime": "2026-07-25T19:05:00",
"utc_offset_minutes": 480,
"event_timezone": "Asia/Shanghai",
"date_only": false,
"event_date": null,
"location": "CNXMN"
}
]
}
}