Concepts

NTHMAP is a relatively thin layer over a PostgreSQL + PostGIS database of physical-world entities. Understanding how these entities are modeled will help you make precise queries and build useful integrations.

The five core datasets

Dataset	Source (Phase 2)	Update frequency	Tier gate
Vessels	AIS via AISstream	every 5 min	free
Infrastructure	GEM + EIA + WPI	static + quarterly	free
World events	NOAA + USGS + NASA FIRMS + GDELT	every 30 min	pro
Commodity prices	FMP + Baltic Exchange	every 15 min	3 free / 12 pro
Chokepoints	NTHMAP proprietary	hourly aggregation	pro

Every entity has a stable ID, a position (lat/lng), and a set of typed attributes. All geometries are stored in EPSG:4326 (WGS-84) and indexed with PostGIS GIST indexes for sub-millisecond spatial queries.

Vessels

A vessel is a ship broadcasting AIS. Each has:

• MMSI (9-digit Maritime Mobile Service Identity — the stable primary key)
• IMO number, name, flag (ISO country code)
• Type — crude tanker, LNG carrier, LPG carrier, chemical tanker, bulk carrier, container ship, etc.
• Commodity — estimated from type + route (crude oil, LNG, containers, …)
• DWT — deadweight tonnage (max cargo capacity, from registry)
• max_draught_m / current_draught_m — the key to cargo estimation
• Load percentage — current_draught / max_draught * 100, a reliable proxy for fullness
• Estimated cargo MT — load_pct/100 × DWT, a point estimate (±20% typical)
• Speed, heading, nav status — underway, anchored, moored
• Destination, ETA, last port — captain-entered (unreliable but useful)

Vessels are viewport-gated: the API only returns vessels inside the bbox you pass, with a smart zoom cap so a world-view query returns the 200 largest vessels rather than thousands of noise.

Infrastructure

Infrastructure is static — buildings and fixed assets. We model:

• LNG terminals (export + import, with mtpa capacity)
• Oil refineries (with bpd capacity)
• Oil + gas pipelines (with route geometry as LineString)
• Ports (with throughput in million tonnes)
• Coal mines, oil fields, strategic petroleum reserves
• Power plants, power transmission (planned)

Each asset has an operator, owner, country, status (operating, construction, proposed, closed), start year, and a representative point. Pipelines additionally have a route_geojson LineString that draws as an animated dashed line on the map.

World events

Events are transient things in the world that affect physical flows. We ingest:

• NOAA alerts — hurricanes, severe weather, marine warnings
• USGS earthquakes — magnitude 2.5+ in the last 24 hours
• NASA FIRMS — active wildfire hotspots (MODIS + VIIRS)
• GDELT — conflict events, sanctions, strikes, port closures

Each event has a lat/lng, an optional radius_km (impact area), a severity (Extreme / Severe / Moderate / Minor), and timestamps (occurred_at, expires_at). The radius_km renders as a translucent circle on the map so you can see what's in the impact zone at a glance.

Commodity prices

Twelve live commodity prices, refreshed every 15 minutes:

Symbol	Commodity	Hub
CLUSD	WTI Crude	Cushing
BZUSD	Brent Crude	Rotterdam
NGUSD	Natural Gas	Henry Hub
NGUSD_JKM	LNG JKM	Asia
HOUSD	Heating Oil	NYMEX
RBUSD	Gasoline RBOB	NYMEX
BDI	Baltic Dry Index	Baltic Exchange
BDC	Baltic Clean Tanker	Baltic Exchange
GCUSD	Gold	COMEX
HGUSD	Copper	COMEX
ALIUSD	Aluminum	LME
CLWTX	WTI-Brent Spread	NYMEX

Free tier sees WTI, Brent, and Natural Gas. Pro sees all 12 plus 30-day history per symbol.

Chokepoints

Eight strategic maritime chokepoints, each with a bounding box, reference "normal" speed, live vessel count, average speed, and status (Normal / Congested / Closed / Alert):

1. Strait of Hormuz
2. Strait of Malacca
3. Suez Canal
4. Bosphorus
5. Panama Canal
6. Danish Straits
7. Cape of Good Hope
8. Gulf of Aden

Status is computed hourly by comparing live vessel speed in the bbox against the reference speed. A chokepoint running 15% below normal speed is flagged Congested; a zone with sanctions or conflict gets Alert.

The draw tool analysis

The most differentiated NTHMAP feature: draw any polygon on the map (or send a GeoJSON polygon to /api/draw/analyze) and get back a regional snapshot:

• Total vessels inside
• Commodity breakdown by vessel type
• Total estimated cargo in MT + crude oil barrels
• All infrastructure assets inside
• All active events inside
• Optional AI flow analysis (Pro)

This is a single PostGIS ST_Within query under the hood and returns in under 100ms for any polygon.

What "live" means

NTHMAP is not a real-time streaming system. It's a pollster that refreshes each dataset on a cadence appropriate to how fast that dataset changes:

• Vessels: every 5 minutes (AIS has inherent latency)
• Prices: every 15 minutes
• Events: every 30 minutes
• Infrastructure: static + quarterly refresh from source

If you need sub-minute freshness for a specific dataset, contact sales about the enterprise tier.