Guides › Live map & 3D Globe

Live Map & 3D Globe - Complete Guide

shipdata.net gives you the dry-bulk fleet in two complementary surfaces: the flat live map at /app - a fast, work-oriented MapLibre chart with two top bars, filters, a market-potential gauge, a density heatmap and a replay slider - and the 3D Globe at /globe (also the homepage /) - a cinematic globe.gl view with animated trade-lane arcs, a freight-market ticker, a story tour and a 30-day trade replay. This guide documents every visible element on both, grounded only in what the templates actually render.

Two maps, one fleet - which view to open

The same underlying vessel positions power two distinct surfaces. Knowing which one you're on tells you what controls to expect and where the data comes from.

Flat live map - /app: the signed-in working map. Built on MapLibre with CARTO raster tiles that follow your light/dark theme (dark_all / light_all), capped to zoom 1.5-18. Each ship is a rotated arrow icon coloured by state, refreshing live. This is the view with the two top bars (nav+search and live counters), the region/DWT filters, the market-potential gauge, the Layers menu (density heatmap), the potential and ship-type chips, and the time-machine replay bar. Data: /api/latest (lean per-ship snapshot) + /api/stats (counters) + a live Server-Sent-Events feed at /api/stream, with a 30-45s poll as fallback. A bottom-of-screen bunker price marquee (/api/bunker) scrolls USD/t fuel prices.
3D Globe - /globe (and the homepage /): the public, marketing-facing globe over a NASA night-earth texture with a glowing atmosphere. Ships are merged dots; trade lanes are animated arcs that hug the sea with a comet running load→discharge; ports show VLSFO bunker prices when you zoom in. It carries a top-left legend overlay, a top-right live/Tour/Replay HUD, and a bottom freight-market ticker. Data: /api/globe (positions + lanes + bunkers, cached) and /api/globe_replay (30-day replay). It is fully usable while logged out - a Sign up free / log in CTA appears only for anonymous visitors, and clicking through to a ship or lane page requires login.

Why it matters: a charterer hunting open tonnage near a load port wants /app (filterable, precise, with a market gauge). Anyone wanting the macro picture - where tonnage is bunched, which lanes are firm, where the market index sits - wants the globe. Pick a tonnage band from the selector and the globe narrows to that size class alone: the lane figures and the ship dots both filter to the band you chose, and the live count follows, so what you see on the map always matches the band you are reading.

The two top bars on /app - nav, search, and live counters

The flat map stacks two bars above the map. Both are part of the page chrome, not the map itself.

Row 1 (#bar) - navigation: the site logo, the feature-aware menu, your username (#uname), a Theme toggle (the circle-half icon flips light/dark and re-tiles the basemap instantly via applyMapTheme), and a Log out link.

Row 2 (#bar2) - search + counters, sticky: this row stays pinned as you scroll.

Global search box (#gsearch): only shown to users with the search feature. Placeholder: Search ship name / IMO / MMSI / port / LOCODE / country / operator. It debounces input (250 ms) and queries /api/search, dropping a results panel grouped into Owners / companies (click → that operator's fleet at /ships?owner=…), Ships (name, IMO, MMSI, segment/type - opens /ship/<imo> in a new tab), and Ports (name, LOCODE, country, region - opens /port/<code>). Enter fires the first hit; Escape closes it. This is the fastest way to jump straight to a vessel or port rather than hunting on the map.
Live state counters: four always-visible stats fed from /api/stats.pulse - Underway (green, ships sailing/using engine), Moored (blue, at a berth), At anchor (amber, waiting/drifting), Stopped (grey, stopped/aground/not-under-command). These count the whole tracked fleet (including ships AIS hasn't seen recently), so they're broader than the dots currently plotted. They render as skeleton shimmers until data arrives.
Admin-only diagnostics (.admin-only): hidden for normal users - Target IMO, Mapped, With position, Position rows, Voyage rows, and two amber warn-stats MMSI changes / Name changes (identity-spoof / re-flag watch). An Admin link also appears for admins.
Update stamp (#upd): top-right, e.g. updated 14:32:07 (3,180 ships live) - refreshes on every stream tick so you can confirm the feed is live.

Bunker marquee (#bnk): a thin auto-scrolling ribbon below the bars listing port · grade · $/t (e.g. Singapore VLSFO $790) with an as of date and a history → link to /bunker. It pauses on hover so prices stay readable. Watch it for the fuel cost that drives ballast-vs-laden voyage economics.

Ship dots & the colour legend - the single most important thing to read

Both maps colour every vessel by its operational state and, at sea, by its load condition. The colour is the chartering signal - learn it first.

Flat map (/app) - arrow icons. Each ship is a top-down silhouette (an SDF icon tinted at runtime) rotated to its course-over-ground (cog), so the bow points where the ship is heading; icons scale up as you zoom (≈0.22→0.75). The bottom-left Legend box (built in JS) and the mcolor() function define six colours:

Blue #5fb3ff - In port (moored): at a berth.
Amber #ffb454 - Anchorage (waiting): at anchor / drifting off a port. A wall of amber off a load area = a queue / congestion.
Green #3ddc97 - At sea, Laden: loaded and carrying cargo.
Pink #ff8fa3 - At sea, Ballast: empty, repositioning. This is the colour a broker hunts - a ballaster is open tonnage looking for a cargo.
Light blue #69b0e8 - At sea, load n/a: underway, load status unknown.
Grey #9aa7b5 - Idle / unknown: stopped, aground, not-under-command, or unclassified.

3D Globe - coloured dots. The globe simplifies to three colours, spelled out in the top-left overlay legend: green #3ddc97 = Laden (carrying cargo), red #ff5a5f = Ballast (empty / repositioning), grey #9aa7b5 = In port / unknown. The server encodes this per ship as 2=laden, 0=ballast, anything else=in port/unknown in each dot's third field. Note the globe's empty-ship colour is red, not the flat map's pink.

How to use it: scan for clusters of the empty-ship colour (pink on /app, red on the globe) near a region you load from - that's available tonnage and a soft local market. Clusters of amber off a port mean ships are waiting (tight berths, firmer rates).

Clicking & hovering a ship - popups and tooltips

Flat map (/app) click popup. Clicking any arrow opens a MapLibre popup that fills in two phases. Phase 1 (instant) uses the lean metadata already loaded from /api/latest - ship name (a link to /ship/<imo>), IMO, lat/lon, State, Load, and an Open potential line colour-coded by outlook (High / Mid / Low Potential, Fixed, or Unknown via the ok-* classes). While Phase 1 shows loading details…, Phase 2 fetches /api/mapship and appends: MMSI, vessel type, LOA×beam (m), AIS Status, Destination and ETA, Draught (m), and the position timestamp. At the bottom: a ▸ Open ship page link and a My Fleet star button - ☆ Add to My Fleet turns into a highlighted amber ★ In My Fleet when toggled (POST to /api/favorite with CSRF); clicking it as an anonymous visitor redirects to login. Details are cached, so re-clicking the same ship is instant.

3D Globe ship interactions. Globe dots are merged for rendering speed, so they aren't individually clickable in the usual sense. Instead the page resolves your click on the sea to the nearest vessel within a zoom-dependent threshold (tighter as you zoom in) and opens /ship/<imo>#transit. Hovering a dot pops a small tooltip (#stip) with the ship name and its voyage as FROM>TO in UN/LOCODE - for a laden ship we prefix her load port, so you read the whole leg at a glance (e.g. NLRTM>IEDUB = loaded Rotterdam, discharging Dublin); a ballaster shows the declared destination only (BRFOR), because her last load port is a finished prior cargo and would mislead. A crew-typed route the ship broadcast itself (TRIZM>BRTMT) is shown verbatim. The tooltip also carries her state in matching colour (Laden / Ballast / In port-unknown), her IMO, and the hint click → live transit. The flat /app map now shows the same FROM>TO label on hover too (a light popup, no click needed) - and because that label is pre-built and cached server-side, the map’s first paint is now near-instant rather than waiting on a cold lookup.

Why it matters: the popup is the fastest path from "there's a green ship off Brazil" to "it's a Capesize, laden, ETA Qingdao, draught 18.1 m, last fix 11:04" - and one click to the full vessel page. The My Fleet star turns the map into a watchlist-building tool.

Filters & the market-potential gauge (/app)

Two control clusters drive what's plotted and how the market reads. They combine with logical AND and also re-query the gauge.

The floating top bar (#mbar), top-left over the map:

Layers button: opens the layers menu (next section).
Region dropdown (#mgreg): filters to one sea region, populated server-side from SEA_REGION_NAMES (plus "Open sea / other"); default is all regions.
DWT min / max boxes: a numeric deadweight band filter - type a min and/or max to show only that size class (e.g. 68000-90000 for Panamax). Ships without a DWT are treated as 0.
Market gauge bar (#mgbar) + label (#mglbl): a horizontal stacked bar fed by /api/market_gauge for the current filter. Five segments coloured by open-market potential - High (green), Mid (amber), Low (pink), Fixed (blue), Unknown (grey); each segment's width is its percent share, with the label and count in its hover tooltip. Beside it the label shows the running total ship count plus a per-bucket legend (label, %, count).

Top-right chips (#fltcol):

Potential chips (#mflt): the same five buckets as clickable pills. Click one to toggle it off (it goes faded + struck-through) and those ships vanish from the map. The map filter only applies once fewer than all five are on.
Type / segment chips (#segflt): built dynamically from whatever ship types actually appear in the live feed (Capesize, Panamax, Supramax, Handysize, Other, etc.). Each is a toggle; turn off the segments you don't care about. They're built once so they don't flicker on the 30s refresh.

Why it matters: this is the core broker workflow - filter to your size class and region, then read the gauge. A bar dominated by green/amber "open" tonnage means lots of ships hunting cargo (soft market for owners, good for charterers); a bar dominated by blue "Fixed" means tight availability and firmer rates.

Layers menu, density heatmap & the replay slider (/app)

Layers menu (#lyrmenu): opened by the Layers button. On the fleet map it carries a single toggle:

🔥 Ship density heatmap (lyr-heat): overlays a MapLibre heatmap of vessel positions, coloured low→high as transparent-blue → cyan → green → yellow → red, with radius and intensity that grow as you zoom in (radius ~4→44 px). Ship icons stay drawn on top. Read it as a concentration / congestion map: the red blooms are where tonnage is piled up - anchorages, load areas, choke points like Singapore or the Bosphorus.

Weather is intentionally off this map. A code comment notes the storm and Open-Meteo marine-conditions overlays were moved to each vessel's own page so the fleet view stays focused on positions. (The logic still lives in the file - pulsing storm rings coloured by Saffir-Simpson category from an NHC+GDACS feed, plus a "Conditions at map centre" box reading wind/waves/air/pressure - but those toggles are not exposed on /app; open a ship page to see them.)

Time-machine replay bar (#pbbar), bottom-centre: the flat map's own playback. Pick a window (6h / 12h / 24h / 48h / 72h), press ▷ Replay to fetch /api/playback, and the live arrows are replaced by yellow circle dots that walk through history. Controls: a play/pause button, a scrub slider (#pbsl), a UTC timestamp readout (#pbt), and an ✕ to exit back to live. The live SSE feed is frozen while replay is on so it doesn't fight the playback.

Why it matters: the heatmap answers "where is tonnage bunched right now," and the replay answers "how did ships flow into/out of this area over the last few days" - useful for spotting a building queue at a load port or a wave of departures opening tonnage.

The 3D Globe overlay, layer chips & freight ticker

The globe's top-left overlay (#ov) is the control and legend hub.

Headline count (#cnt): e.g. 12,400 vessels tracked · 3,180 live now (1,950 laden / 1,100 ballast) · 64 lanes - the total tracked fleet, how many have a live position, the laden/ballast split, and how many trade lanes are drawn.
Legend: the three dot colours (Laden / Ballast / In port-unknown), plus two reading hints: a green $22k chip explaining the lane number = current market hire ($/day), and a VLSFO $790 chip explaining the amber port fuel labels (zoom in to reveal).
Layer chips (#layers): five toggles - Ships, Flows (the lane arcs/numbers), Fuel (port VLSFO labels), 🌓 Day/Night (a translucent dark cap over the night side, recomputed every minute from a solar-terminator calculation), and ▶ Animate fleet (off by default). Lit chips are filled accent; off chips are outlined.
Tonnage-band lane filter (#bandsel): a dropdown just under the layer chips. All bands (busiest) is the default - the busiest region-to-region lanes across every size class - the big long-haul majors plus a long tail of shorter regional lanes that surface only as you zoom in (see Zoom to reveal below) - merged and each tagged with its dominant tonnage band. Pick a specific band (Mini-bulk through VLOC, e.g. 55-68K Supramax or 120-190K Capesize) and the globe redraws to show only that band's busiest lanes (up to ~40) with their own $/day rates and sea routes - so you can isolate, say, just the Panamax trade flows and what they are paying. The lane counter updates to match, and the colour scale rescales within the chosen band.
Reading hints: green = strong · amber = mid · red = soft lane rates, marker runs the sea lane load→discharge, zoom in for more lanes, and click a lane for its history, or a ship dot to open it.
Footer links: ← 2D map (to /app), FFA Reports™ (to /report), a Sign up free / log in CTA shown only to anonymous visitors, and an "information only - not advice" disclaimer linking to /about.

Trade-lane arcs. Each lane is drawn as two stacked paths along a real sea route: a continuous dim route line plus a short bright comet that animates load→discharge to show trade direction. Lane colour encodes rate strength via tonne-mile-scaled thresholds - green = top tier, amber = mid, pink = soft. A number floating on the water at the lane's midpoint shows the rate in $Xk/day. Zoom to reveal: the world view deliberately shows only the big long-haul majors, and as you zoom into a region its shorter high-frequency coastal lanes fade in - intra-Baltic, North Sea and similar short-haul trades that carry real volume but score low on tonne-miles, so at world scale they would clutter and lose out to the majors. The lane counter reads N of M lanes so you can watch how many are drawn, and pulls back as you zoom away. Hovering a lane shows its name, band and $/day; clicking a lane or its number opens that lane's history at /lane?band=…&load=…&disch=…. Pulsing green rings mark the busiest loading hubs (the top lanes' origins).

Bottom freight-market ticker (#mkt): our own public freight data, every chip linking to the full FFA Reports™. It shows the DBPI index, Avg hire ($/day composite), per-class FFA spot for Cape / Pmax / Smax / Handy each with a green ▲ / pink ▼ 1-day change %, and a VLSFO bunker chip for the lead port. Why it matters: in one glance you see the market level (DBPI), where each size class is trading, the day's direction, and the fuel cost - the macro backdrop to anything you see on the map.

Globe motion, the Tour, and the 30-day Replay

The globe is alive by default and offers two guided/scrubbed experiences via the top-right HUD (#hud), which carries a pulsing green Live fleet dot plus a ▶ Tour and a ⏱ Replay 30d link.

Default motion: a cinematic intro starts far out in space and glides into the hottest lane, then the globe slowly auto-rotates. The fleet dots are static (real AIS fixes) unless you turn on Animate.
▶ Animate fleet (layer chip): stops the auto-spin and instead dead-reckons underway ships along their course/speed as a sped-up time-lapse (~3,200× real time). To stop drift accumulating, positions re-snap to the true AIS fix every 90 seconds. Turning it back off restores ships to their real positions. Use it to feel the direction and pace of fleet movement; use it off when you want exact current positions.
▶ Tour (#tourbtn): flies the camera through the top six lanes one at a time (~5s each), showing a caption (#tcap) with the lane name, band and $/day. The button flips to ■ Stop; any manual drag of the globe also stops the tour. A quick way to brief yourself on the most important trades.
⏱ Replay 30d (#replay): fetches /api/globe_replay and replaces the live dots with a scrub through the last 30 days of at-sea trade flow. Controls: a play/pause button, a slider, and a UTC date readout that also shows N at sea for that instant; ✕ exits back to live. The full window plays in ~22 seconds. While replay is on the lane arcs and fuel labels are cleared so the historical fleet stands alone. Why it matters: it visualises how tonnage built up or thinned out across regions over the month - a fast read on which basins have been filling with ballasters or emptying out.

Note both pages also self-size to fill the viewport below the variable-height nav so the bottom ticker (globe) and replay bar (both) stay on-screen, and both honour your light/dark theme preference saved in localStorage.