1. Introduction
AIS Vessel Tracker is a self-hosted vessel tracking application. It shows vessels currently transmitting AIS (Automatic Identification System) position reports on a live map, keeps a permanent record of every vessel ever seen, and can alert you to distress signals and to vessels entering areas you define — in the spirit of tools like AIS-Catcher's own web UI, MarineTraffic, or ADS-B Exchange, but running entirely on infrastructure you control.
2. Getting started
Open the application's web address in a browser. You'll see:
- A map, centred on a default location, showing every vessel currently transmitting AIS data.
- A sidebar on the left with three tabs: Live, Search register, and My Markers.
- A top bar with a connection status pill, an active-vessel count, a GPS coordinate format selector, an alert bell, a Help button, and a link to the Admin panel.
If the map is empty, that's expected until an AIS receiver is feeding the server data — the connection status pill reflects your browser's link to the server, not whether any vessels are currently transmitting.
3. Map controls & layers
- Pan: click and drag.
- Zoom: scroll wheel, pinch-to-zoom, or the on-screen +/- buttons.
- Switch basemap: use the layers control in the top-right corner.
- Right-click anywhere to see that location's GPS position, with the option to drop a custom marker there.
- Click a vessel (on the map or in a list) to open its detail panel.
| Layer | Source | Notes |
|---|---|---|
| OpenStreetMap | osm.org | Always available |
| NZ Topo50 | LINZ Data Service | Needs a LINZ API key configured on the server |
| NZ Marine | OpenSeaMap nautical overlay on OSM | Always available — buoys, depth areas, harbours |
| NZ Aerial Imagery | LINZ Basemaps API | Needs a LINZ API key configured on the server |
4. Understanding vessel icons
Every vessel's icon is coloured and shaped according to its type, using the same convention as AIS-Catcher's own web UI. A vessel is classified from its most recent AIS report: its reported ship-type code takes priority; if none has been received yet, the app falls back to whether it's a Class A or Class B position report.
Two examples to anchor the scheme: a stationary, unclassified Class B target shows as a pink dot. A moving passenger vessel shows as a blue arrow, pointed in its direction of travel.
5. The Live vessel list & search
The Live tab lists every vessel currently transmitting AIS, scoped to whatever area of the map you can currently see — pan or zoom and the list updates to match. The list stays in alphabetical order (by name, or MMSI if no name is known yet), so a vessel's row stays put as new position reports arrive.
Typing into the "Search all live vessels" box overrides the viewport limit and searches every currently-transmitting vessel by name, MMSI, or callsign, anywhere on the map. Clear the box to return to viewport filtering.
The Search register tab is different: it searches the server's entire permanent vessel database, including vessels whose track has since expired.
6. Vessel details & track history
Click a vessel to open its detail panel, showing name, callsign, IMO number, MMSI, ship type, dimensions, draught, destination/ETA, current position (SOG/COG/heading/navigational status), and its most recent track drawn on the map.
A track is a continuous run of position reports for one vessel. It ends once the vessel goes quiet for a configurable period (60 minutes by default); the vessel then disappears from the Live tab and live map, but its full record stays permanently in the register, searchable from Search register. A new track starts if it transmits again later — old tracks are never reopened or merged.
7. GPS coordinate formats
Every position shown in the app can be displayed in any of three formats, chosen from the dropdown in the top bar:
| Format | Example |
|---|---|
| DD — decimal degrees | 36.84850°S |
| DDM — degrees + decimal minutes | 36°50.910'S |
| DMS — degrees, minutes, seconds | 36°50'54.6"S |
Your choice is saved in this browser (localStorage) and remembered next time —
it's never sent to or stored on the server, so other viewers can each use their own preferred
format.
8. Custom markers
The "My Markers" tab lets you place your own reference points on the map, independent of AIS traffic. Add one by clicking + Add marker and typing a position, or by right-clicking the map and choosing + Add marker here. Position entry auto-detects DD/DDM/DMS format.
localStorage, never uploaded to the server, so nobody else viewing the same map
will see them, and they won't follow you to a different browser or device.9. Alerts
Two independent kinds of alert feed the same real-time notification stream — a toast on every open browser tab, within about a second.
Distress alerts (automatic)
- Navigational status 14 — reserved for "AIS-SART (active), MOB-AIS, EPIRB-AIS".
- An MMSI prefix of
970…,972…, or974…— reserved ranges for SART / MOB / EPIRB devices; seeing one is itself the alert. - AIS message type 9 — a Standard Search-and-Rescue Aircraft position report.
An ongoing distress condition re-alerts at most once every 5 minutes.
Geofence alerts (admin-configured)
An administrator can define a circular or polygon area, optionally filtered by draught, length, beam, and/or navigational status. A vessel triggers the rule the moment it transitions from outside to inside the area, and again if it leaves and re-enters.
The alert bell
The bell icon in the top bar shows a live, session-only alert history for this browser tab. The authoritative, permanent record (with acknowledgement tracking) is always the admin panel's Alert log.
10. Admin panel
The admin panel (/admin) is separate from the public map and requires a login.
It's intended for whoever manages the server, not day-to-day map viewers.
- Overview — totals for vessels, active tracks, feeders, viewers, and unacknowledged alerts.
- Vessels — edit any vessel's name, callsign, ship type, destination, or add a private note.
- Feeders — every AIS data source, its status, packet counts, and (once a station location is set) a range/wind-rose reception chart.
- Viewers — every browser currently holding the live map open.
- Alerts — the geofence rule editor and the permanent alert log.
If you need admin access and don't have credentials, ask whoever administers your server.
11. FAQ & troubleshooting
Why don't I see any vessels?
This server only shows vessels that have sent it AIS data. Someone needs to point a receiver at the server's ingestion ports for anything to appear — check the admin panel's Feeders tab to confirm data is arriving.
Why is a vessel's name or type missing?
Names and ship types arrive periodically via separate static reports; a newly-appeared vessel may take a few minutes to show its name. An administrator can also fill these in manually.
Why did a vessel disappear from the map?
Its track closed after a period of silence (60 minutes by default). It's still permanently recorded — find it under Search register.
Are my custom markers visible to anyone else?
No — they're stored only in your browser and never sent to the server.
What triggers a distress alert?
Navigational status 14, an MMSI in the 970/972/974 ranges, or a SAR aircraft position report — see Alerts above.
Why does a vessel's icon look different than expected?
Icon colour/shape follows the vessel's most recently reported ship type and message type — see Understanding vessel icons. A vessel with no static report yet shows in the generic "unknown type" colour until one arrives.
Is this a substitute for proper navigation equipment?
No. It only displays AIS data that reaches its server, cannot detect vessels not transmitting AIS or out of receiver range, and should never be relied on as a sole means of collision avoidance or navigation.
12. Glossary of AIS terms
| Term | Meaning |
|---|---|
| AIS | Automatic Identification System — vessels broadcast identity, position, course and other data over VHF radio. |
| MMSI | Maritime Mobile Service Identity — a unique 9-digit transponder ID. Certain prefixes are reserved (e.g. 970/972/974 for distress devices). |
| Callsign | A vessel's assigned radio call sign, separate from its name and MMSI. |
| IMO number | A permanent 7-digit identifier for the life of a ship, unlike name or callsign. |
| Class A / Class B | Two AIS transponder categories. Class A is mandatory on most commercial vessels; Class B is common on smaller/leisure craft. |
| Ship type | A numeric code (0–99) for vessel category, e.g. 70–79 cargo, 80–89 tanker, 60–69 passenger. |
| Navigational status | A code (0–15) describing a vessel's current state, e.g. under way, at anchor, moored, or (14) an active distress beacon. |
| SOG | Speed Over Ground — speed relative to the sea floor, in knots. |
| COG | Course Over Ground — actual direction of travel, which can differ from heading due to current/wind. |
| Heading | The direction the bow is physically pointing, distinct from COG. |
| Draught | How deep a vessel sits in the water, waterline to keel bottom, in metres. |
| Base station | A fixed, shore-based AIS station (message type 4) — not a vessel. |
| Aid to navigation (AtoN) | A fixed or floating AIS-equipped marker such as a buoy or beacon (message type 21). |
| AIS-SART / MOB-AIS / EPIRB-AIS | Dedicated emergency AIS transmitters — a search-and-rescue transponder, man-overboard beacon, and emergency position beacon respectively. Reserved MMSI ranges; treated as automatic distress signals. |
| Track | A continuous run of position reports from one vessel, ending after a period of silence. |
| Geofence | A defined map area (circle or polygon) used to trigger an alert when a vessel enters it. |