Compatibility tracking
Track a container, bill of lading or booking and receive the compatibility envelope, so an existing integration keeps parsing unchanged. You change the base URL and the key, nothing else.
The key travels in the query string as api_key, which is where a migrating client already puts it. Any Navo24 tmcp_ key works. Bearer tokens are for the native /v1 API.
Aliases served by the same handler: /compat/searates/container, /compat/searates/reference.
Query parameters
Your Navo24 API key (tmcp_ prefix). Create one in the developer portal.
Container number (4 letters and 7 digits), bill of lading, or booking number. Upper-cased and trimmed server-side. The kind is detected from the reference, and metadata.number echoes what you sent. Send type to declare the kind yourself.
Accepts the following types: CT (container), BL (bill of lading), BK (booking).
Force resolution on a specific operating line by SCAC (four letters). Naming a different line than the stored one drops the prior-voyage data and re-resolves on the requested carrier.
Set true to ask for a fresher answer. If a cached answer exists, it is returned at once (from_cache true, refreshing true) and a background re-poll of the shipment is scheduled; the next call shows the refreshed data. The call does not wait for the carrier, so the answer in the same response is not fresh. If no cached answer exists, the flag changes nothing and the normal first-answer path runs. It is not billed extra: a cached answer writes an audit row only and does not count toward api_calls or unique_shipments, and the background re-poll is internal and not metered.
Response schema
249 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.
carrier_notice
What the line itself said about this reference, when it said something that is not tracking data: the shipment is cancelled, the document belongs to another carrier, the line no longer serves it. Present only then.
SCAC of the line that answered.
When the line gave this answer, ISO 8601.
The line's wording, or ours for it.
The reference the line answered about.
container, bl or booking.
The line's verdict: other_carrier, temporarily_unavailable, not_found, invalid_reference, SHIPMENT_CANCELLED or no_longer_available.
The carrier the line points to instead. Null when it names none.
That carrier's tracking site. Null when the line names none.
data
The shipment. An empty object when the answer carries no data.
containers[]
One entry per box. A container lookup returns one. A bill of lading or booking returns every box on the manifest, never a truncated list.
events[]
The milestone timeline, chronological, with a journey-stage tie-break so a run of same-timestamp estimates cannot read as a gate-out before the ship has arrived.
True once the milestone has occurred, false while it is a forecast. Reconciled to be monotonic: everything at or before the latest actual event is actual, so the sequence never reads as out of order.
The line's own status wording, verbatim. Present only when the line stated one.
The true UTC instant of the event, YYYY-MM-DD HH:MM:SS. This is the primary date on every surface, so a value never depends on which clock the carrier reported it in. The port wall clock rides alongside in event_local_datetime.
The DCSA code for the same event, so a client already speaking the standard needs no mapping table. Present on every event.
Which DCSA family the code belongs to: EQUIPMENT, TRANSPORT or SHIPMENT.
The carrier own wording for the move where we hold it, otherwise a generic label for the code. The carrier sentence wins deliberately: a code-derived label discards a fact the line already stated.
EMPTY or LADEN, on equipment events. Null when the carrier did not report the fill state: the standard has no unknown value and we do not invent one, and this is not an end-of-shipment signal.
carrier when the line stated whether the box was empty or laden, not_reported when it did not. Present on equipment events.
The movement code, drawn from a CLOSED vocabulary of sixteen values and never anything else. Full list in the event code table below. NULL IS A NORMAL VALUE on an ordinary movement, not an error and not only the transshipment delay: it means we hold no code from this closed set for that move, and the incumbent withholds a code on the same kind of row. Read the description when the code is null. The row is never dropped for it.
The port local wall clock for the same event, YYYY-MM-DDTHH:MM:SS, no offset. A vessel that departs Yantian at 14:15 on the quay shows date 06:15:00 UTC and event_local_datetime T14:15:00. Null until the carrier connector reports a placeable port.
How precise the timestamp is. date_only means the line gave a calendar day and no time of day, so the time part of date is padding.
IANA zone of the port, such as Asia/Shanghai. The stable companion to the offset, which alone cannot name the zone or survive a DST change. Null when unresolved.
EQUIPMENT or TRANSPORT, derived from the code: arrivals and departures are TRANSPORT, every equipment move is EQUIPMENT. Null only on the transshipment delay notice, which carries no family.
Index into facilities. Null when the carrier named no terminal.
Always false. We do not synthesise events.
Always true: every date on this surface comes from the carrier filing, not from an inference of ours.
Index into locations. Null when the carrier reported no place, or reported only a terminal, which is filed as the facility instead.
One-based position in this timeline, renumbered after duplicate records are removed. A repeated milestone at one place is not a duplicate and keeps its own number (see the duplicates note).
The milestone this event represents. Full vocabulary in the status code table below. Never null.
VESSEL, RAIL, TRUCK or BARGE. Null only on the transshipment delay notice. See the conveyance table for how TRUCK is used as a fallback.
sea or land. VESSEL and BARGE ride water, RAIL and TRUCK ride land.
Minutes to add to date to reach event_local_datetime, so the pair is self describing. Null when unknown.
Index into vessels. NULL ON EVERY LAND MOVE by construction, so a rail or truck leg can never claim to ride a ship, and null on a sea move where the carrier named no hull and the timeline names more than one.
Voyage number. Nulled alongside vessel on a land move, and null when the carrier filed none.
A provenance disclosure, not a formatting flag. True when this box carries a timeline copied from a sibling on the same bill of lading rather than one sourced for this box. A box whose events were fetched in their own request is false even when its dates match a sibling.
Always false, for the reason given on metadata.is_status_from_sealine.
ISO 6346 size and type code. Null when the carrier did not publish one, or when a multi-box bill of lading cannot attribute the parent equipment to one box.
Container number.
Human size and type, normalised so one box type reads one way across carriers. The ISO code is read first and the carrier short code second, and the two tables are held identical on every shared key, so a value such as 40RH renders "40' Reefer" whichever of the two fields the carrier populated. An unrecognised carrier value is passed through untouched rather than guessed at. Null on the same condition as iso_code.
Shipment status for this box, same vocabulary as metadata.status.
facilities[]
Terminals, depots and yards, deduplicated by name. A place with no UN/LOCODE whose name reads as a terminal or an operator is filed here rather than entering locations.
Always null today, for the same reason as locode.
Which registry the facility code came from, for example BIC or SMDG, so a code is never read against the wrong scheme.
ISO 3166-1 alpha-2 of the event that introduced the facility. Null when that event carried no country.
One-based id, referenced by an event facility.
Always null today. Facility coordinates are not published by the carriers we read.
Always null today, for the same reason as lat.
Always null today: carriers give us the facility name only. Present so the shape matches.
Terminal or depot name as the carrier reported it.
Always null today, for the same reason as locode.
locations[]
Every place the payload references, deduplicated. Events and route points point here by id.
English country name. Null when we could not determine the country at all.
ISO 3166-1 alpha-2. Derived from the UN/LOCODE prefix when the reference data is silent.
One-based id, referenced by events and route points.
Latitude. Null when the place is unresolved in our port reference data.
Longitude. Null on the same condition as lat.
Full 5-character UN/LOCODE. NULL MEANS THE CARRIER GAVE A PLACE NAME ONLY and we could not resolve it to a code, not that the place is unknown.
Port or place name, cleaned of a trailing country suffix where a carrier appended one.
State or province. Null when our port reference data holds none for this place.
IANA zone for the port. This is the clock every event date is printed on. Null when the port is unplaced, in which case that event date is the carrier value as filed.
metadata
Everything about the ANSWER rather than the shipment: what resolved, where it came from, how fresh it is, and what it cost you.
api_calls
Your call allowance on the plan behind this key: the total, what you have used, what is left.
Calls left, or null when uncapped.
Call cap for the key. NULL MEANS UNCAPPED, which is the common case. It does not mean zero.
Calls consumed in the current period. Always a real number.
The UTC instant until which this answer may be replayed from our cache. It is set when the answer is assembled: assembly time plus our cache TTL, which is 90 seconds for a shipment that is resolved and 5 seconds for a partial answer still waiting on carrier events. It is not updated_at plus 12 hours. A replayed answer repeats the value from the original assembly, so on a replay it can already be in the past. Do not treat it as the end of the month or as a promise that data stays valid until then.
Which clock every date in this answer is on: utc (the true instant) or local (the port wall clock).
force_update
What force_update achieved. Present only when the request sent force_update and the line was asked.
True when the stored answer is served instead.
Why the stored answer is served: line_timeout, line_no_answer or refresh_failed. Null when fresh.
True when the answer is the one the line gave in this request.
True when the ask is still running after the answer was sent.
When the line was asked, ISO 8601.
fresh: the line answered in this request. timeout: it did not answer in time. no_answer: it answered with nothing usable.
When the line last answered about this shipment: this request when fresh, else the stored answer. Null when it never has.
False on an answer assembled for this call. True when the answer is a replay of one we assembled moments earlier, inside our short response cache. A replay carries the same shipment data as the original; only api_calls and unique_shipments are read live on every call. Use updated_at, not from_cache, to judge how old the data is.
Always false, and deliberately so: our status is derived from the carrier events we hold, not lifted from a carrier status string. Reporting true would misattribute a value we computed.
The reference exactly as you queried it, upper-cased.
True when a fresh check of the line is still running behind this answer. Present only on an answer served from the store or after force_update.
SCAC of the operating line. Falls back to the container prefix when the stored carrier is unresolved and the prefix names a known line, and to the literal auto when even that is unknown.
The line's registered name, for documents. sealine_name keeps the trade name. Falls back to the trade name.
Human carrier name, or the literal Unknown when no line has been resolved. Never null.
shipment_scope
Which trip of a reusable container this answer describes: the move that opened the current trip. Absent or null when the first actual move of the timeline does not name one.
The move that opened the trip: empty_dispatch (the empty released to the shipper) or export_gate_in (the laden gate in for export).
When that move happened.
Where it happened. Null when the line did not locate it.
Shipment status: PLANNED, IN_TRANSIT, DELIVERED or UNKNOWN. See the shipment status table.
Which identifier resolved: CT container, BL bill of lading, BK booking.
unique_shipments
Same three counters for unique shipments, which is the dimension we meter on. Same null rule.
What is left. It is the figure to alert on.
The allowance on your plan.
How much of it is spent.
When we last wrote this record, in UTC. Null means we hold no write timestamp, which happens only on a record that has never been polled.
warnings[]
Availability notices. Empty when there is nothing to say. An unknown fact stays null in its own field; the notice says why.
CARRIER_NOT_REPORTED: the line has not reported the fields named. CONTAINER_CYCLE_SCOPE: the answer covers the current trip of a reused container only. ETA_OVERDUE: the ETA of the line is more than 7 days past and the line has reported no arrival. POD_ARRIVAL_OBSERVED_BY_AIS: AIS saw the vessel arrive at the port of discharge before the line reported it.
Which facts the notice is about: ETA, POL, POD.
The notice as a sentence.
route
The legs in order. Each carries its two endpoints, its geometry and its vessel.
pod
Port of discharge: where the box leaves the ship, not the inland destination.
True once the move has happened.
basis
Where the place and the date of this point came from, each on its own.
Source of the date, same three values. Null when the point has no date.
Source of the place: line_header (the line's route header), line_event (an event the line filed) or rule (a rule of ours). Null when the point has no place.
The line's own published ETA for this port, beside our estimate. Null when the line declared none, and null once the box has arrived.
The true UTC instant of this point, YYYY-MM-DD HH:MM:SS. Null when the line has not filed the move yet.
The port wall clock for the same moment, no offset. Null when we do not hold the port zone.
Id of the entry in locations. Null when we hold no place for this point.
Our estimate of the arrival at the port of discharge. Equals the recorded arrival once it is actual. Null when we hold no estimate.
IANA zone of the port. Null when unresolved.
Minutes to add to date to reach date_local. Null when unknown.
pol
Port of loading.
True once the move has happened.
basis
Where the place and the date of this point came from, each on its own.
Source of the date, same three values. Null when the point has no date.
Source of the place: line_header (the line's route header), line_event (an event the line filed) or rule (a rule of ours). Null when the point has no place.
The true UTC instant of this point, YYYY-MM-DD HH:MM:SS. Null when the line has not filed the move yet.
The port wall clock for the same moment, no offset. Null when we do not hold the port zone.
Id of the entry in locations. Null when we hold no place for this point.
IANA zone of the port. Null when unresolved.
Minutes to add to date to reach date_local. Null when unknown.
postpod
The inland destination move after the final discharge.
True once the move has happened.
The true UTC instant of this point, YYYY-MM-DD HH:MM:SS. Null when the line has not filed the move yet, or when the point fell back to the port beside it.
The port wall clock for the same moment, no offset. Null when we do not hold the port zone.
Id of the entry in locations. Null when we hold no place for this point.
IANA zone of the port. Null when unresolved.
Minutes to add to date to reach date_local. Null when unknown.
prepol
The inland origin move before the sea leg.
True once the move has happened. Null on a prepol that fell back to the port of loading.
The true UTC instant of this point, YYYY-MM-DD HH:MM:SS. Null when the line has not filed the move yet, or when the point fell back to the port beside it.
The port wall clock for the same moment, no offset. Null when we do not hold the port zone.
Id of the entry in locations. Null when we hold no place for this point.
IANA zone of the port. Null when unresolved.
Minutes to add to date to reach date_local. Null when unknown.
route_data
Map payload: plotted legs, the current pin and live AIS. Null when we hold no plottable route. Additive, and safe to ignore if you only consume the timeline.
ais
Live vessel block. Null when no vessel is under way for this shipment.
data
The AIS-shaped payload. It is nested under a data key because that is the layout of the API this surface is compatible with, not because it is a second envelope.
arrival_port
The arrival call these dates describe.
The 3-letter port code, which is the UN/LOCODE with its country prefix removed and is NOT itself a UN/LOCODE. Kept for compatibility.
ISO 3166-1 alpha-2 country code.
The date of the call, as a port wall-clock string with no offset, which is the layout this block has always used. Read date_label to know whether it is an estimate or an actual.
ETA, ETD, ATA or ATD, saying which kind of time the sibling date is.
Additive to the incumbent shape: the full 5-character UN/LOCODE, so a consumer keying on UN/LOCODE can match this block. Null when the port is unresolved.
departure_port
The departure call these dates describe.
The short port code, as above. Read locode for the standard one.
ISO 3166-1 alpha-2 country code.
The date of the call, in the same wall-clock layout. Read date_label before treating it as an actual.
Which kind of date the neighbouring value is: ETA, ETD, ATA or ATD. Read it before treating a date as an actual.
UN/LOCODE of the place.
discharge_port
The discharge call these dates describe.
The short port code, as above. Read locode for the standard one.
ISO 3166-1 alpha-2 country code.
The date of the sea discharge, in the same wall-clock layout. Read date_label before treating it as an actual.
Which kind of date the neighbouring value is: ETA, ETD, ATA or ATD. Read it before treating a date as an actual.
UN/LOCODE of the place.
Human-readable name.
last_event
The most recent vessel move behind these dates.
When it happened, as a port wall-clock string without an offset, which is the layout this block has always used.
The carrier own phrasing for the event, falling back to our word for the code.
Carrier voyage number, when published. Null otherwise.
last_vessel_position
The most recent fix for the hull, with the time it was taken.
Latitude.
Longitude.
When the fix was taken.
When this AIS block was last rebuilt.
vessel
The hull these dates belong to.
Vessel radio call sign. Null when we hold none.
Flag state of the vessel, as a two-letter code. Null when we hold none.
IMO number of the vessel.
Vessel MMSI. Null when we hold none.
Human-readable name.
Whether the AIS block carries data, and why not when it does not.
Version of the algorithm that drew the map. A number that only goes up.
Stamp of the chart the map was drawn against. Null when none is published.
Current position as [lat, lng]. Null when we hold no position for the carrying vessel.
True when pin is our estimate because the live AIS position went stale. Draw it as an estimate, not as an observed position.
When we calculated the estimate. Never an AIS observation time. Null when the pin is not an estimate.
Time of the last real position the estimate was worked out from. Null when the pin is not an estimate from a vessel position.
True when pin sits close enough to the drawn route to be the same journey.
What the distance above was measured from. vessel_fix: a position the vessel reported, the only independent check. port_anchor: a port that is itself a point of the route, so the distance is near zero by construction. estimate: our estimated position.
How far pin sits from the drawn route, in kilometres.
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.
route[]
Plotted legs, port to port, each with its sea lane or land path.
True when the path crosses the 180th meridian. Split the line there or make the longitudes continuous before drawing. Absent when it does not.
from
Where the leg starts.
Country name.
ISO 3166-1 alpha-2 country code.
Latitude.
Longitude.
UN/LOCODE of the place.
Human-readable name.
State, province or region of the port, when the gazetteer holds one.
IANA time zone of the place. Null when we could not resolve the port.
The shipment's own port to port line, served when path carries the vessel's AIS track and the two differ. Absent when path already is that line.
Points as [lat, lng] pairs, in that order.
Why an absent leg has no line. crosses_land: a straight line would cross land, so none is drawn.
Which runs of path the vessel itself reported, as inclusive index pairs. Absent on a leg not drawn from an AIS track.
Where the path came from. ais_track when it follows positions the vessel reported.
What path is. routed: a sea lane with three or more points. direct: a straight segment between the two ends. absent: nothing to draw.
to
Where the leg ends.
Country name.
ISO 3166-1 alpha-2 country code.
Latitude.
Longitude.
UN/LOCODE of the place.
Human-readable name.
State, province or region of the port, when the gazetteer holds one.
IANA time zone of the place. Null when we could not resolve the port.
The mode carrying the leg, for example VESSEL or TRUCK, when the carrier names it. Null when it does not.
SEA or LAND for the leg.
vessel
The hull that ran the leg. Null on a land leg, and on a sea leg where no hull is known.
Its call sign. Null when unknown.
Its flag, ISO 3166-1 alpha-2. Null when unknown.
Its IMO number. Null when unknown.
Its MMSI. Null when unknown.
Name of the vessel that ran this leg. Null when unknown.
source
Provenance for the geometry and the AIS, so you can tell computed geometry from provider geometry.
Which vessel-position source fed the AIS block.
One sentence of provenance in plain language.
Machine name of the producer.
Display name of the producer.
How the drawn line was produced, for example trackingmcp_computed.
How far the vessel's last reported position sits from the drawn route, in kilometres. Null when the answer carries no position.
Whether route_data is still coming. ready: the map is present. pending: the shipment has movements and its map is being built, ask again in a few minutes. unavailable: there is nothing to draw from and asking again will not change that.
active: a carrier timeline has landed and the route dates come from real events. pending: the reference is trackable but no timeline exists yet, so ask again instead of storing the nulls. not_found: the reference did not resolve.
vessels[]
Every hull the timeline names, deduplicated by IMO and by canonical name.
Call sign. Null when we hold no particulars for this hull.
Flag as an ISO 3166-1 alpha-2 code, derived from the MMSI when the stored flag is absent. Null when neither is available.
One-based id, referenced by an event vessel.
IMO number. Null when the carrier named the ship but gave no IMO.
MMSI. Null on the same condition as call_sign.
Vessel name. Where two sources disagree we emit the fuller spelling, so a name is never silently truncated.
Year the hull was built. Null when we do not hold it.
A human sentence beside the machine code in message, for example which line had no record of the reference. Present on answers without data.
Present only on a container lessor's own account: null, or a sentence when no line shows the box.
With data: OK, or a short sentence when the shipment is served while its reference is still unresolved. Without data, a machine code. Success: NO_EVENTS, NO_CONTAINERS, SEALINE_HASNT_PROVIDE_INFO, SEALINE_CANCELED_SHIPMENT. Error: WRONG_NUMBER, SEALINE_NOT_SUPPORTED, SEALINE_NO_RESPONSE, AUTO_CANT_DETECT_SEALINE, AUTO_CANT_FIND_INFO, UNEXPECTED_ERROR.
success when the request completed, error when it did not. A reference the line has no record of is still a success with an empty data.
Seconds to wait before asking again. The Retry-After header says the same. Only on status 202.
The longest a request waits for the line before this answer is sent. Absent when the request ran into the 85 second ceiling of the whole API. Only on status 202.
Tokens this lookup costs. Null when unknown. Only on status 402.
Tokens the account holds. Only on status 402.
Where to top the balance up. Only on status 402.
packages[]
The token packages on sale. Only on status 402.
Seconds until force_update is accepted again for this reference. Present on that refusal only. Only on status 429.
Errors
This surface follows the incumbent convention: a not-found or still-resolving reference is HTTP 200 with { "status": "error" } and a machine code in message, never a 4xx. Only transport-level failures use a 4xx or 503 status, and those carry prose in message with data null.
We could not work out which carrier the reference belongs to. Re-send the request with sealine set to the line SCAC and it resolves. The body is { "status": "error", "message": "AUTO_CANT_DETECT_SEALINE", "data": {} } plus an additive detail string, which strict parsers can ignore.
The line is known but we could not retrieve the data inside the window this call allows itself. Resolution continues in the background, so a retry a moment later normally succeeds.
The line was asked and did not answer. This names the carrier rather than us, and it is only ever returned when the carrier is genuinely the party that failed.
A success, not a failure: the line replied that it has nothing on file for this reference. Counts as 1 call, never as a billed unique shipment.
The reference has been determined invalid. Same envelope, and the machine code again rides in message rather than in the HTTP status. Where a container number fails its ISO 6346 check digit, detail names the corrected number when one exists.
No number (or container) was supplied. data is null.
The api_key is missing, unknown, revoked or expired. data is null.
The entitlement on this key has expired. data is null.
The per-organisation burst throttle tripped, or the plan allowance is spent. data is null.
Our own storage was unavailable. Retry the request. data is null.
What changes, and what does not
Your parser does not change. The envelope, the field names, the normalised locations, facilities and vessels arrays, the route block and the milestone vocabulary are all reproduced. Three things change: the base URL, the api_key you send, and the fact that the data underneath is ours. Two behaviours are worth reading before you cut over: our nulls are documented field by field below, and the differences we know about are stated on this page rather than left for you to find.
Cold lookups
A reference we have never seen is registered and resolved live. The request is held until real data lands, usually two to four seconds, with a ceiling of twenty-five seconds. If nothing resolves inside that window you get the reason rather than a placeholder: AUTO_CANT_DETECT_SEALINE when we could not work out which carrier the reference belongs to, which you fix by re-sending with sealine, or AUTO_CANT_FIND_INFO when we know the line but could not retrieve the data in time. A retry a moment later normally succeeds because the resolution keeps running in the background. Neither is charged against your allowance, so you can retry freely.
Response statuses, and which ones count
Every answer carries a machine code in message, drawn from the incumbent vocabulary your parser already handles. Five of them are successes: OK when containers and events are both present, NO_EVENTS when the line gave containers but no timeline yet, NO_CONTAINERS when it gave no container list, SEALINE_HASNT_PROVIDE_INFO when the line replied that it holds nothing for this reference, and SEALINE_CANCELED_SHIPMENT when the shipment is cancelled. Every authenticated request counts as 1 call, whatever it answers. Only an answer that carries shipment data (OK, NO_EVENTS or NO_CONTAINERS) becomes a billed unique shipment, once per reference per period. A line answering "nothing found", a cancelled shipment and every error never become a unique shipment, but each try still costs a call, so back off on a miss instead of looping. See Billing and usage.
Which clock the dates use
Every event date, every route date and the AIS block are printed as the true UTC instant, formatted YYYY-MM-DD HH:MM:SS with no offset. This is the same basis on the native API and this compatibility one, so no value depends on which clock a carrier reported it in. The port local wall clock rides alongside each event in event_local_datetime, together with utc_offset_minutes and event_timezone, so you can show quay time without re-deriving it. Each of the four route points carries the same three companions under the names date_local, utc_offset_minutes and timezone, so route.pol can be compared against a port-local system without a timezone table on your side. If a port could not be placed the three stay null rather than being derived, so a null there means we do not know, never assume UTC. metadata.updated_at and metadata.cache_expires are our own bookkeeping and stay in UTC too.
Repeated milestones, and which duplicates we remove
A repeated status at one place is NOT treated as a duplicate. A vessel calling the same port twice, or an arrival and a berthing hours apart, is two real movements, and both rows are returned, exactly as the incumbent returns them. Two different movement codes can also fold onto one milestone at one place, and both of those rows are returned too. Only two things are removed, and both are records rather than movements. First, two events at the SAME instant and the same milestone and place, which is one physical move reported twice by two event families. Second, an unlocated copy of an event we also hold with a resolved UN/LOCODE, which is a bookkeeping artefact rather than a second call. Where a pair does fold we keep the located row, then the actual or the later one, and order_id is renumbered afterwards. UNKN and LTS never fold at all, because neither is a once-per-journey milestone.
Versioning
Versions are dates. Pin one with the API-Version request header (X-API-Version and Navo-API-Version are accepted aliases) and your response shape is held. An unpinned request always resolves to the oldest supported version, never the newest, so a deploy can never move an existing integration onto a new shape. The resolved version is echoed on every response, and an unrecognised value never blocks a request: it falls back and returns API-Version-Warning naming what was sent and what was served. One shape difference exists between the two published versions today: 2026-08-04 spells the unclassified milestone UNKN, and 2027-02-01 spells the same value UNK. Everything else is identical, including the envelope shape.
Event codes
Every value containers[].events[].event_code can carry, and there are exactly sixteen. The vocabulary is CLOSED: a movement we hold under some other code is emitted with event_code null rather than under a name this list does not contain, because a code outside the list is the one thing a migrating parser cannot be expected to handle. Null is an ordinary outcome on an ordinary movement, not a marker for the transshipment delay alone, and the incumbent withholds a code on the same kind of row. When the code is null, read description: the row still carries its wording, its place, its date, its status and its actual flag, so no movement is lost. Note that the code and the milestone are different questions. The code says what the carrier did; status says where on the journey it happened, and several codes reach one milestone.
| Code | Meaning | Usual milestone |
|---|---|---|
| ARRI | Vessel arrival. | VAT at a hub, VAD at the port of discharge, LTS on an inland leg. |
| DEPA | Vessel departure. | VDL at the loading port, VDT at a hub, LTS on an inland leg. |
| LOAD | Container loaded on the vessel. | CLL on the first load, CLT afterwards, LTS on an inland leg. |
| DISC | Container discharged from the vessel. | CDT at a transshipment port, CDD at the final one. |
| GTIN | Container gate in. Our internal DROP token is emitted as GTIN, which is the only gate-in code this vocabulary has. One exception: a laden drop-off at the destination is the delivery to the consignee, so it goes out with event_code null and milestone CDC, not as a gate-in. Every other drop is still GTIN. | CGI laden, CER empty, LTS on an inland leg. |
| GTOT | Container gate out. | CEP when empty, CGO when laden at the destination. |
| PICK | Container picked up. | CPS at the shipper, CGO past the port of discharge, CEP on a merchant-haulage empty pickup. |
| RELS | Released. Carries both the carrier release and the availability-to-collect notice. | UNKN: neither is a positional milestone. |
| STUF | Container stuffed. The long spelling STUFF is emitted as STUF, which is how the wire spells it. | UNKN. |
| STRP | Container stripped. | UNKN. |
| RECE | Received. | UNKN. |
| CONF | Confirmed. | UNKN. |
| CUSR | Customs release. | UNKN. |
| CUSI | Customs inspection. | UNKN. |
| ISSU | Issued. | UNKN. |
| INSP | Inspected. | UNKN. |
| null | No code from the closed set applies. Availability for delivery is the common case, and the transshipment delay notice is a second one. The delivery to the consignee is null too, and so are a line's delivery notices (a delivery order issued, a delivery appointment confirmed), where description carries the line's own words. Fall back to description. | The milestone is still emitted: TSD on the delay notice, CDC on the delivery, UNKN on a delivery notice, and the ordinary positional milestone otherwise. |
Size and type
How containers[].size_type is rendered. Two carrier fields can carry the box type, the ISO code and a short code, and both are read against the same vocabulary so one physical box cannot read two ways depending on which field the line happened to populate. The ISO code is consulted first. A code in neither table is passed through as the carrier wrote it rather than guessed at.
| Carrier value | size_type |
|---|---|
| 22G1, 22G0, 20G1 | 20' Dry Standard |
| 20DV, 20GP | 20' Dry Standard |
| 42G1, 42G0, 40G1 | 40' Dry Standard |
| 40DV, 40GP | 40' Dry Standard |
| 45G1, 45G0 | 40' High Cube Dry |
| 40HC, 40HQ, 45GP | 40' High Cube Dry |
| L5G1 | 45' High Cube Dry |
| 45HC | 45' High Cube Dry |
| 22R1, 20RF | 20' Reefer |
| 42R1, 40RF, 40RH | 40' Reefer. 40RH is a carrier short code rather than a valid ISO 6346 size type, and its second character encodes the 8 foot nominal height, so it is not a high cube. Carriers do file it in the ISO field, so it is recognised there as well as in the short-code field. |
| 45R1 | 40' High Cube Reefer |
| 22T1 | 20' Tank |
| 22KL, 22K0 | 20' Tank for Liquids and Gases |
| 42T1 | 40' Tank |
| 22U1, 20U1 | 20' Open Top |
| 42U1 | 40' Open Top |
| 45U1 | 40' High Cube Open Top |
| 22P1 | 20' Flat Rack |
| 22P3 | 20' Flat Collapsible |
| 42P1 | 40' Flat Rack |
Milestone status codes
Every value containers[].events[].status can carry. The vocabulary is position-aware: one movement code means a different milestone before the loading port, at the loading port, at a transshipment hub, at the port of discharge and on an inland move past it. Two rules do most of the work. Cargo state, not journey position, separates the gate pairs, so an empty release is never confused with a laden gate-out and an empty return is never confused with a laden gate-in. And sea milestones are ordinal rather than matched on UN/LOCODE, so a shipment with a missing port code still splits correctly instead of collapsing into transshipments.
| Code | Meaning | When we emit it | Caveat |
|---|---|---|---|
| CPS | Container picked up at the shipper. | A pickup event before or at the port of loading. | The same physical move at the destination is the laden gate-out (CGO). A pickup on a leg the carrier reports as rail, truck or barge is LTS. |
| CEP | Empty container released to the shipper. | A gate-out the carrier reports as EMPTY, wherever it happens, including an unlocated depot. Also a gate-out at the loading port when no cargo state was reported. | One wording-driven exception: an empty pickup the carrier calls merchant haulage is the release to the shipper (CEP), while a carrier-haulage empty pickup at a depot stays CPS. Nothing else infers CEP from position alone. |
| CGI | Laden gate-in at the port of loading. | A gate-in that is laden, or that carries no cargo state, before the box reaches its destination. Also an arrival at the loading port, including a road or rail arrival there. | A laden gate-in on an explicitly inland leg is LTS, not CGI. |
| CLL | Container loaded on the vessel at the port of loading. | The first load of the itinerary. | Ordinal, not matched on UN/LOCODE, so a shipment with a missing port code still splits correctly. An explicitly inland load is LTS. |
| VDL | Vessel departed the port of loading. | The first departure of the itinerary. | Ordinal, same rule as CLL. An explicitly inland departure is LTS. |
| VAT | Vessel arrived at a transshipment hub. | Any vessel arrival that is not the last sea arrival of the itinerary. | An arrival before the first load, or after the final discharge, is land-side by construction and codes LTS. VAT and VAD are vessel concepts, and a box on a train is at neither. |
| CDT | Container discharged at a transshipment port. | Any discharge the box later sails away from, and any discharge the carrier itself words as a transshipment. | A discharge is the final one only when no sea load or departure follows it. A box discharged at a hub and still waiting for its onward vessel stays CDT, so an arrival is never announced a month early in the wrong country. |
| TSD | Transshipment delay. | A status-only row carrying no movement: no event code, no event family, no conveyance, type sea. Recognised from the carrier exact wording on a row carrying no classifiable code, which covers both an uncoded notice and the DELAY code some lines file. | It is not a discharge. It can appear beside a CDT at the same instant and place, because they are two separate facts. |
| CLT | Container loaded at a transshipment hub. | Any load that is not the first of the itinerary. | |
| VDT | Vessel departed a transshipment hub. | Any departure that is not the first of the itinerary. | |
| BTS | Barge transshipment: the barge or feeder leg serving an inland port. | Only where the carrier own wording names both a barge or feeder and an inland port. | Deliberately biased to precision. Where a feeder IS the carriage rather than an ancillary leg, the ordinary ocean codes apply, so some genuine barge legs read CLT, VDT or CDD instead. Neither the conveyance nor the journey position reproduces this code, and we do not guess it. |
| VAD | Vessel arrived at the port of discharge. | The last sea arrival of the itinerary, and only when the box never sails again after it. | |
| CDD | Container discharged at the final port of discharge. | The last discharge with no onward sea leg after it. An availability notice at the destination folds onto the same milestone. | Two of our movement codes can reach this milestone at one port. Where they land on the same instant that is one physical discharge reported twice and it is folded to a single row; where they land on different instants they are two facts and both rows are returned (see the duplicates note). |
| CGO | Laden gate-out at the destination. | A gate-out or pickup once the box is at or past the port of discharge. | Cargo state decides the gate pairs, not position: an EMPTY gate-out is a release (CEP) wherever it occurs, and only a laden or unstated one at the destination is CGO. |
| CDC | Container delivered to the consignee. | Only where the carrier entire statement is the delivery itself, matched against a short list of unambiguous phrases, or where the line reports a laden drop-off at the destination (its explicit "delivered to consignee"). That row carries event_code null. | Narrow on purpose, and this is a difference worth knowing. Measured against captured carrier envelopes, a broader positional or wording rule rewrites hundreds of correct empty returns into a wrong code, so a delivery whose wording is indistinguishable from a gate-out or an empty return keeps that code instead. We would rather under-emit CDC than write a wrong value into your database. |
| CER | Empty container returned. | A gate-in the carrier reports as EMPTY, anywhere. Also a gate-in with no cargo state once the box is at or past the destination. | The carrier explicit indicator wins where it exists. Most rows carry none, and an EMPTY stated only in the carrier prose is honoured as well. |
| LTS | Inland transport stage: land pre-carriage or on-carriage. | Any load, discharge, departure, gate move or arrival on a leg the carrier explicitly reports as rail, truck or barge. Also a gate-out or arrival before the box reaches its loading port, and an arrival after the port of discharge. | LTS is a category of inland movement, not a once-per-journey milestone. Several LTS rows at one place are normal (an inland origin routinely files both an arrival and a departure) and they are never collapsed onto each other. |
| UNKN | No milestone definition applies to this event. | A gate move at a sea transshipment hub or at no place at all, and ancillary codes with no evidenced milestone: stuffing, stripping, customs inspection, customs release, release and availability notices, and a line's delivery order and delivery appointment notices (these carry event_code null and the line's own words in description, never a gate-out). | The spelling is version-dependent. Version 2026-08-04 emits the four-letter UNKN and version 2027-02-01 emits the three-letter UNK for the same value. An unpinned request keeps UNKN. Either way the row keeps its date, its place and the carrier own description: we would rather carry an unclassified row than force a wrong milestone onto it. |
type and transport_type
These two fields are the pair most migrations map first, and they derive from the same signal, so an event can never read as land while claiming a vessel. An explicit conveyance from the carrier always wins. Where the carrier reports none in a structured field we read its own event wording on an unambiguous whole-word match, and where there is no signal at all a vessel operation is sea and everything else is land.
| transport_type | type | When we emit it |
|---|---|---|
| VESSEL | sea | An ocean leg. Also the default for a load, discharge, departure or arrival where the carrier reports no mode. |
| BARGE | sea | A barge or inland-waterway leg. It rides water, so it is typed sea, and it legitimately names its hull. |
| RAIL | land | An intermodal rail leg, reported by the carrier either in a structured mode field or unambiguously in its own event wording. |
| TRUCK | land | A road leg, and also the fallback for any land-side move where no mode was reported. Read it as not a sea leg rather than as a claim that a truck was used. |
| null | sea | Only on the transshipment delay notice (TSD), which carries no conveyance at all. |
The route block
Four anchor points. On a bill of lading that expanded into per-box timelines the route is derived from the union of those timelines, so it can only ever cite a date you can find elsewhere in the same payload. Each point carries location, date and actual, and only pod carries predictive_eta.
| Point | What it is | How we resolve it |
|---|---|---|
| prepol | The inland origin move before the sea leg. | The first gate or pickup event ahead of the first load or departure. Falls back to the pol location, with a null date and a null actual, when there is no inland origin move. |
| pol | Port of loading. | Anchored on the vessel departure, falling back to the first load. The departure is preferred because a door or rail origin files an inland load first, which would otherwise put the loading port inland and the departure date days early. |
| pod | Port of discharge: where the box leaves the ship. | The last vessel discharge the box never sails away from, and never a discharge the carrier itself calls a transshipment. This is NOT the inland destination on a door or ramp move: that belongs to postpod. |
| postpod | The inland destination move after the final discharge. | The last availability or gate event past the port of discharge. On a multi-box bill of lading this is the last box back to the depot, which is what closes the demurrage clock. Falls back to pod when there is no on-carriage move. |
Shipment status
The value carried by metadata.status and by containers[].status.
| Value | Meaning |
|---|---|
| PLANNED | Booked, not yet departed. |
| IN_TRANSIT | Everything from the origin port through discharge, availability and customs hold. |
| DELIVERED | Delivered, or returned empty. |
| UNKNOWN | Nothing has resolved yet, or the booking was cancelled. |
curl 'https://api.navo24.com/v1/tracking/compat/searates/tracking?api_key=tmcp_YOUR_API_KEY&number=MEDU1234562&type=BK&carrier=COSU&force_update=true'const res = await fetch("https://api.navo24.com/v1/tracking/compat/searates/tracking?api_key=tmcp_YOUR_API_KEY&number=MEDU1234562&type=BK&carrier=COSU&force_update=true");
const data = await res.json();import requests
res = requests.get("https://api.navo24.com/v1/tracking/compat/searates/tracking?api_key=tmcp_YOUR_API_KEY&number=MEDU1234562&type=BK&carrier=COSU&force_update=true")
data = res.json(){
"status": "success",
"message": "OK",
"data": {
"metadata": {
"type": "CT",
"number": "ONEU1234567",
"sealine": "ONEY",
"sealine_name": "ONE",
"status": "DELIVERED",
"is_status_from_sealine": false,
"from_cache": false,
"updated_at": "2026-08-19 10:16:04",
"cache_expires": "2026-08-19 10:17:34",
"api_calls": {
"total": 10000,
"used": 438,
"remaining": 9562
},
"unique_shipments": {
"total": 650,
"used": 61,
"remaining": 589
}
},
"locations": [
{
"id": 1,
"name": "Lagos",
"state": null,
"country": "Nigeria",
"country_code": "NG",
"locode": "NGLOS",
"lat": 6.43427,
"lng": 3.34088,
"timezone": "Africa/Lagos"
},
{
"id": 2,
"name": "Apapa",
"state": null,
"country": "Nigeria",
"country_code": "NG",
"locode": "NGAPP",
"lat": 6.43427,
"lng": 3.34088,
"timezone": "Africa/Lagos"
}
],
"facilities": [
{
"id": 1,
"name": "SIFAX CONTAINER TERMINAL",
"country_code": "NG",
"locode": "NGLOS",
"bic_code": null,
"smdg_code": null,
"lat": null,
"lng": null,
"code_source": "derived"
}
],
"route": {
"prepol": {
"location": 1,
"date": "2026-05-01 09:00:00",
"date_local": "2026-05-01 10:00:00",
"utc_offset_minutes": 60,
"timezone": "Africa/Lagos",
"actual": true
},
"pol": {
"location": 2,
"date": "2026-05-30 00:30:00",
"date_local": "2026-05-30 01:30:00",
"utc_offset_minutes": 60,
"timezone": "Africa/Lagos",
"actual": true
},
"pod": {
"location": 4,
"date": "2026-06-27 04:23:00",
"date_local": "2026-06-27 11:23:00",
"utc_offset_minutes": 420,
"timezone": "Asia/Ho_Chi_Minh",
"actual": true,
"predictive_eta": "2026-06-27 04:23:00"
},
"postpod": {
"location": 6,
"date": "2026-07-04 08:19:00",
"date_local": "2026-07-04 15:19:00",
"utc_offset_minutes": 420,
"timezone": null,
"actual": true
}
},
"vessels": [
{
"id": 1,
"name": "ONE PRESENCE",
"imo": 9444273,
"call_sign": null,
"mmsi": 563290200,
"flag": "SG"
}
],
"containers": [
{
"number": "ONEU1234567",
"iso_code": "45G1",
"size_type": "40' High Cube Dry",
"status": "DELIVERED",
"is_status_from_sealine": false,
"events_mirrored": false,
"events": [
{
"order_id": 1,
"location": 1,
"facility": 1,
"description": "Empty Container Release to Shipper",
"event_type": "EQUIPMENT",
"event_code": "GTOT",
"dcsa_event_code": "GTOT",
"dcsa_event_family": "EQUIPMENT",
"empty_indicator": "EMPTY",
"status": "CEP",
"date": "2026-05-01 09:00:00",
"event_local_datetime": "2026-05-01T10:00:00",
"utc_offset_minutes": 60,
"event_timezone": "Africa/Lagos",
"actual": true,
"is_date_from_sealine": true,
"is_additional_event": false,
"type": "land",
"transport_type": "TRUCK",
"vessel": null,
"voyage": null
},
{
"order_id": 2,
"location": 2,
"facility": null,
"description": "Gate In to Outbound Terminal",
"event_type": "EQUIPMENT",
"event_code": "GTIN",
"dcsa_event_code": "GTIN",
"dcsa_event_family": "EQUIPMENT",
"empty_indicator": null,
"status": "CGI",
"date": "2026-05-06 15:54:00",
"event_local_datetime": "2026-05-06T16:54:00",
"utc_offset_minutes": 60,
"event_timezone": "Africa/Lagos",
"actual": true,
"is_date_from_sealine": true,
"is_additional_event": false,
"type": "land",
"transport_type": "TRUCK",
"vessel": null,
"voyage": null
}
]
}
],
"route_data": {
"route": [
{
"path": [
[
6.439312000000001,
3.3588620000000446
],
[
6.448505,
3.358891999999969
]
],
"type": "LAND",
"transport_type": "TRUCK",
"from": {
"name": "Lagos",
"state": "Lagos State",
"country": "Nigeria",
"country_code": "NG",
"locode": "NGLOS",
"lat": 6.4395,
"lng": 3.3585,
"timezone": "Africa/Lagos"
},
"to": {
"name": "Apapa",
"state": "Lagos State",
"country": "Nigeria",
"country_code": "NG",
"locode": "NGAPP",
"lat": 6.4488,
"lng": 3.35901,
"timezone": "Africa/Lagos"
},
"vessel": null
},
{
"path": [
[
6.4488,
3.3590000000000373
],
[
6.041325,
3.1174062499999877
],
[
5.633849999999999,
2.875812499999938
]
],
"type": "SEA",
"transport_type": "VESSEL",
"from": {
"name": "Apapa",
"state": "Lagos State",
"country": "Nigeria",
"country_code": "NG",
"locode": "NGAPP",
"lat": 6.4488,
"lng": 3.35901,
"timezone": "Africa/Lagos"
},
"to": {
"name": "Singapore",
"state": null,
"country": "Singapore",
"country_code": "SG",
"locode": "SGSIN",
"lat": 1.28967,
"lng": 103.85007,
"timezone": "Asia/Singapore"
},
"vessel": {
"name": "ONE PRESENCE",
"imo": 9444273,
"call_sign": "9VMY9",
"mmsi": 563290200,
"flag": "SG"
}
}
],
"pin": [
27.9392
],
"source": {
"provider": "trackingmcp",
"provider_name": "TrackingMCP",
"route_geometry": "trackingmcp_computed",
"ais": "trackingmcp_vessel_positions",
"note": "Route geometry is computed by TrackingMCP; AIS position is from TrackingMCP vessel tracking."
},
"pin_source": "vessel_position",
"ais": {
"data": {
"vessel": {
"imo": 9629914,
"flag": "JP",
"mmsi": 431225000,
"name": "ONE CONTRIBUTION",
"call_sign": "7KPZ"
},
"last_event": {
"date": "2026-07-04 08:19:00",
"voyage": null,
"description": "Container gate in"
},
"updated_at": "2026-08-19 10:16:04",
"arrival_port": {
"code": "TYO",
"locode": "JPTYO",
"date": "2026-08-08 06:00:00",
"date_label": "ETA",
"country_code": "JP"
},
"departure_port": {
"code": "CMP",
"locode": "VNCMP",
"date": "2026-06-29 01:08:00",
"date_label": "ATD",
"country_code": "VN"
},
"discharge_port": {
"code": "CMP",
"locode": "VNCMP",
"date": "2026-06-27 13:18:00",
"date_label": "ATA",
"country_code": "VN",
"name": "Cai Mep"
},
"last_vessel_position": {
"lat": 27.9392,
"lng": 121.9139,
"updated_at": "2026-08-19 10:16:16"
}
},
"status": "OK"
}
}
}
}