Skip to main content
Overwatch receives live AIS position reports through AISStream and stores them so that maps, investigations, and cargo estimates always reflect current vessel activity. By default, Overwatch subscribes to AIS data around each monitored port. Two environment variables let you control how much ocean area is covered.

​
Coverage modes

​
Port-based coverage (default)

Overwatch computes a bounding box around each port zone polygon and subscribes to AIS messages within that area. The AISSTREAM_BBOX_BUFFER_DEG variable controls how far the bounding box extends beyond the port boundary. A larger buffer catches vessels that are in transit approaching or departing a port, so map views populate before a vessel reaches anchorage.

​
Global coverage

Set AISSTREAM_GLOBAL=1 to subscribe to a single planet-wide bounding box (-90/-180 to 90/180). This replaces all port-derived bounding boxes and delivers positions for every vessel broadcasting AIS worldwide (~175,000 distinct vessels).
Global coverage delivers 100,000–300,000 vessel positions at any given time compared to approximately 3,000–5,000 with port-based coverage. Make sure your database and infrastructure can handle the increased write volume before enabling this option.

​
In-zone vs. background positions

When AISSTREAM_GLOBAL=1 is on, Overwatch splits each incoming position by whether the vessel is inside a monitored port or chokepoint bounding box:
  • In-zone positions (inside any monitored box) behave exactly like port-based coverage. They are written to ais_positions history, feed the intelligence pipeline (port events, dark-event detection, course-anomaly scoring, cargo estimation, EWMAs), and update vessel_states.
  • Background positions (outside every monitored box) are map-only. They flow through a latest-wins, per-vessel-throttled buffer directly into vessel_states — no ais_positions history row, no analytics side effects. The live map’s worldwide layer reads from vessel_states and vessels_live_tiles, so background vessels still appear on the map with a fresh last-known position.
lastSeen is still updated on every background frame so that when a vessel later enters a monitored zone after a long ocean transit, the entry is not misread as a dark-event gap.
In-zone behavior is byte-for-byte identical to port-based coverage. The changes below only affect vessels outside the monitored boxes.

​
Environment variables

​
Coverage

​
Background ingestion (AISSTREAM_GLOBAL=1 only)

These knobs tune how out-of-zone positions are coalesced and written. Defaults are chosen for a ~175 K-vessel global feed; leave them alone unless you are seeing DB pressure or map-freshness issues. Example: freshen the worldwide map every 5 minutes and drain every 15 seconds.

​
When to adjust coverage

  • Maps look empty far from port — increase AISSTREAM_BBOX_BUFFER_DEG to catch in-transit vessels earlier.
  • You want worldwide last-known coverage on the live map — enable AISSTREAM_GLOBAL=1. Background positions keep the map fresh without writing full position history for the whole planet.
  • Background writes are still too heavy — raise GLOBAL_BACKGROUND_MIN_INTERVAL_S (fewer accepted samples per vessel) or STATIC_DATA_DB_MIN_INTERVAL_S (fewer static-data upserts).
  • Storage or compute costs are too high — reduce AISSTREAM_BBOX_BUFFER_DEG to limit data volume, or leave global mode off.
Position data is automatically downsampled and archived over time to manage storage. See data retention and downsampling for details on retention windows and resolution tiers.