Skip to content
Navo24Navo24
POSTAPI keyCounts as a call

Force update

POSTapi.navo24.com/v1/tracking/containers/{id}/refresh

Ask the shipping line about this shipment now and wait for its answer, up to 25 seconds. The body is the same record as container detail, shortened in the example here, plus a refresh block that says what happened. When the line answered in time, refresh.refreshed is true. When it did not, data is the last answer we hold, refresh.from_cache is true and refresh.reason says why; after a timeout the ask keeps running and a later read serves its answer.

Counted: REST: 1 call per keyed request, whatever the route answers; a quota refusal is not counted. See what counts as a successful request.

Path parameters

idstringrequired

The container UUID, or a container, bill of lading or booking number your account tracks.

Response schema

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

okboolean

Whether the request succeeded.

api_versionstring

The response contract this build answers, as a date.

dataobject

The payload.

idstring

Stable identifier for the record.

org_idstring

Your organisation.

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.

bl_numberstring | null

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

booking_numberstring | null

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

carrier_codestring

Carrier SCAC.

carrier_namestring

Carrier name.

iso_codestring | null

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

size_teuinteger | null

Size in TEU: 1 for a 20ft box, 2 for a 40ft.

container_typestring | null

Plain-language equipment type, for example Reefer or Dry.

statusstring

Current normalised status of the shipment.

origin_unlocodestring

Origin port UN/LOCODE, or null when the carrier named no origin we could resolve.

destination_unlocodestring

Destination port UN/LOCODE, or null when unresolved.

origin_namestring

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

destination_namestring

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

etastring

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

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.

eta_confidence_pctinteger

How often this lane arrives on time, as a percentage.

discharge_datetimestring | null

When the box was discharged, which is when free time starts counting.

free_daysinteger | null

Free days the terms allow at this port.

last_free_daystring | null

The last day free of charge, computed from the discharge and the free days.

demurrage_at_riskboolean

True when the free-time clock on this box is a concern.

demurrage_accrued_usdnumber | null

Demurrage charged so far on this box, US dollars.

tagsstring[] | null

Your own labels on this box.

notesstring | null

Your own free-text note on this box.

added_atstring

When you started tracking this box (ISO 8601).

last_polled_atstring

When we last asked the carrier (ISO 8601).

poll_prioritystring

Which polling cadence this box sits in (pre_departure, transit, arrival, dwell).

archived_atstring | null

When tracking stopped, or null while the box is still active.

identifierstring

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

identifier_typestring

What the identifier is.

current_vessel_imostring

IMO of the hull carrying the box now.

current_voyage_idstring | null

Carrier voyage number for the current leg.

demurrage_daily_rate_usdnumber | null

Daily demurrage rate in force at the destination, US dollars.

demurrage_last_free_daystring | null

The last day before demurrage accrues, or null when no terms are on file.

last_poll_triggerstring | null

What caused the most recent carrier check: a schedule, your recheck call, or a webhook.

tracker_latstring | null

Latitude from a physical IoT tracker on the box, when you feed us one.

tracker_lngstring | null

Longitude from that device.

tracker_updated_atstring | null

When the device last reported.

tracker_has_alertboolean

True when the device raised an alert, for example a door opening or a temperature excursion.

customs_hold_reasonstring | null

Why customs is holding the box, when the carrier names a reason.

customs_hold_sincestring | null

When the hold started.

container_sizestring | null

Equipment size, for example 40HC.

equipment_typestring | null

Equipment family as the carrier names it.

iso_type_codestring | null

The type half of the ISO 6346 code (G1 for a general-purpose box, R1 for a reefer).

unresolvable_sincestring | null

When we gave up resolving this reference.

route_alertstring | null

A route problem we detected, for example a destination change or a missed connection.

planned_departure_atstring

Departure the carrier planned or actually filed for the load port.

current_vessel_namestring

Name of that hull.

cargo_cutoff_atstring | null

Cargo (gate) cutoff at the load port.

vgm_cutoff_atstring | null

VGM filing cutoff.

si_cutoff_atstring | null

Shipping-instruction cutoff.

customs_release_cutoff_atstring | null

Customs-release cutoff at the load port.

cutoff_enrichmentobject | null

What the line returned beside the events: the boxes of a document, the route it states, and line-specific extras. Free-form: the keys inside depend on the shipping line, so the ones listed here are examples, not a fixed set.

bl_containersstring[]

Every container number on the bill of lading or booking, as listed by the carrier.

bl_container_countinteger

How many containers the document names, including any the carrier has not numbered yet.

containersarray

One entry per container on the document that has its own timeline. Each item is free-form: its keys depend on the shipping line, so the ones listed here are examples, not a fixed set.

containers[]object
numberstring

Container number.

container_sizestring | null

Normalised size and type, for example 40HC.

iso_codestring | null

ISO 6346 size and type code, for example 45G1.

size_rawstring | null

The carrier's size and type string before normalisation.

events_sourcedboolean

True when this timeline was fetched for this container specifically and is not a copy of the shipment timeline.

source_outcomestring

sourced when the carrier returned movements for this container, no_data when it answered and published none.

eventsarray

This container's own events, in the same shape as an event raw_payload. Each item is free-form: its keys depend on the shipping line, so the ones listed here are examples, not a fixed set.

events[]object
datetimestring

The event instant in UTC (ISO 8601).

timezonestring | null

IANA time zone of the event port, null when it could not be resolved.

unlocodestring | null

UN/LOCODE of the event place, null when none is known.

is_actualboolean

True when the event happened, false when it is planned or estimated.

port_namestring | null

Place name as the carrier wrote it.

event_codestring

Normalised event code, for example LOAD, DISC, GTIN, GTOT, ARRI, DEPA, STUF, STRP, AVPU, CUSR, CUSI, CUSS; an unmapped carrier code passes through as written.

vessel_imostring | null

IMO number of the vessel on this move, null when unknown or not a plausible IMO.

descriptionstring | null

The carrier's wording for the event.

source_kindstring

Which kind of source produced the event: carrier when the line answered directly; any other value means the event reached us another way.

vessel_namestring | null

Name of the vessel on this move.

event_familystring

Family the code belongs to: EQUIPMENT, TRANSPORT or SHIPMENT.

voyage_numberstring | null

Carrier voyage number for this move.

datetime_basisstring

What the connector emitted before normalisation: utc for a true instant, port_local for a port wall clock.

datetime_localstring | null

The wall clock at the event port as a zoneless ISO string, for example 2026-07-21T11:07:00.

time_semanticsstring

How the instant was established: carrier_offset, tz_resolved, date_only, local_unplaced or legacy_unknown.

transport_modestring | null

Mode of transport for the leg: VESSEL, RAIL, TRUCK or BARGE, null when not stated.

datetime_precisionstring

How precise the carrier was: datetime, or date when it gave a day with no time.

utc_offset_minutesinteger | null

Local time minus UTC in minutes at that instant, null when the port zone is unknown or the event is date only.

source_resolve_methodstring

The exact rung the source was resolved on, kept verbatim so a coarse bucket never hides the detail.

event_classifierstring

The classifier the carrier itself gave, ACT, EST or PLN, present only when the line tells an estimate from a plan.

line_signalstring

What the line itself said about the move: actual, plan, or unstated when it gave a date with no such word.

stated_utc_offsets_minutesinteger[] | null

The UTC offsets in minutes that the zone abbreviation printed by the carrier can mean.

unlocode_sourcestring

Where the code came from: carrier for the line's own code, derived when filled from the place name, corrected when we replaced the line's code.

carrier_unlocodestring | null

The line's own code for the place when we replaced it with a corrected one.

location_country_codestring | null

Two-letter country code the carrier stated for the place.

port_rolestring

Which port of the journey the carrier says this move happened at: origin, transshipment or destination.

facility_port_namestring | null

The port a facility-only row belongs to, taken from the line's own ordering.

supplier_raw_event_codestring | null

The carrier's own event code before normalisation, kept verbatim for forensics.

group_linestring

SCAC of the sister line that stated this move when it was merged in from a carrier group answer.

facilitystring | null

Terminal, depot or other facility name for the move.

facility_locodestring | null

UN/LOCODE the source gives for the facility.

facility_bic_codestring | null

BIC facility code, when the source publishes one.

facility_smdg_codestring | null

SMDG terminal code, when the source publishes one.

facility_latnumber | null

Latitude of the facility in decimal degrees.

facility_lngnumber | null

Longitude of the facility in decimal degrees.

facility_country_codestring | null

Two-letter country code of the facility.

transport_mode_basisstring

Set to computed when the mode is our conclusion and not the line's own word.

carrier_status_textstring | null

The carrier's own status wording kept verbatim as a remark beside a normalised code.

dcsa_nativeboolean

True when the carrier itself published the DCSA code and it was passed through unchanged.

empty_indicatorstring | null

Whether the box was EMPTY or LADEN on this move, null or absent when not established.

fill_basisstring

Set to line_sequence when the laden or empty state was read from the order of the line's own list and not from its wording.

handoffboolean

True when the carrier hands the box straight to its next shipment without an empty move.

move_directionstring

Trade direction the carrier states for the move: EXP for the export side, IMP for the import side.

intermediaryboolean

True for a port call of the ship where the box stays aboard and is not handled.

document_idstring | null

On a shipment event, the booking or transport document the event is about.

document_type_codestring | null

On a shipment event, BKG for a booking or TRD for a transport document.

datetime_sourcestring

Set to observed when the line stated the fact without a date and the time is when we first saw it.

line_sequenceinteger

Zero-based position of this step in the line's own ordered journey list.

actual_basisstring

Set to implied_by_later_actual when the step counts as actual only because a later actual of the line proves it happened.

equipment_referencestring

Container number the event belongs to, set on a per-container row derived from a document.

route_legsarray

The legs of the route held for this shipment; the fields of a leg vary by where the legs came from. Each item is free-form: its keys depend on the shipping line, so the ones listed here are examples, not a fixed set.

stated_routeobject

The route the line states in its own answer, one statement per place it names, in its order.

statementsarray
statements[]object
rolestring

Role of the place on the route: POR, POL, TSP, POD or FND.

placeobject

The place as the line names it.

textstring

The place as the line wrote it.

codestring | null

The line's own UN/LOCODE for the place, null when it gives none.

arrivalobject | null

The arrival the line states for this place, null when it states none.

localstring

The port calendar day or wall clock as the line gives it, zoneless, for example 2026-10-15 or 2026-10-15T09:30.

estimatedboolean | null

The line's own word: true for estimated, false for actual, null when it says neither.

departureobject | null

The departure the line states for this place, null when it states none.

localstring

The port calendar day or wall clock as the line gives it, zoneless, for example 2026-10-15 or 2026-10-15T09:30.

estimatedboolean | null

The line's own word: true for estimated, false for actual, null when it says neither.

stated_route_codesobject | null

Our UN/LOCODE for each place of stated_route that the line left uncoded, keyed by the place text as the line wrote it.

source_surfacestring

Which surface of the carrier's answer this enrichment was read from.

schedule_derived_podobject

Present when the discharge port was filled from the published sailing schedule because the line named none.

vessel_imostring

IMO number of the vessel the sailing was matched on.

voyage_numberstring

Voyage number the sailing was matched on.

load_unlocodestring

UN/LOCODE of the load port the sailing was matched on.

destination_unlocodestring

UN/LOCODE of the discharge port taken from the sailing.

published_arrivalstring | null

Arrival the schedule publishes for that port, which is not promoted to an ETA.

sailing_sourcestring | null

Label of the schedule record the sailing came from.

unresolved_reasonstring | null

Why a reference could not be resolved: invalid_number, not_found or bl_booking_unresolved.

updated_atstring

When the record itself last changed in our database, which includes bookkeeping writes.

archived_reasonstring | null

Why tracking stopped: your delete call, or an automatic close-out once the box finished its cycle.

identified_notified_atstring | null

Internal bookkeeping: when the "container identified" digest was sent for this box.

intermediary_enriched_atstring | null

Internal bookkeeping: when a lessor or intermediary lookup last enriched this record.

import_batch_idstring | null

Groups every box created by one bulk import, so their digest fires once per batch.

seal_numberstring | null

Carrier seal on the box.

move_typestring | null

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

vgm_kgnumber | null

Verified gross mass, kilograms.

gross_weight_kgnumber | null

Gross weight of the loaded box, kilograms.

package_countinteger | null

Pieces inside the box.

package_unitstring | null

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

measurement_cbmnumber | null

Cargo volume, cubic metres.

service_requirementstring | null

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

commercial_rawobject | null

Commercial details the line states for the shipment (for example service type, operator, release states). Free-form: the keys inside depend on the shipping line, so the ones listed here are examples, not a fixed set.

tracked_fromstring | null

The surface the box was added from.

sourcestring

Where the answer on this call came from: direct_carrier or warm_db.

route_dataobject

The route in the shape our map consumers read: the legs, the current pin and the AIS block.

routearray

The legs of the drawn route.

route[]object
fromobject

Where the leg starts.

latnumber

Latitude.

lngnumber

Longitude.

namestring

Human-readable name.

statestring

State, province or region of the port, when the gazetteer holds one.

locodestring

UN/LOCODE of the place.

countrystring

Country name.

timezonestring

IANA time zone of the place.

country_codestring

ISO 3166-1 alpha-2 country code.

toobject

Where the leg ends.

latnumber

Latitude.

lngnumber

Longitude.

namestring

Human-readable name.

statestring

State, province or region of the port, when the gazetteer holds one.

locodestring

UN/LOCODE of the place.

countrystring

Country name.

timezonestring

IANA time zone of the place.

country_codestring

ISO 3166-1 alpha-2 country code.

pathnumber[][]

The drawn geometry of the leg as lat and lng pairs.

typestring

Event code, for example DEPA or LOAD.

vesselobject | null

Vessel currently carrying the container, or null when we hold neither a name nor an IMO.

imointeger | null

IMO number of the ship, as a number.

namestring | null

Name of the ship.

mmsiinteger | null

MMSI of the ship.

call_signstring | null

Radio call sign of the ship.

flagstring | null

Flag state of the ship.

transport_typestring | null

The mode carrying the leg, for example VESSEL or TRUCK, when the carrier names it.

lanenumber[][]

The clean port to port corridor of the shipment, given when path also carries the sailed track of the ship.

path_source"ais_track"

Set to ais_track when the leg was drawn from the positions the ship itself reported.

path_observed_spansinteger[][]

Which runs of path the ship itself reported, as inclusive [start, end] index pairs into path.

path_status"routed" | "direct" | "absent"

What the line is: routed along a sea lane, a direct straight segment, or absent.

path_absent_reason"crosses_land"

Why the leg has no line.

crosses_antimeridiantrue

True when the path crosses the 180 degree meridian, so a flat map must split or unwrap it.

pinnumber[]

Where to draw the box right now, as a lat and lng pair.

pin_sourcestring

How the pin was placed: ais_vessel_position from a real fix, route_reckoning when computed along the route, or a port when the box is sitting at one.

aisobject

The vessel and port dates as an AIS-shaped block, kept in the layout integrators migrating from the older API already parse.

dataobject

The AIS-shaped payload.

vesselobject

The hull these dates belong to.

imointeger

IMO number of the vessel.

flagstring

Flag state of the vessel, as a two-letter code.

mmsiinteger

Vessel MMSI.

namestring

Human-readable name.

call_signstring

Vessel radio call sign.

last_eventobject

The most recent vessel move behind these dates.

datestring

When it happened, as a port wall-clock string without an offset, which is the layout this block has always used.

voyagestring | null

Carrier voyage number, when published.

descriptionstring

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

updated_atstring

When this AIS block was last rebuilt.

arrival_portobject

The arrival call these dates describe.

codestring

The short port code the compatible API prints next to the UN/LOCODE.

locodestring

UN/LOCODE of the place.

datestring

The date of the call, as a port wall-clock string with no offset, which is the layout this block has always used.

date_labelstring

Which kind of date the neighbouring value is: ETA, ETD, ATA or ATD.

country_codestring

ISO 3166-1 alpha-2 country code.

departure_portobject

The departure call these dates describe.

codestring

The short port code the compatible API prints next to the UN/LOCODE.

locodestring

UN/LOCODE of the place.

datestring

The date of the call, as a port wall-clock string with no offset, which is the layout this block has always used.

date_labelstring

Which kind of date the neighbouring value is: ETA, ETD, ATA or ATD.

country_codestring

ISO 3166-1 alpha-2 country code.

discharge_portobject

The discharge call these dates describe.

codestring

The short port code, as above.

locodestring

UN/LOCODE of the place.

datestring

The date of the sea discharge, in the same wall-clock layout.

date_labelstring

Which kind of date the neighbouring value is: ETA, ETD, ATA or ATD.

country_codestring

ISO 3166-1 alpha-2 country code.

namestring

Human-readable name.

last_vessel_positionobject

The most recent fix for the hull, with the time it was taken.

latnumber

Latitude.

lngnumber

Longitude.

updated_atstring

When the fix was taken.

statusstring

Whether the AIS block carries data, and why not when it does not.

sourceobject

Who produced the route and the AIS in this block.

providerstring

Machine name of the producer.

provider_namestring

Display name of the producer.

route_geometrystring

How the drawn line was produced, for example trackingmcp_computed.

aisstring

Which vessel-position source fed the AIS block.

notestring

One sentence of provenance in plain language.

pin_estimatedboolean

True when the pin was computed rather than observed.

pin_estimated_fromstring | null

The observation the estimate was anchored to.

geometry_versioninteger

Which generation of our route-drawing produced this geometry.

map_validation_idstring | null

Identifier of the chart validation the route was drawn against; null when none is loaded.

pin_estimated_atstring | null

When we calculated the estimated marker position; null when the marker is not an estimate.

pin_route_distance_kminteger

Distance from the marker to the drawn route, in whole kilometres.

pin_reconciledboolean

True when the marker sits close enough to the drawn route to agree with it.

pin_route_agreement_basisstring

Which position the agreement check rested on; only vessel_fix is an independent test of the route. One of: vessel_fix, port_anchor, estimate.

vessel_fix_route_distance_kminteger | null

Distance from the latest AIS fix of the ship to the drawn route, in whole kilometres; null when there is no fix.

route_data_computed_atstring

When this route block was last built.

equipment_ownerstring | null

Registered owner of the box, resolved from its BIC prefix.

equipment_lessorstring | null

Leasing company, when the box is leased rather than carrier-owned.

lessee_namestring | null

Who holds the box on lease.

carrier_hint_codestring | null

An unconfirmed carrier candidate derived from lessor data.

lessor_statusstring | null

The box status as the lessor reports it, for example on-hire or off-hire.

lessor_checked_atstring | null

When we last asked the lessor.

redelivery_referencestring | null

Redelivery booking for the empty.

redelivery_datestring | null

When the empty is due back.

redelivery_locationstring | null

Where the empty is due back.

redelivery_yardstring | null

The depot the empty is due back at.

lessor_contract_numberstring | null

Lease contract the box sits on.

lessor_contract_typestring | null

Lease type, for example long-term or one-way.

equipment_manufacturerstring | null

Who built the box.

lessor_on_hire_datestring | null

When the box went on hire.

lessor_on_hire_locationstring | null

Where it went on hire.

lessor_on_hire_yardstring | null

The depot it went on hire at.

connector_statusstring | null

Where a request to connect this carrier stands, when the line needs one.

connector_notify_requested_atstring | null

When you asked to be told the connector went live.

connector_notified_atstring | null

When we told you it went live.

field_provenanceRecord<string, object>

Per-field account of WHY a declared field is empty, keyed by field name.

{field}object
statestring

Why the field stands where it does: resolved, contract_required, not_published, not_applicable or awaiting_carrier.

actionstring

What would change the state: supply_terms, wait, or do_not_expect when nothing will.

sourcestring | null

Where the answer on this call came from: direct_carrier or warm_db.

confidencestring | null

On a card, whether the slot partners agree with each other.

evidencestring

The reasoning behind the state, in one sentence, so a support answer does not need our source.

field_provenance_summaryobject

Counts of the declared cutoff and demurrage fields by state, so you can tell "we do not have it" from "your contract terms would unlock it".

resolvedinteger

Declared fields we hold a value for.

contract_requiredinteger

Declared fields that stay empty until you supply your own free-time terms.

not_publishedinteger

Declared fields this carrier does not publish.

not_applicableinteger

Declared fields that do not apply to this shipment.

awaiting_carrierinteger

Declared fields we expect but have not received yet.

unblocked_by_contract_termsboolean

True when supplying free-time terms would fill at least one empty field.

carrier_response_rawobject | null

The same object as cutoff_enrichment, served under a second name. Free-form: the keys inside depend on the shipping line, so the ones listed here are examples, not a fixed set.

bl_containersstring[]

Every container number on the bill of lading or booking, as listed by the carrier.

bl_container_countinteger

How many containers the document names, including any the carrier has not numbered yet.

containersarray

One entry per container on the document that has its own timeline. Each item is free-form: its keys depend on the shipping line, so the ones listed here are examples, not a fixed set.

containers[]object
numberstring

Container number.

container_sizestring | null

Normalised size and type, for example 40HC.

iso_codestring | null

ISO 6346 size and type code, for example 45G1.

size_rawstring | null

The carrier's size and type string before normalisation.

events_sourcedboolean

True when this timeline was fetched for this container specifically and is not a copy of the shipment timeline.

source_outcomestring

sourced when the carrier returned movements for this container, no_data when it answered and published none.

eventsarray

This container's own events, in the same shape as an event raw_payload. Each item is free-form: its keys depend on the shipping line, so the ones listed here are examples, not a fixed set.

events[]object
datetimestring

The event instant in UTC (ISO 8601).

timezonestring | null

IANA time zone of the event port, null when it could not be resolved.

unlocodestring | null

UN/LOCODE of the event place, null when none is known.

is_actualboolean

True when the event happened, false when it is planned or estimated.

port_namestring | null

Place name as the carrier wrote it.

event_codestring

Normalised event code, for example LOAD, DISC, GTIN, GTOT, ARRI, DEPA, STUF, STRP, AVPU, CUSR, CUSI, CUSS; an unmapped carrier code passes through as written.

vessel_imostring | null

IMO number of the vessel on this move, null when unknown or not a plausible IMO.

descriptionstring | null

The carrier's wording for the event.

source_kindstring

Which kind of source produced the event: carrier when the line answered directly; any other value means the event reached us another way.

vessel_namestring | null

Name of the vessel on this move.

event_familystring

Family the code belongs to: EQUIPMENT, TRANSPORT or SHIPMENT.

voyage_numberstring | null

Carrier voyage number for this move.

datetime_basisstring

What the connector emitted before normalisation: utc for a true instant, port_local for a port wall clock.

datetime_localstring | null

The wall clock at the event port as a zoneless ISO string, for example 2026-07-21T11:07:00.

time_semanticsstring

How the instant was established: carrier_offset, tz_resolved, date_only, local_unplaced or legacy_unknown.

transport_modestring | null

Mode of transport for the leg: VESSEL, RAIL, TRUCK or BARGE, null when not stated.

datetime_precisionstring

How precise the carrier was: datetime, or date when it gave a day with no time.

utc_offset_minutesinteger | null

Local time minus UTC in minutes at that instant, null when the port zone is unknown or the event is date only.

source_resolve_methodstring

The exact rung the source was resolved on, kept verbatim so a coarse bucket never hides the detail.

event_classifierstring

The classifier the carrier itself gave, ACT, EST or PLN, present only when the line tells an estimate from a plan.

line_signalstring

What the line itself said about the move: actual, plan, or unstated when it gave a date with no such word.

stated_utc_offsets_minutesinteger[] | null

The UTC offsets in minutes that the zone abbreviation printed by the carrier can mean.

unlocode_sourcestring

Where the code came from: carrier for the line's own code, derived when filled from the place name, corrected when we replaced the line's code.

carrier_unlocodestring | null

The line's own code for the place when we replaced it with a corrected one.

location_country_codestring | null

Two-letter country code the carrier stated for the place.

port_rolestring

Which port of the journey the carrier says this move happened at: origin, transshipment or destination.

facility_port_namestring | null

The port a facility-only row belongs to, taken from the line's own ordering.

supplier_raw_event_codestring | null

The carrier's own event code before normalisation, kept verbatim for forensics.

group_linestring

SCAC of the sister line that stated this move when it was merged in from a carrier group answer.

facilitystring | null

Terminal, depot or other facility name for the move.

facility_locodestring | null

UN/LOCODE the source gives for the facility.

facility_bic_codestring | null

BIC facility code, when the source publishes one.

facility_smdg_codestring | null

SMDG terminal code, when the source publishes one.

facility_latnumber | null

Latitude of the facility in decimal degrees.

facility_lngnumber | null

Longitude of the facility in decimal degrees.

facility_country_codestring | null

Two-letter country code of the facility.

transport_mode_basisstring

Set to computed when the mode is our conclusion and not the line's own word.

carrier_status_textstring | null

The carrier's own status wording kept verbatim as a remark beside a normalised code.

dcsa_nativeboolean

True when the carrier itself published the DCSA code and it was passed through unchanged.

empty_indicatorstring | null

Whether the box was EMPTY or LADEN on this move, null or absent when not established.

fill_basisstring

Set to line_sequence when the laden or empty state was read from the order of the line's own list and not from its wording.

handoffboolean

True when the carrier hands the box straight to its next shipment without an empty move.

move_directionstring

Trade direction the carrier states for the move: EXP for the export side, IMP for the import side.

intermediaryboolean

True for a port call of the ship where the box stays aboard and is not handled.

document_idstring | null

On a shipment event, the booking or transport document the event is about.

document_type_codestring | null

On a shipment event, BKG for a booking or TRD for a transport document.

datetime_sourcestring

Set to observed when the line stated the fact without a date and the time is when we first saw it.

line_sequenceinteger

Zero-based position of this step in the line's own ordered journey list.

actual_basisstring

Set to implied_by_later_actual when the step counts as actual only because a later actual of the line proves it happened.

equipment_referencestring

Container number the event belongs to, set on a per-container row derived from a document.

route_legsarray

The legs of the route held for this shipment; the fields of a leg vary by where the legs came from. Each item is free-form: its keys depend on the shipping line, so the ones listed here are examples, not a fixed set.

stated_routeobject

The route the line states in its own answer, one statement per place it names, in its order.

statementsarray
statements[]object
rolestring

Role of the place on the route: POR, POL, TSP, POD or FND.

placeobject

The place as the line names it.

textstring

The place as the line wrote it.

codestring | null

The line's own UN/LOCODE for the place, null when it gives none.

arrivalobject | null

The arrival the line states for this place, null when it states none.

localstring

The port calendar day or wall clock as the line gives it, zoneless, for example 2026-10-15 or 2026-10-15T09:30.

estimatedboolean | null

The line's own word: true for estimated, false for actual, null when it says neither.

departureobject | null

The departure the line states for this place, null when it states none.

localstring

The port calendar day or wall clock as the line gives it, zoneless, for example 2026-10-15 or 2026-10-15T09:30.

estimatedboolean | null

The line's own word: true for estimated, false for actual, null when it says neither.

stated_route_codesobject | null

Our UN/LOCODE for each place of stated_route that the line left uncoded, keyed by the place text as the line wrote it.

source_surfacestring

Which surface of the carrier's answer this enrichment was read from.

schedule_derived_podobject

Present when the discharge port was filled from the published sailing schedule because the line named none.

vessel_imostring

IMO number of the vessel the sailing was matched on.

voyage_numberstring

Voyage number the sailing was matched on.

load_unlocodestring

UN/LOCODE of the load port the sailing was matched on.

destination_unlocodestring

UN/LOCODE of the discharge port taken from the sailing.

published_arrivalstring | null

Arrival the schedule publishes for that port, which is not promoted to an ETA.

sailing_sourcestring | null

Label of the schedule record the sailing came from.

place_of_delivery_unlocodestring | null

UN/LOCODE of the place where the line hands the box over.

place_of_delivery_namestring | null

Name of the place of delivery as the line states it.

pol_unlocodestring

UN/LOCODE of the port of loading: where the box boarded its first ship on this trip, read from its first vessel load (the line's own "at Port of Loading" load when it files one).

pol_namestring

Name of the port of loading as the line states it on that load.

origin_coordobject

Coordinate of the origin port.

latnumber

Latitude.

lngnumber

Longitude.

approximateboolean

True when the coordinate is a place centroid rather than a terminal position.

approx_fromstring | null

What the approximate point was derived from.

destination_coordobject

Coordinate of the destination port.

latnumber

Latitude.

lngnumber

Longitude.

approximateboolean

True when the coordinate is a place centroid rather than a terminal position.

approx_fromstring | null

What the approximate point was derived from.

is_demoboolean

True on a sample reference.

child_containersarray | null

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[]object
numberstring

Container number of the box, or TBA for a group of boxes the line has not numbered yet.

iso_codestring | null

ISO equipment type code of the box, for example 45G1.

size_typestring | null

The line's own size and type label for the box.

statusstring | null

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.

status_source"tracked" | "line" | "document" | null

Where the box status came from: its own tracked row, the line's events for that box, or the document status.

eventsarray

The box's own timeline; an empty array when no per-box timeline is known yet.

events[]object
event_codestring

Milestone code of the move, for example GTIN, LOAD, DEPA, ARRI, DISC or GTOT.

event_namestring

Readable name of the move, the same wording the dashboard shows.

event_family"EQUIPMENT" | "TRANSPORT" | "SHIPMENT"

Family the move belongs to.

transport_mode"VESSEL" | "RAIL" | "TRUCK" | "BARGE"

Conveyance the line stated for the move.

is_actualboolean

True when the move has happened, false when it is planned or estimated.

implied_actualtrue

True when a planned move is served as done because a later actual move proves it happened.

datetimestring

When the move happened or is planned, as a UTC instant when the port time zone is known.

datetime_localstring | null

The same moment on the port wall clock, without an offset.

timezonestring | null

IANA time zone of the port, for example Asia/Shanghai.

utc_offset_minutesinteger | null

Minutes to add to UTC to get the port wall clock.

time_semanticsstring

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.

unlocodestring | null

UN/LOCODE of the place of the move.

location_code_sourcestring | null

Where the served UN/LOCODE came from. One of: carrier, matched_in_country, matched_port_name, corrected, not_determined, recorded.

port_namestring | null

Place name as the line wrote it.

facilitystring | null

Terminal, depot or other facility name as the line wrote it.

vessel_namestring | null

Name of the ship for this move.

vessel_imostring | null

IMO number of the ship for this move, as a string.

voyage_numberstring | null

Voyage number the line stated for this move.

descriptionstring | null

The line's own wording for the move.

carrier_status_textstring

The line's own status remark for the move.

empty_indicator"EMPTY" | "LADEN" | null

Whether the box was empty or laden at this move.

empty_indicator_source"carrier" | "not_reported"

Who stated the fill state: the line, or nobody.

gate_out_rolestring

What a gate-out did: moved the box on, or handed it to the consignee. One of: transfer, consignee_delivery, not_reported.

journey_leg_sequenceinteger | null

The leg_sequence of the entry in legs[] this move belongs to, or null when no served ocean leg claims it.

ais_etaobject | null

Our own arrival projection from the live vessel position, beside the ETA of the line.

predicted_arrivalstring

Projected arrival at the port.

basis"ais_position"

Always ais_position.

remaining_nmnumber

Distance left to the port, in nautical miles.

speed_knnumber

Speed used for the projection, in knots.

divergence_hoursnumber | null

Signed hours against the ETA of the line: positive means the projection is later.

confidence"high" | "medium" | "low"

How far to trust the projection.

eventsarray

Milestone timeline, oldest to newest.

events[]object
idstring

Stable identifier for the record.

org_idstring

Your organisation.

container_idstring

The container number this row is about.

dcsa_event_idstring

The id this event carries on the DCSA /v2 surface, so the same physical event can be matched across both surfaces.

event_typestring

DCSA event category: SHIPMENT, TRANSPORT or EQUIPMENT.

event_classifier_codestring

DCSA classifier: ACT, EST or PLN.

event_date_timestring

When the event happened or is forecast to (ISO 8601).

event_created_date_timestring

When we recorded the event, not when it happened.

transport_event_type_codestring | null

DCSA transport code on a vessel move: ARRI for arrival, DEPA for departure.

delay_reason_codestring | null

Carrier code for why a move slipped.

change_remarkstring | null

The carrier own free-text remark about a change to this event.

equipment_event_type_codestring

DCSA equipment code on a box move, for example GTOT for a gate-out or LOAD for a load.

empty_indicator_codestring

EMPTY or LADEN on an equipment event.

equipment_referencestring

The container the event happened to.

iso_equipment_codestring | null

ISO 6346 equipment code as filed on this event.

shipment_event_type_codestring | null

DCSA shipment code on a documentation move.

document_idstring | null

The document the shipment event refers to, on the lines that publish one.

document_type_codestring | null

What that document is, for example a bill of lading.

reasonstring | null

The carrier stated reason for the event, on the lines that publish one.

transport_callobject

The location, vessel and voyage of the port call.

locationobject

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

locationNamestring

Port name as the carrier wrote it, unmapped.

UNLocationCodestring

UN/LOCODE.

modeOfTransportstring | null

Conveyance the line stated for the move. One of: VESSEL, RAIL, TRUCK, BARGE.

facilityobject | null

The terminal, depot or other facility of the move.

codeSource"carrier"

Who supplied the facility codes.

facilityNamestring

Facility name as the line wrote it.

UNLocationCodestring

UN/LOCODE of the facility.

smdgCodestring

SMDG terminal code of the facility.

bicCodestring

BIC facility code.

facilityCodestring

The single facility code to use: the SMDG code when known, else the BIC code.

facilityCodeListProvider"SMDG" | "BIC"

Which code list facilityCode comes from.

latitudenumber

Latitude of the facility.

longitudenumber

Longitude of the facility.

countryCodestring

Two letter country code of the facility.

vesselobject | null

The ship of the move.

namestring | null

Name of the ship.

vesselIMONumberstring | null

IMO number of the ship as a string; null when the value the line sent cannot be an IMO number.

vesselNamestring | null

Name of the ship, duplicated under the DCSA key.

carrierVoyageNumberstring

Voyage number the line stated for the move.

exportVoyageNumberstring | null

Voyage number of the move, on rows rebuilt from a per-box timeline.

referencesstring | null

Extra carrier references filed against the event.

sealsstring | null

Seal numbers filed against the event.

normalisation_confidencestring

How sure we are of the normalised code: REPORTED when the carrier gave a code we map directly, INFERRED when we derived it from its wording, UNKNOWN when neither was possible.

supplier_raw_event_codestring | null

The code the source used, before normalisation.

supplier_raw_payloadstring | null

The source own event object, kept verbatim.

created_atstring

When the record was created (ISO 8601).

event_idstring | null

The carrier own id for the event, when it publishes one.

event_datetimestring

Same instant as event_date_time, under the name the earlier API used.

event_codestring

Machine-readable event code, for example LOAD, DISC, GTIN, GTOT, ARRI, DEPA.

raw_payloadobject

The connector event exactly as it was stored, so a value we did not map is never lost. Free-form: the keys inside depend on the shipping line, so the ones listed here are examples, not a fixed set.

datetimestring

The event instant in UTC (ISO 8601).

timezonestring | null

IANA time zone of the event port, null when it could not be resolved.

unlocodestring | null

UN/LOCODE of the event place, null when none is known.

is_actualboolean

True when the event happened, false when it is planned or estimated.

port_namestring | null

Place name as the carrier wrote it.

event_codestring

Normalised event code, for example LOAD, DISC, GTIN, GTOT, ARRI, DEPA, STUF, STRP, AVPU, CUSR, CUSI, CUSS; an unmapped carrier code passes through as written.

vessel_imostring | null

IMO number of the vessel on this move, null when unknown or not a plausible IMO.

descriptionstring | null

The carrier's wording for the event.

source_kindstring

Which kind of source produced the event: carrier when the line answered directly; any other value means the event reached us another way.

vessel_namestring | null

Name of the vessel on this move.

event_familystring

Family the code belongs to: EQUIPMENT, TRANSPORT or SHIPMENT.

voyage_numberstring | null

Carrier voyage number for this move.

datetime_basisstring

What the connector emitted before normalisation: utc for a true instant, port_local for a port wall clock.

datetime_localstring | null

The wall clock at the event port as a zoneless ISO string, for example 2026-07-21T11:07:00.

time_semanticsstring

How the instant was established: carrier_offset, tz_resolved, date_only, local_unplaced or legacy_unknown.

transport_modestring | null

Mode of transport for the leg: VESSEL, RAIL, TRUCK or BARGE, null when not stated.

datetime_precisionstring

How precise the carrier was: datetime, or date when it gave a day with no time.

utc_offset_minutesinteger | null

Local time minus UTC in minutes at that instant, null when the port zone is unknown or the event is date only.

source_resolve_methodstring

The exact rung the source was resolved on, kept verbatim so a coarse bucket never hides the detail.

event_classifierstring

The classifier the carrier itself gave, ACT, EST or PLN, present only when the line tells an estimate from a plan.

line_signalstring

What the line itself said about the move: actual, plan, or unstated when it gave a date with no such word.

stated_utc_offsets_minutesinteger[] | null

The UTC offsets in minutes that the zone abbreviation printed by the carrier can mean.

unlocode_sourcestring

Where the code came from: carrier for the line's own code, derived when filled from the place name, corrected when we replaced the line's code.

carrier_unlocodestring | null

The line's own code for the place when we replaced it with a corrected one.

location_country_codestring | null

Two-letter country code the carrier stated for the place.

port_rolestring

Which port of the journey the carrier says this move happened at: origin, transshipment or destination.

facility_port_namestring | null

The port a facility-only row belongs to, taken from the line's own ordering.

supplier_raw_event_codestring | null

The carrier's own event code before normalisation, kept verbatim for forensics.

group_linestring

SCAC of the sister line that stated this move when it was merged in from a carrier group answer.

facilitystring | null

Terminal, depot or other facility name for the move.

facility_locodestring | null

UN/LOCODE the source gives for the facility.

facility_bic_codestring | null

BIC facility code, when the source publishes one.

facility_smdg_codestring | null

SMDG terminal code, when the source publishes one.

facility_latnumber | null

Latitude of the facility in decimal degrees.

facility_lngnumber | null

Longitude of the facility in decimal degrees.

facility_country_codestring | null

Two-letter country code of the facility.

transport_mode_basisstring

Set to computed when the mode is our conclusion and not the line's own word.

carrier_status_textstring | null

The carrier's own status wording kept verbatim as a remark beside a normalised code.

dcsa_nativeboolean

True when the carrier itself published the DCSA code and it was passed through unchanged.

empty_indicatorstring | null

Whether the box was EMPTY or LADEN on this move, null or absent when not established.

fill_basisstring

Set to line_sequence when the laden or empty state was read from the order of the line's own list and not from its wording.

handoffboolean

True when the carrier hands the box straight to its next shipment without an empty move.

move_directionstring

Trade direction the carrier states for the move: EXP for the export side, IMP for the import side.

intermediaryboolean

True for a port call of the ship where the box stays aboard and is not handled.

document_idstring | null

On a shipment event, the booking or transport document the event is about.

document_type_codestring | null

On a shipment event, BKG for a booking or TRD for a transport document.

datetime_sourcestring

Set to observed when the line stated the fact without a date and the time is when we first saw it.

line_sequenceinteger

Zero-based position of this step in the line's own ordered journey list.

actual_basisstring

Set to implied_by_later_actual when the step counts as actual only because a later actual of the line proves it happened.

equipment_referencestring

Container number the event belongs to, set on a per-container row derived from a document.

event_local_datetimestring

The port wall-clock for the same moment, naive and with no offset, exactly as a terminal prints it.

utc_offset_minutesinteger

Minutes to add to the UTC instant to reach the local wall-clock.

event_timezonestring

IANA zone of the port, which survives a DST change in a way a bare offset cannot.

date_onlyboolean

True when the carrier published a calendar date with no time of day.

event_datestring | null

The calendar date, YYYY-MM-DD, when date_only is true.

event_time_semanticsstring

Internal marker for how this row timestamp was established.

event_namestring

The step in plain language, for example Gated out.

empty_indicator_sourcestring

Who stated the fill state of an equipment event: carrier when the line reported EMPTY or LADEN, not_reported when it did not.

gate_out_rolestring

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.

journey_leg_sequenceinteger | null

The leg_sequence of the legs[] ocean leg whose voyage this event belongs to: the leg its own ship and voyage name, else the leg that loads or discharges at its port, else the voyage last discharged before it (so the rail haul, the delivery and the empty return after discharge belong to the last ocean leg).

has_facilityboolean

True when the line named a terminal, hub or depot for this arrival.

journey_contextobject

Marks a move that is part of a transshipment.

port_role"transshipment"

Always transshipment.

milestonestring

Which side of the transshipment the move is. One of: discharged_for_transshipment, loaded_on_onward_vessel.

location_code_sourcestring | null

Where the served UN/LOCODE of the event came from. One of: carrier, matched_in_country, matched_port_name, corrected, not_determined, recorded.

implied_actualtrue

True when a planned move is served as done because a later actual move proves it happened.

line_date_suspecttrue

True on a past plan the line left behind a later actual move, shown as the line gave it.

journey_timelinearray

The shipment as a reader story: carrier events plus the moves we inferred between them, in order.

journey_timeline[]object
idstring

Stable identifier for the record.

kindstring

carrier_event when a carrier filed it, trackingmcp_inference when we derived the step from surrounding events.

classifierstring

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

occurred_atstring

When the step happened (UTC).

event_namestring

The step in plain language, for example Gated out.

port_unlocodestring

Resolved port UN/LOCODE.

port_namestring

Resolved port name.

facility_namestring | null

Terminal or depot inside the port, when the carrier names one.

evidence_event_idsstring[]

The event ids this step was built from, so an inference can always be traced back.

confidencestring

On a card, whether the slot partners agree with each other.

labelstring

The event in plain words.

port_rolestring | null

The role the port plays on this route: origin, transshipment or destination.

milestonestring | null

The voyage milestone this step marks, when it marks one.

exceptionsarray

Count of shipments in an exception state: customs hold, rolled, delayed or at transshipment.

exceptions[]object
typestring

What kind of exception this is. One of: inspection_started, scanner_flagged, carrier_hold, exam_selected, document_hold, declaration_rejected, inferred_silent_hold, eta_at_risk.

status"reported" | "inferred" | "forecast"

Whether the line reported it, we inferred it, or it is a forecast.

severity"critical" | "high" | "medium"

How serious it is.

sincestring | null

When the hold started; always null for eta_at_risk.

labelstring

Short label for a badge.

explanationstring

One or two sentences explaining the exception.

recommended_actionstring

What to do about it now.

sourcestring

Whether it comes from a carrier event or from our own inference. One of: carrier_event, trackingmcp_inference.

history_daysinteger

How far back the timeline reaches on your plan, in days.

current_legobject | null

The leg the box is on now.

leg_sequenceinteger

Order of the leg on the journey, starting from the first leg.

leg_type"ocean" | "inland"

Whether the leg is carried on water or over land.

origin_unlocodestring | null

UN/LOCODE where the leg starts.

destination_unlocodestring | null

UN/LOCODE where the leg ends.

vessel_imostring | null

IMO number of the ship sailing the leg, as a string.

vessel_namestring | null

Name of the ship sailing the leg.

voyage_idstring | null

Internal voyage identifier.

voyage_numberstring | null

The carrier's voyage number for the leg, read from the box's own timeline.

eta_at_leg_deststring | null

Arrival at the end of the leg: estimated until it happens, then the actual time.

discharged_atstring | null

When the box actually came off at the end of the leg; null while the leg is still open.

is_plannedtrue

True on a leg that was added from the line's stated route and has no ship, voyage or dates yet.

legsarray

The voyage broken into legs.

legs[]object
is_plannedboolean

True only for an undated connection inferred from the carrier-declared destination and known preceding port, including owner-confirmed terminal-to-delivery on-carriage.

leg_sequenceinteger

Order of the leg on the journey, starting from the first leg.

leg_type"ocean" | "inland"

Whether the leg is carried on water or over land.

origin_unlocodestring | null

UN/LOCODE where the leg starts.

destination_unlocodestring | null

UN/LOCODE where the leg ends.

vessel_imostring | null

IMO number of the ship sailing the leg, as a string.

vessel_namestring | null

Name of the ship sailing the leg.

voyage_idstring | null

Internal voyage identifier.

voyage_numberstring | null

The carrier's voyage number for the leg, read from the box's own timeline.

eta_at_leg_deststring | null

Arrival at the end of the leg: estimated until it happens, then the actual time.

discharged_atstring | null

When the box actually came off at the end of the leg; null while the leg is still open.

planned_vesselobject | null

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.

namestring | null

Name of the planned ship.

imostring | null

IMO number of the planned ship, as a string.

voyagestring | null

Voyage number of the planned sailing.

positionobject | null

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.

latnumber

Latitude of the ship.

lngnumber

Longitude of the ship.

updated_atstring

When the ship was observed at this position.

heading_toobject

The port where the box is planned to load.

unlocodestring | null

UN/LOCODE of the planned load port.

namestring | null

Name of the planned load port.

planned_load_atstring | null

When the box is planned to load onto this ship.

status"planned"

Always planned.

eta_overdueobject | null

Set when the served ETA has passed, the line reports no arrival and has gone quiet.

etastring

The served ETA that has passed.

days_overdueinteger

Whole days since that date.

line_silent_sincestring

When the line last put anything new on this box.

notestring

One sentence you can show as-is.

ais_pod_arrivalobject | null

Our AIS observation of the carrying vessel arriving at the port of discharge, when the line has not filed the arrival yet.

observed_atstring

When the vessel was first seen at the port on its final stay there.

port_unlocodestring

UN/LOCODE of the port of discharge.

port_namestring | null

Name of the port.

timezonestring | null

IANA zone of the port, for printing observed_at on the port clock.

vessel_imointeger

IMO number of the vessel.

vessel_namestring | null

Name of the vessel.

distance_kmnumber

How far from the port the qualifying position lay.

source"ais"

Always ais: our observation of the vessel, never an event the line filed.

notestring

One sentence you can show as-is.

ais_pol_departureobject | null

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.

observed_atstring

When the ship left the port of loading, by our AIS port call record.

port_unlocodestring

UN/LOCODE of the port of loading.

port_namestring | null

Name of the port of loading.

timezonestring | null

IANA time zone of the port of loading.

vessel_imointeger

IMO number of the ship.

vessel_namestring | null

Name of the ship.

source"ais"

Always ais.

notestring

A sentence you can show as-is.

vessel_positionobject

Live AIS position of the carrying vessel.

imostring

IMO number of the vessel.

namestring

Human-readable name.

latnumber

Latitude.

lngnumber

Longitude.

speed_knotsnumber | null

Speed over ground, in knots.

heading_deginteger

Heading in degrees.

nav_statusstring

Navigational status as reported by AIS, for example "Under way using engine" or "Moored".

position_updated_atstring

When we last wrote the position row.

position_fix_atstring

When the hull was actually observed.

eta_aisstring

The destination ETA the vessel itself is broadcasting, which is the master own entry and often disagrees with the carrier.

destination_unlocodestring

Destination port UN/LOCODE, or null when unresolved.

photo_urlstring

Photograph of the hull.

photo_attributionstring
photo_licensestring
particulars_updated_atstring

When the vessel particulars were last refreshed.

reported_nav_statusstring

The navigational status the vessel broadcasts, unchecked.

nav_status_verifiedboolean

False when the broadcast status contradicts where the vessel actually is, for example Moored while far from any port.

nav_status_reasonstring

Why the broadcast status was not trusted, for example outside_port_geofence.

nearest_port_nmnumber

Distance to the nearest port, nautical miles, which is the evidence behind the check.

position_checked_atstring

When we checked the position for this request.

ais_refresh_requested_atstring | null

When this request started a live AIS refresh because the stored fix was older than 20 minutes; null when none was started.

pin_sourcestring

How the pin was placed: ais_vessel_position from a real fix, route_reckoning when computed along the route, or a port when the box is sitting at one.

pin_basisstring

What the reckoning leaned on when the pin was computed rather than observed, for example a published schedule.

pin_estimated_fromstring | null

The observation the estimate was anchored to.

observed_positionobject

The last position we actually observed, never a computed one.

latnumber

Latitude.

lngnumber

Longitude.

observed_atstring

When the fix was taken.

qualitystring

How exact the fix is: precise for a terrestrial fix, coarse for a satellite one.

accuracy_kmnumber | null

Radius the fix is good to, kilometres.

estimated_positionobject

A computed position, for when there is no fresh fix.

latnumber

Latitude.

lngnumber

Longitude.

estimated_atstring

The moment the estimate describes.

based_on_observation_atstring | null

The observation the estimate was reckoned from.

classificationstring

Which reckoning class produced the estimate.

methodstring

How the position was produced, for example route_reckoning.

vessel_photoobject

Photograph of the current hull with its attribution.

urlstring

Where we POST the events.

sourcestring

Where the answer on this call came from: direct_carrier or warm_db.

retrieved_atstring

When we fetched the photograph.

attributionstring
licensestring
last_updated_atstring

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

last_updated_sourcestring

Which of the two produced last_updated_at: carrier_poll or ais_vessel_position.

last_ais_fix_atstring

When the vessel was last actually observed by AIS, or null when we hold no fix.

vessel_namesRecord<string, string>

Vessel names by IMO number, for every vessel named on the legs.

transshipmentobject | null

The hub the box is dwelling at and its onward vessel.

hubUnlocodestring | null

UN/LOCODE of the hub, when the line gave one.

hubNamestring | null

Place name of the hub as the line wrote it.

dwellSincestring

When the box was discharged at the hub, which starts the waiting clock.

inboundVesselNamestring | null

Name of the ship that brought the box to the hub.

inboundVesselImostring | null

IMO number of the ship that brought the box to the hub.

nextVesselNamestring | null

Name of the ship the box is planned to load onto.

nextVesselImostring | null

IMO number of the ship the box is planned to load onto.

nextVesselArrivalAtHubstring | null

Estimated arrival of the next ship at the hub, when the line publishes it.

plannedDeparturestring | null

Planned departure of the box from the hub on the next ship.

hubCoordobject | null

Map coordinate of the hub; null when the hub cannot be placed.

latnumber

Latitude of the hub.

lngnumber

Longitude of the hub.

approximateboolean

True when the point is a country level fallback and not the real port.

approx_fromstring | null

UN/LOCODE the approximate position was borrowed from.

schedule_overlayobject

The published vessel rotation we matched this box to, which is the plan against which actuals can be read.

sourcestring

Where the answer on this call came from: direct_carrier or warm_db.

matchstring

How strongly the sailing matches the box, strongest first: vessel_voyage, vessel_lane, vessel_route, onward_vessel_lane, lane, carrier_lane.

carrier_codestring

Carrier SCAC.

service_namestring

Carrier service or loop name.

vessel_imostring

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

voyage_numberstring

Carrier voyage number.

published_departurestring

The departure the carrier published (ISO 8601).

published_arrivalstring

The arrival the carrier published (ISO 8601).

transit_daysinteger

Port-to-port transit in days.

is_transshipmentboolean

True when the box changes vessel on the way.

legsarray

The voyage broken into legs.

legs[]object
seqinteger

Position of the leg in the rotation, starting at 1.

from_unlocodestring

UN/LOCODE the leg departs.

to_unlocodestring

UN/LOCODE the leg arrives at.

from_namestring

Name of the departure port.

to_namestring

Name of the arrival port.

vessel_namestring

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

voyagestring

Carrier voyage number, when published.

servicestring

Carrier service or loop name.

etdstring

Estimated time of departure (ISO 8601).

etastring

Arrival time (ISO 8601).

eta_intelobject

Probability envelope and reliability context.

basisstring

What the reliability figures were computed from, which tells you how much to lean on them.

carrier_scopedboolean

True when the statistics are for THIS carrier on this lane, false when they are lane-level across all carriers and therefore coarser.

confidence_pctinteger

On-time percentage for the lane, which is the same number the ring shows.

on_time_pctinteger

Share of sailings that arrived on time.

median_delay_hoursnumber | null

Typical delay on the lane, hours.

p90_delay_hoursinteger

Delay that 90 percent of arrivals stay inside, hours.

observationsinteger

Number of observed sailings behind the figure.

window_daysinteger

How far back those observations reach, days.

band_lowstring

Best case: the published ETA, arriving on time.

band_highstring

The date 90 percent of arrivals land by.

expectedstring

The typical outcome: the ETA plus the median delay.

transit_p50_hoursnumber | null

Median transit time on the lane, hours.

transit_p90_hoursnumber | null

Transit time 90 percent of sailings stay inside, hours.

eta_at_riskobject | null

Congestion warning.

at_risktrue

Always true when the object is present.

next_portstring | null

UN/LOCODE of the next port the box calls at.

reasonsstring[]

Readable sentences explaining the risk, one per signal.

port_level"moderate" | "severe" | null

Congestion level at the next port; null when the risk comes only from the ship.

port_expected_wait_daysnumber | null

Expected extra waiting time at the next port, in days.

vessel_recent_dwell_hoursnumber | null

How long this ship recently waited at anchor, in hours.

provenancestring[]

Which kinds of signal the warning is based on. One of: ais_wait, port_index, ais, ais_density, vessel_dwell.

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.

probabilityboolean

True when the ETA can carry a confidence figure.

active_countinteger

How many of the four lenses are present.

agreementstring

Whether the sources tell the same story: aligned, diverging, partial, or insufficient when there are too few to compare.

eta_sourcesarray

The ETA each cross-checkable source implies, so a disagreement can be seen rather than averaged away.

eta_sources[]object
lensstring

Which source this ETA came from: carrier, published or ais.

etastring

Arrival time (ISO 8601).

max_spread_hoursnumber | null

Hours between the furthest-apart ETA sources.

ai_insightstring | null

A written read of the shipment state.

ai_insight_pendingboolean

True while one is being generated, so a client can poll instead of showing an empty space.

carrier_document_replyobject | null

Latest retained, exact-reference OOCL document reply.

carrier_code"OOLU"
referencestring
reference_type"bl" | "booking"
status"cancelled" | "declined"
carrier_referencestring
carrier_noticeobject | null

Latest reference-specific reply from the named carrier.

carrier_code"ZIMU" | "MAEU" | "CHVW"
referencestring
reference_type"container" | "bl" | "booking"
statusstring

One of: other_carrier, temporarily_unavailable, not_found, invalid_reference, SHIPMENT_CANCELLED, no_longer_available.

messagestring
checked_atstring
suggested_carrierstring | null
suggested_urlstring | null
line_suggestionobject | null

Another line that answered this container directly, shown when the line you named has no record of it.

carrier_codestring
carrier_namestring | null
found_atstring
eta_localstring | null

The ETA on the destination port's own clock, with no offset: YYYY-MM-DDTHH:MM:SS, or a bare YYYY-MM-DD when the line gave a date and no time.

eta_timezonestring | null

The IANA time zone of the destination port (for example Europe/Amsterdam), to label eta_local.

predictive_etastring | null

Our own forecast of the arrival (ISO 8601), served beside eta (the line's date where it gave one).

carrier_etastring | null

The line's own published arrival, as parsed from its answer.

predicted_etastring | null

Stored source of our arrival forecast: carrier_eta shifted by the hull's measured slip at its next port.

prediction_delay_mininteger | null

Signed minutes of the slip behind predicted_eta.

prediction_basisstring | null

ais_delay_propagation when a forecast was published, else why none was (for example no_carrier_eta, no_ais_eta, port_mismatch, delay_immaterial).

prediction_updated_atstring | null

When the forecast fields above were last evaluated.

eta_pending_reason"final_leg_not_published" | null

Why eta is null although the route is known.

published_departurestring | null

The sailing the line published for the port of loading (its ETD or estimated on board date).

document_shipped_onstring | null

Shipped-on-board date stated on your bill of lading (from a document you uploaded).

carrier_sourcestring | null

Who named carrier_code: user (you), lessor (the box owner's records), detected (our resolver) or admin (our support team).

carrier_set_atstring | null

When a person last named carrier_code.

pinned_carrier_codestring | null

The carrier code you named, before any of our rules changed it.

suggested_referencestring | null

A corrected form of identifier that a line answered for, offered as "did you mean".

suggested_reference_atstring | null

When suggested_reference was found.

suggested_reference_evidenceobject | null

What the line returned for the suggested reference.

carrier_codestring | null

The line that answered for the suggestion.

vesselstring | null

Vessel the line names for it.

voyagestring | null

Voyage the line names for it.

polstring | null

Port of loading the line names for it.

podstring | null

Port of discharge the line names for it.

container_countinteger

How many containers the line lists on it.

event_countinteger

How many events the line returned for it.

last_event_atstring | null

Time of the newest event the line returned for it.

editstring

How the suggestion differs from what you typed.

confirmed_atstring

When the line confirmed the suggestion.

line_answered_atstring | null

When the line itself last answered for this box with at least one event.

line_updated_atstring | null

When the line says it last updated this record.

trip_fromstring | null

Start of your own trip for this box: the line's trip that was in progress when you added it.

trip_untilstring | null

End of your own trip, set once the line moved on to the box's next trip.

tracking_status"active" | "pending" | "not_found"

active once the line answered, pending while the first answer is still loading (query again rather than cache the nulls), not_found when the reference never resolved.

tracking_activityobject

Whether the box is still moving or has gone quiet.

state"tracking" | "dormant"
last_event_codestring | null
last_event_atstring | null
last_event_namestring | null
days_since_last_eventinteger | null

Whole days since the newest actual event.

days_since_expected_arrivalinteger | null

Whole days past the later of ETA and the last actual event.

summarystring | null

One sentence you can show as-is.

suggest_archiveboolean
derived_milestonesarray

The milestones we inferred (never filed by the line), also merged into journey_timeline.

derived_milestones[]object
idstring

Stable identifier for the record.

kindstring

carrier_event when a carrier filed it, trackingmcp_inference when we derived the step from surrounding events.

classifierstring

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

occurred_atstring

When the step happened (UTC).

event_namestring

The step in plain language, for example Gated out.

port_unlocodestring

Resolved port UN/LOCODE.

port_namestring

Resolved port name.

facility_namestring | null

Terminal or depot inside the port, when the carrier names one.

evidence_event_idsstring[]

The event ids this step was built from, so an inference can always be traced back.

confidencestring

On a card, whether the slot partners agree with each other.

labelstring

The event in plain words.

port_rolestring | null

The role the port plays on this route: origin, transshipment or destination.

milestonestring | null

The voyage milestone this step marks, when it marks one.

display_positionobject | null

The one pin to draw for the box: an AIS fix or, between fixes, a position reckoned along the route.

latnumber
lngnumber
basisstring | null
estimatedboolean

True when reckoned along the route, not observed.

observed_atstring | null
vessel_historyarray

Every hull this box was reported on, oldest first.

vessel_history[]object
imostring | null
namestring | null
first_seen_atstring | null
last_seen_atstring | null
year_builtinteger | null
rollover_detectedboolean

True when the box was moved off the vessel it was booked on.

rolloverobject | null

The latest vessel change, when rollover_detected is true.

previous_vesselobject
imostring | null
namestring | null
new_vesselobject
imostring | null
namestring | null
detected_atstring
identifierstring | null

The reference the shipment is tracked by.

identifier_typestring | null

What kind of reference identifier is.

previous_tripobject | null

The trip before yours for this box, when the line still reports it.

linestring | null

The line that answered, as its SCAC.

last_eventobject
codestring | null
descriptionstring | null
locationstring | null
unlocodestring | null
datetimestring | null
eventsarray

Every event of that trip, oldest first.

events[]object
codestring | null
descriptionstring | null
locationstring | null
unlocodestring | null
datetimestring | null
ended_atstring | null
legs_partialboolean | null

On a bill of lading or booking: true when legs covers only part of the route its boxes travel.

status_partialboolean | null

On a document with two or more boxes: true when its boxes are not all at the same stage.

discharge_partialboolean | null

On a document with two or more boxes: true when only some of them are discharged.

lessor_notestring | null

A note for leasing-company accounts when no line holds the box yet.

ais_status_suggestionobject | null

A hint that AIS shows the hull under way while the line still files pre-departure.

suggested_status"in_transit"
reasonstring
evidenceobject

The AIS facts the suggestion rests on.

nav_statusstring | null

Navigation status the ship reported over AIS.

distance_from_origin_kminteger

Distance of the ship from the load port, in whole kilometres.

position_fix_atstring | null

When the ship was observed at that position.

near_destinationboolean

True when the ship is within 100 km of the destination port.

added_bystring | null

Internal bookkeeping: the user who added the reference, when a person did.

added_via_api_key_idstring | null

Internal bookkeeping: the API key the reference was added with.

metered_by"legacy" | "credits"

Internal bookkeeping: which meter counts this box.

identifier_type_sourcestring | null

Internal bookkeeping: how we decided what kind of reference this is.

line_event_orderobject | null

Internal bookkeeping: the line's own step order, as we stored it.

keysstring[]

Logical keys of the events in the order the line listed them.

atstring

When this order was recorded.

next_trip_wait_untilstring | null

Internal bookkeeping: when we next ask about a box between trips.

trip_anchor_atstring | null

Internal bookkeeping: when the reference was last added; null reads as added_at.

web_added_atstring | null

Internal bookkeeping: when the reference was added from the web app.

resumeobject

Only on status 202, 401, 403, 404, 409, 500, 503 and 504.

methodstring
pathstring
bodyobject
identifierstring

The reference to add again.

refreshobject

What a force update achieved.

status"fresh" | "timeout" | "no_answer"
refreshedboolean

True when the line answered in this request.

from_cacheboolean

True when the detail is the answer we already held, not one from this request.

reasonstring | null

Null when fresh. One of: line_timeout, line_no_answer, refresh_failed.

requested_atstring
updated_atstring | null

When the line last answered about this shipment: this request when fresh, else the answer shown.

refreshing_in_backgroundboolean

True while the ask is still running after the response (the timeout case).

errorobject

Only on status 202, 401, 403, 404, 409, 429, 500, 503 and 504.

codestring

Machine readable error code.

messagestring

Human readable explanation.

severity"info" | "warning" | "error"

How serious the error is.

retryableboolean

True.

referencestring

The reference.

retry_after_secondsinteger

Seconds to wait.

fieldsstring[]

Offending fields.

user_messagestring

CONTAINER_QUOTA_EXCEEDED only.

credits_requiredinteger | null

Tokens this request needs.

credits_balanceinteger | null

Tokens the wallet holds.

top_up_urlstring

Where to top up.

packagesarray

Plans on offer.

packages[]object
planstring

Plan key.

creditsinteger

Tokens per month.

usdnumber

Monthly price in USD.

reasonstring

CARRIER_NOT_IDENTIFIED only.

waited_secondsinteger

CARRIER_NOT_IDENTIFIED, timed out only.

retry_withstring
member_limitinteger | null

The member cycle limit.

member_spentinteger | null

Tokens the member has used this cycle.

member_remaininginteger | null

Tokens left for the member.

retry_afterinteger

Seconds until the next refresh is allowed.

request_idstring
requestedstring | null
supported_versionsstring[]
oldest_supportedstring
lateststring
docsstring
progressobject
carrier_codestring
carrier_namestring | null
carrier_identifiedtrue
registered_atstring | null
last_checked_atstring | null
next_check_after_seconds60
unresolved_reasonstring
outcomestring

One of: SEALINE_HASNT_PROVIDE_INFO, NO_EVENTS, WRONG_NUMBER, REFERENCE_REQUIRED, LINE_NOT_SUPPORTED, PENDING, UNRESOLVED.

outcome_classstring
sealine_statusstring | null
previous_tripobject | null

The trip before yours for this box, when the line still reports it.

linestring | null

The line that answered, as its SCAC.

last_eventobject
codestring | null
descriptionstring | null
locationstring | null
unlocodestring | null
datetimestring | null
eventsarray
events[]object
codestring | null
descriptionstring | null
locationstring | null
unlocodestring | null
datetimestring | null
ended_atstring | null
lessor_notestring | null

A note for leasing-company accounts when no line holds the box yet.

identified_linestring | null
identified_partystring | null
identified_party_role"current_lessee" | null
required_reference_types("bill_of_lading" | "booking")[] | null
connector_statusstring | null

One of: in_progress, not_supported, connected, reference_required.

notification_interest_availableboolean
carrier_noticeobject | null

Latest reference-specific reply from the named carrier. Only on status 202, 401, 403, 404, 409, 500, 503 and 504.

carrier_code"ZIMU" | "MAEU" | "CHVW"
referencestring
reference_type"container" | "bl" | "booking"
statusstring

One of: other_carrier, temporarily_unavailable, not_found, invalid_reference, SHIPMENT_CANCELLED, no_longer_available.

messagestring
checked_atstring
suggested_carrierstring | null
suggested_urlstring | null
carrier_hint_appliedboolean

Present when the line named was not used. Only on status 202, 401, 403, 404, 409, 500, 503 and 504.

carrier_hint_codestring

Known line that cannot be asked. Only on status 202, 401, 403, 404, 409, 500, 503 and 504.

upgradeobject | null

CONTAINER_QUOTA_EXCEEDED only. Only on status 202, 401, 403, 404, 409, 500, 503 and 504.

planstring

Next plan.

monthly_eurnumber | null

Monthly price.

annual_eurnumber | null

Annual price.

warningstring

Why the line named was not used. Only on status 202, 401, 403, 404, 409, 500, 503 and 504.

Errors

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

STILL_RESOLVING202

Not a failure. The shipment has no tracking data yet. The body carries error.retry_after_seconds and the refresh block. Retry after the Retry-After header.

UNAUTHORIZED401

The key is missing, malformed or revoked.

FORBIDDEN403

The key is read-only. A force update needs a read_write key.

NOT_FOUND404

No such shipment on your account.

CONTAINER_ARCHIVED409

The shipment is archived, so the line is not asked again. data.archived_at says when tracking stopped. To track it again, add the reference with POST /containers.

RATE_LIMITED429

This shipment was force updated with this key less than 5 minutes ago. Retry after the Retry-After header; error.retry_after carries the same seconds.

DEPENDENCY_ERROR503

We could not read the record just now. Retry shortly.

curl -X POST 'https://api.navo24.com/v1/tracking/containers/8f1c2d4e-6a3b-4f52-9c70-11ab22cd33ef/refresh' \
  -H "Authorization: Bearer tmcp_YOUR_API_KEY"
Response
{
  "api_version": "2026-08-04",
  "ok": true,
  "data": {
    "id": "8f1c2d4e-6a3b-4f52-9c70-11ab22cd33ef",
    "container_number": "HLXU8765432",
    "carrier_code": "ONEY",
    "carrier_name": "ONE",
    "status": "in_transit",
    "eta": "2026-10-17T22:00:00+00:00",
    "eta_is_estimated": true
  },
  "refresh": {
    "status": "fresh",
    "refreshed": true,
    "from_cache": false,
    "reason": null,
    "requested_at": "2026-11-10T09:00:00.000Z",
    "updated_at": "2026-11-10T09:00:01.000Z",
    "refreshing_in_background": false
  }
}