How this instrument works
Everything below is stated so that a competent stranger could reproduce the numbers, or prove them wrong. That is the point: what should be cited is a method and a dataset, never a person's judgement.
1. Source
Automatic Identification System (AIS) broadcasts, received terrestrially and recorded continuously by this project via aisstream.io, an aggregator of volunteer and community receivers. AIS is a legally mandated, unencrypted radio broadcast: ships announce their identity, position, speed and navigational status for collision avoidance. We record two message classes: position reports and static/voyage data.
Records are written to an append-only archive at the moment of receipt. Each record carries our
own receive timestamp (rx) alongside the vessel-reported time. Our clock, not the
carrier's, is the observatory's reference — and the archive is never rewritten.
2. From broadcasts to states
A per-vessel state machine assigns one of: underway, anchored, moored.
Inputs are the declared navigational status and speed over ground. Transitions commit only after
persisting, because AIS flaps:
| State | Trigger | Must persist |
|---|---|---|
| anchored | navigational status = 1 (at anchor) | 5 minutes |
| moored | navigational status = 5 (moored) | 5 minutes |
| moored (inferred) | speed ≤ 0.3 kn, stationary, no declared status | 20 minutes |
| underway | speed ≥ 1.0 kn | 5 minutes |
Inferred mooring is flagged as inferred in the data. Committed transitions emit events:
ANCHOR_START/END, BERTH_START/END, DEPARTED, plus
ZONE_ENTER/LEAVE for the monitored areas. When a berthing follows an anchoring by the
same vessel, the anchorage wait is computed and attached to the berthing event.
3. Classification — the part AIS can't do alone
AIS ship-type codes cannot distinguish a container ship from a bulk carrier: codes 70–79 are all
simply "cargo". Container identification therefore comes from where a vessel berths.
Container-terminal geofences were seeded empirically from the observed berthing positions of large
(230 m+) cargo vessels in our own archive, then labelled against public terminal maps.
A cargo vessel moored inside a container-terminal polygon is classified container;
one of 260 m+ elsewhere in a gateway is container(likely); 120–260 m is
bulk/general(likely). Codes 80–89 are tankers, and are reported separately —
an anchorage full of tankers waiting for refinery berths is not a container queue, and conflating
the two is the most common way port-congestion numbers mislead.
4. Semantic notes
Where a vessel declares "under way using engine" while physically stationary inside a monitored
zone for 30 minutes or more, the instrument records a SEMANTIC_NOTE. These are not errors
in our data; they are observations about the gap between what shipping data says and what is
happening — which is the question this project exists to measure.
5. Known limits
- Terrestrial only. No satellite AIS: vessels vanish mid-ocean and reappear on approach. Absence of a vessel is not evidence of its absence from the world.
- Coverage varies by region. The eight US gateways receive well. Indian gateways and Colombo are recorded but currently sparse to silent. Every response states this.
- Left-censoring. A vessel already anchored when recording began has an unknown true start; such durations are lower bounds and are labelled as such.
- Declared fields are declarations. Destination and ETA are typed by crews and are frequently wrong; we pass them through unmodified and never compute on them.
- Archive gaps. One gap on the first day (2026-07-26T17:20Z to 2026-07-27T12:16Z) while the recorder moved from a laptop to dedicated infrastructure. Disclosed here permanently.
- Geofences are v0.1. Seeded from observation; they will be refined as the archive grows, under version control.
6. Versioning and corrections
This method is v0.1. Changes ship as versioned revisions with a public changelog; prior data snapshots remain immutable. When the instrument is wrong, the correction is published prominently, with the size of the error quantified. Nothing is quietly edited.
7. Citation
Trimtab AIS (ais.trimtabist.com), method v0.1, built by Mrigank Singh. Data CC BY 4.0 · code Apache 2.0 · not for regulatory or safety-of-life reliance · no warranty.