---
title: "Military Tracking"
description: "Military vessel and aircraft identification, surge detection, foreign presence monitoring, and strategic posture analysis across global theaters."
---
WorldMonitor provides specialized tracking of military vessels and aircraft, identifying assets by their transponder characteristics and monitoring activity patterns. The system detects surge events, foreign military presence in sensitive regions, and assesses strike capability across multiple strategic theaters.

<Note>
The system defines **10 active conflict zones** (Iran, Strait of Hormuz, Ukraine, Gaza, South Lebanon, Red Sea, Sudan, Myanmar, Korean DMZ, Pakistan-Afghanistan Border) and **4 military command hotspots** (INDO-PACIFIC, CENTCOM, EUCOM, ARCTIC). Different subsystems group these into theater lists tailored to their specific analysis, so theater counts vary by context throughout this page.
</Note>

## Backed by endpoints

The frontend uses generated MilitaryService clients for fresh or scoped reads, while some panels first consume bootstrap or circuit-breaker caches. These are the public REST RPC routes behind the military map layers, posture cards, aircraft enrichment, USNI fleet view, and defense R&D tile.

| Method | Route | What it feeds |
|--------|-------|---------------|
| `GET` | `/api/military/v1/list-military-flights` | Military aircraft map layer, surge inputs, and country-risk signals; the frontend calls it by bounding box through the generated client and the handler serves Redis/relay-backed data. |
| `GET` | `/api/military/v1/get-theater-posture` | AI Strategic Posture cards; `fetchCachedTheaterPosture()` checks bootstrap `theaterPosture`, circuit-breaker cache, and IndexedDB before falling through to this RPC. |
| `GET` | `/api/military/v1/get-aircraft-details` | Single-aircraft Wingbits enrichment for map popups and aircraft detail lookups. |
| `POST` | `/api/military/v1/get-aircraft-details-batch` | Batched Wingbits enrichment for visible military aircraft; the browser keeps a local cache so repeat views do not refetch the same ICAO24 records. |
| `GET` | `/api/military/v1/get-wingbits-status` | Wingbits configuration check used before enabling enrichment-dependent UI. |
| `GET` | `/api/military/v1/get-wingbits-live-flight` | On-demand Wingbits ECS live-position lookup for a selected aircraft. |
| `GET` | `/api/military/v1/get-usni-fleet-report` | Parsed USNI Fleet Tracker report used for naval order-of-battle enrichment and weekly fleet context. |
| `GET` | `/api/military/v1/list-military-bases` | Military bases map layer; viewport, zoom, type, kind, and country filters are clustered server-side. |
| `GET` | `/api/military/v1/list-defense-patents` | Defense Patents panel and R&D signal tile, with CPC, assignee, and result-limit filters. |

## Military Vessel Identification

Vessels are identified as military through multiple methods:

**MMSI Analysis**: Maritime Mobile Service Identity numbers encode the vessel's flag state. The system maintains a mapping of 150+ country codes to identify naval vessels:

| MID Range | Country | Notes |
|-----------|---------|-------|
| 338-339 | USA | US Navy, Coast Guard |
| 273 | Russia | Russian Navy |
| 412-414 | China | PLAN vessels |
| 232-235 | UK | Royal Navy |
| 226-228 | France | Marine Nationale |

**Known Vessel Database**: A curated database of 50+ named vessels enables positive identification when AIS transmits vessel names:

| Category | Tracked Vessels |
|----------|-----------------|
| **US Carriers** | All 11 Nimitz/Ford-class (CVN-68 through CVN-78) |
| **UK Carriers** | HMS Queen Elizabeth (R08), HMS Prince of Wales (R09) |
| **Chinese Carriers** | Liaoning (16), Shandong (17), Fujian (18) |
| **Russian Carrier** | Admiral Kuznetsov |
| **Notable Destroyers** | USS Zumwalt (DDG-1000), HMS Defender (D36), HMS Duncan (D37) |
| **Research/Intel** | USNS Victorious (T-AGOS-19), USNS Impeccable (T-AGOS-23), Yuan Wang |

**Vessel Classification Algorithm**:

1. Check vessel name against known database (hull numbers and ship names)
2. Fall back to AIS ship type code if name match fails
3. Apply MMSI pattern matching for country/operator identification
4. For naval-prefix vessels (USS, HMS, HMCS, HMAS, INS, JS, ROKS, TCG), infer military status

**Callsign Patterns**: Known military callsign prefixes (NAVY, GUARD, etc.) provide secondary identification.

## Naval Chokepoint Monitoring

The system monitors 12 critical maritime chokepoints with configurable detection radii:

| Chokepoint | Strategic Significance |
|------------|----------------------|
| Strait of Hormuz | Persian Gulf access, oil transit |
| Suez Canal | Mediterranean-Red Sea link |
| Strait of Malacca | Pacific-Indian Ocean route |
| Taiwan Strait | Cross-strait tensions |
| Bosphorus | Black Sea access |
| GIUK Gap | North Atlantic submarine route |

When military vessels enter these zones, proximity alerts are generated.

## Naval Base Proximity

Activity near 12 major naval installations is tracked:

- **Norfolk** (USA) - Atlantic Fleet headquarters
- **Pearl Harbor** (USA) - Pacific Fleet base
- **Sevastopol** (Russia) - Black Sea Fleet
- **Qingdao** (China) - North Sea Fleet
- **Yokosuka** (Japan) - US 7th Fleet

Vessels within 50km of these bases are flagged, enabling detection of unusual activity patterns.

## Aircraft Tracking (OpenSky)

Military aircraft are tracked via the OpenSky Network using ADS-B data. OpenSky blocks unauthenticated requests from cloud provider IPs (Vercel, Railway, AWS), so aircraft tracking requires a relay server with credentials.

**Authentication**:

- Register for a free account at [opensky-network.org](https://opensky-network.org)
- Create an API client in account settings to get `OPENSKY_CLIENT_ID` and `OPENSKY_CLIENT_SECRET`
- The relay uses **OAuth2 client credentials flow** to obtain Bearer tokens
- Tokens are cached (30-minute expiry) and automatically refreshed

**Identification Methods**:

- **Callsign matching**: Known military callsign patterns (RCH, REACH, DUKE, etc.)
- **ICAO hex ranges**: Military aircraft use assigned hex code blocks by country
- **Altitude/speed profiles**: Unusual flight characteristics

**Tracked Metrics**:

- Position history (20-point trails over 5-minute windows)
- Altitude and ground speed
- Heading and track

**Activity Detection**:

- Formations (multiple military aircraft in proximity)
- Unusual patterns (holding, reconnaissance orbits)
- Chokepoint transits

## Vessel Position History

The system maintains position trails for tracked vessels:

- **30-point history** per MMSI
- **10-minute cleanup interval** for stale data
- **Trail visualization** on map for recent movement

This enables detection of loitering, circling, or other anomalous behavior patterns.

## Military Surge Detection

The system continuously monitors military aircraft activity to detect **surge events**, significant increases above normal operational baselines that may indicate mobilization, exercises, or crisis response.

### Theater Classification

Military activity is analyzed across five geographic theaters (a subset of the system's full conflict zone and hotspot definitions, scoped to regions with reliable ADS-B coverage for surge analysis):

| Theater | Coverage | Key Areas |
|---------|----------|-----------|
| **Middle East** | Persian Gulf, Levant, Arabian Peninsula | US CENTCOM activity, Iranian airspace |
| **Eastern Europe** | Ukraine, Baltics, Black Sea | NATO-Russia border activity |
| **Western Europe** | Central Europe, North Sea | NATO exercises, air policing |
| **Pacific** | East Asia, Southeast Asia | Taiwan Strait, Korean Peninsula |
| **Horn of Africa** | Red Sea, East Africa | Counter-piracy, Houthi activity |

### Aircraft Classification

Aircraft are categorized by callsign pattern matching:

| Type | Callsign Patterns | Significance |
|------|-------------------|--------------|
| **Transport** | RCH, REACH, MOOSE, HERKY, EVAC, DUSTOFF | Airlift operations, troop movement |
| **Fighter** | VIPER, EAGLE, RAPTOR, STRIKE | Combat air patrol, interception |
| **Reconnaissance** | SIGNT, COBRA, RIVET, JSTARS | Intelligence gathering |

### Baseline Calculation

The system maintains rolling 48-hour activity baselines per theater:

- Minimum 6 data samples required for reliable baseline
- Default baselines when data insufficient: 3 transport, 2 fighter, 1 reconnaissance
- Activity below 50% of baseline indicates stand-down

### Surge Detection Algorithm

```
surge_ratio = current_count / baseline
surge_triggered = (
  ratio >= 2.0 AND
  transport >= 5 AND
  fighters >= 4
)
```

### Surge Signal Output

When a surge is detected, the system generates a `military_surge` signal:

| Field | Content |
|-------|---------|
| **Location** | Theater centroid coordinates |
| **Message** | "Military Transport Surge in [Theater]: [X] aircraft (baseline: [Y])" |
| **Details** | Aircraft types, nearby bases (150km radius), top callsigns |
| **Confidence** | Based on surge ratio (0.6-0.9) |

### Foreign Military Presence Detection

Beyond surge detection, the system monitors for **foreign military aircraft in sensitive regions**, situations where aircraft from one nation appear in geopolitically significant areas outside their normal operating range.

**Sensitive Regions**

The system tracks 18 strategically significant geographic areas:

| Region | Sensitivity | Monitored For |
|--------|-------------|---------------|
| **Taiwan Strait** | Critical | PLAAF activity, US transits |
| **Persian Gulf** | Critical | Iranian, US, Gulf state activity |
| **Baltic Sea** | High | Russian activity near NATO |
| **Black Sea** | High | NATO reconnaissance, Russian activity |
| **South China Sea** | High | PLAAF patrols, US FONOPs |
| **Korean Peninsula** | High | DPRK activity, US-ROK exercises |
| **Eastern Mediterranean** | Medium | Russian naval aviation, NATO |
| **Arctic** | Medium | Russian bomber patrols |

**Detection Logic**

For each sensitive region, the system:

1. Identifies all military aircraft within the region boundary
2. Groups aircraft by operating nation
3. Excludes "home region" operators (e.g., Russian VKS in Baltic excluded from alert)
4. Applies concentration thresholds (typically 2-3 aircraft per operator)

**Critical Combinations**

Certain operator-region combinations trigger **critical severity** alerts:

| Operator | Region | Rationale |
|----------|--------|-----------|
| PLAAF | Taiwan Strait | Potential invasion rehearsal |
| Russian VKS | Arctic | Nuclear bomber patrols |
| USAF | Persian Gulf | Potential strike package |

**Signal Output**

Foreign presence detection generates a `foreign_military_presence` signal:

| Field | Content |
|-------|---------|
| **Title** | "Foreign Military Presence: [Region]" |
| **Details** | "[Operator] aircraft detected: [count] [types]" |
| **Severity** | Critical/High/Medium based on combination |
| **Confidence** | 0.7-0.95 based on aircraft count and type diversity |

## Baseline-Based Surge Detection

Surges are detected by comparing current aircraft counts to historical baselines within defined military theaters:

| Parameter | Value | Purpose |
|-----------|-------|---------|
| Surge threshold | 2.0x baseline | Minimum multiplier to trigger alert |
| Baseline window | 48 hours | Historical data used for comparison |
| Minimum samples | 6 observations | Required data points for valid baseline |

**Aircraft Categories Tracked**:

| Category | Examples | Minimum Count |
|----------|----------|---------------|
| Transport/Airlift | C-17, C-130, KC-135, REACH flights | 5 aircraft |
| Fighter | F-15, F-16, F-22, Typhoon | 4 aircraft |
| Reconnaissance | RC-135, E-3 AWACS, U-2 | 3 aircraft |

### Surge Severity

| Severity | Criteria | Meaning |
|----------|----------|---------|
| **Critical** | 4x baseline or higher | Major deployment |
| **High** | 3x baseline | Significant increase |
| **Medium** | 2x baseline | Elevated activity |

### Military Theaters

Surge detection groups activity into four primary strategic theaters (a simplified grouping used for baseline comparison, distinct from the 5-theater and 9-theater lists used elsewhere):

| Theater | Center | Key Bases |
|---------|--------|-----------|
| Middle East | Persian Gulf | Al Udeid, Al Dhafra, Incirlik |
| Eastern Europe | Poland | Ramstein, Spangdahlem, Lask |
| Pacific | Guam/Japan | Andersen, Kadena, Yokota |
| Horn of Africa | Djibouti | Camp Lemonnier |

### Foreign Presence Detection

A separate system monitors for military operators outside their normal operating areas:

| Operator | Home Regions | Alert When Found In |
|----------|--------------|---------------------|
| USAF/USN | Alaska ADIZ | Persian Gulf, Taiwan Strait |
| Russian VKS | Kaliningrad, Arctic, Black Sea | Baltic Region, Alaska ADIZ |
| PLAAF/PLAN | Taiwan Strait, South China Sea | (alerts when increased) |
| Israeli IAF | Eastern Med | Iran border region |

**Example alert**:
```
FOREIGN MILITARY PRESENCE: Persian Gulf
USAF: 3 aircraft detected (KC-135, RC-135W, E-3)
Severity: HIGH - Operator outside normal home regions
```

### News Correlation

Both surge and foreign presence alerts query the Focal Point Detector for context:

1. Identify countries involved (aircraft operators, region countries)
2. Check focal points for those countries
3. If news correlation exists, attach headlines and evidence

**Example with correlation**:
```
MILITARY AIRLIFT SURGE: Middle East Theater
Current: 8 transport aircraft (2.5x baseline)
Aircraft: C-17 (3), KC-135 (3), C-130J (2)

NEWS CORRELATION:
Iran: "Iran protests continue amid military..."
-> Iran appears in both news (12) and map signals (9)
```

## Aircraft Enrichment

Military aircraft tracking is enhanced with **Wingbits** enrichment data, providing detailed aircraft information that goes beyond basic transponder data.

### What Wingbits Provides

When an aircraft is detected via OpenSky ADS-B, the system queries Wingbits for:

| Field | Description | Use Case |
|-------|-------------|----------|
| **Registration** | Aircraft tail number (e.g., N12345) | Unique identification |
| **Owner** | Legal owner of the aircraft | Military branch detection |
| **Operator** | Operating entity | Distinguish military vs. contractor |
| **Manufacturer** | Boeing, Lockheed Martin, etc. | Aircraft type classification |
| **Model** | Specific aircraft model | Capability assessment |
| **Built Year** | Year of manufacture | Fleet age analysis |

### Military Classification Algorithm

The enrichment service analyzes owner and operator fields against curated keyword lists:

**Confirmed Military** (owner/operator match):

- Government: "United States Air Force", "Department of Defense", "Royal Air Force"
- International: "NATO", "Ministry of Defence", "Bundeswehr"

**Likely Military** (operator ICAO codes):

- `AIO` (Air Mobility Command), `RRR` (Royal Air Force), `GAF` (German Air Force)
- `RCH` (REACH flights), `CNV` (Convoy flights), `DOD` (Department of Defense)

**Possible Military** (defense contractors):

- Northrop Grumman, Lockheed Martin, General Atomics, Raytheon, Boeing Defense, L3Harris

**Aircraft Type Matching**:

- Transport: C-17, C-130, C-5, KC-135, KC-46
- Reconnaissance: RC-135, U-2, RQ-4, E-3, E-8
- Combat: F-15, F-16, F-22, F-35, B-52, B-2
- European: Eurofighter, Typhoon, Rafale, Tornado, Gripen

### Confidence Levels

Each enriched aircraft receives a confidence classification:

| Level | Criteria | Display |
|-------|----------|---------|
| **Confirmed** | Direct military owner/operator match | Green badge |
| **Likely** | Military ICAO code or aircraft type | Yellow badge |
| **Possible** | Defense contractor ownership | Gray badge |
| **Civilian** | No military indicators | No badge |

### Caching Strategy

Aircraft details rarely change, so aggressive caching reduces API load:

- **Server-side**: HTTP Cache-Control headers (24-hour max-age)
- **Client-side**: 1-hour local cache per aircraft
- **Batch optimization**: Up to 20 aircraft per API call

This means an aircraft's details are fetched at most once per day, regardless of how many times it appears on the map.

## Space Launch Infrastructure

The Spaceports layer displays global launch facilities for monitoring space-related activity and supply chain implications.

### Tracked Launch Sites

| Site | Country | Operator | Activity Level |
|------|---------|----------|----------------|
| **Kennedy Space Center** | USA | NASA/Space Force | High |
| **Vandenberg SFB** | USA | US Space Force | Medium |
| **Starbase** | USA | SpaceX | High |
| **Baikonur Cosmodrome** | Kazakhstan | Roscosmos | Medium |
| **Plesetsk Cosmodrome** | Russia | Roscosmos/Military | Medium |
| **Vostochny Cosmodrome** | Russia | Roscosmos | Low |
| **Jiuquan SLC** | China | CNSA | High |
| **Xichang SLC** | China | CNSA | High |
| **Wenchang SLC** | China | CNSA | Medium |
| **Guiana Space Centre** | France | ESA/CNES | Medium |
| **Satish Dhawan SC** | India | ISRO | Medium |
| **Tanegashima SC** | Japan | JAXA | Low |

### Why This Matters

Space launches are geopolitically significant:

- **Military implications**: Many launches are dual-use (civilian/military)
- **Technology competition**: Launch cadence indicates space program advancement
- **Supply chain**: Satellite services affect communications, GPS, reconnaissance
- **Incident correlation**: News about space debris, failed launches, or policy changes

## Strategic Posture Analysis

The AI Strategic Posture panel aggregates military aircraft and naval vessels across defined theaters, providing at-a-glance situational awareness of global force concentrations.

### Strategic Theaters

Nine geographic theaters are monitored continuously for posture analysis (this is a separate, more granular grouping than the surge detection theaters above, tailored for strategic posture assessment with per-theater strike capability thresholds):

| Theater | Bounds | Elevated Threshold | Critical Threshold |
|---------|--------|--------------------|--------------------|
| **Iran Theater** | Persian Gulf, Iraq, Syria (20N-42N, 30E-65E) | 50 aircraft | 100 aircraft |
| **Taiwan Strait** | Taiwan, East China Sea (18N-30N, 115E-130E) | 30 aircraft | 60 aircraft |
| **Korean Peninsula** | North/South Korea (33N-43N, 124E-132E) | 20 aircraft | 50 aircraft |
| **Baltic Theater** | Baltics, Poland, Scandinavia (52N-65N, 10E-32E) | 20 aircraft | 40 aircraft |
| **Black Sea** | Ukraine, Turkey, Romania (40N-48N, 26E-42E) | 15 aircraft | 30 aircraft |
| **South China Sea** | Philippines, Vietnam (5N-25N, 105E-121E) | 25 aircraft | 50 aircraft |
| **Eastern Mediterranean** | Syria, Cyprus, Lebanon (33N-37N, 25E-37E) | 15 aircraft | 30 aircraft |
| **Israel/Gaza** | Israel, Gaza Strip (29N-33N, 33E-36E) | 10 aircraft | 25 aircraft |
| **Yemen/Red Sea** | Bab el-Mandeb, Houthi areas (11N-22N, 32E-54E) | 15 aircraft | 30 aircraft |

### Strike Capability Assessment

Beyond raw counts, the system assesses whether forces in a theater constitute an **offensive strike package**, the combination of assets required for sustained combat operations.

**Strike-Capable Criteria**:

- Aerial refueling tankers (KC-135, KC-10, A330 MRTT)
- Airborne command and control (E-3 AWACS, E-7 Wedgetail)
- Combat aircraft (fighters, strike aircraft)

Each theater has custom thresholds reflecting realistic strike package sizes:

| Theater | Min Tankers | Min AWACS | Min Fighters |
|---------|-------------|-----------|--------------|
| Iran Theater | 10 | 2 | 30 |
| Taiwan Strait | 5 | 1 | 20 |
| Korean Peninsula | 4 | 1 | 15 |
| Baltic/Black Sea | 3-4 | 1 | 10-15 |
| Israel/Gaza | 2 | 1 | 8 |

When all three criteria are met, the theater is flagged as **STRIKE CAPABLE**, indicating forces sufficient for sustained offensive operations.

### Naval Vessel Integration

The panel augments aircraft data with real-time naval vessel positions from AIS tracking. Vessels are classified into categories:

| Category | Examples | Strategic Significance |
|----------|----------|------------------------|
| **Carriers** | CVN, CV, LHD | Power projection, air superiority |
| **Destroyers** | DDG, DDH | Air defense, cruise missile strike |
| **Frigates** | FFG, FF | Multi-role escort, ASW |
| **Submarines** | SSN, SSK, SSBN | Deterrence, ISR, strike |
| **Patrol** | PC, PG | Coastal defense |
| **Auxiliary** | T-AO, AOR | Fleet support, logistics |

**Data Accumulation Note**: AIS vessel data arrives via WebSocket stream and accumulates gradually. The panel automatically re-checks vessel counts at 30, 60, 90, and 120 seconds after initial load to capture late-arriving data.

### Posture Levels

| Level | Indicator | Criteria | Meaning |
|-------|-----------|----------|---------|
| **Normal** | NORM | Below elevated threshold | Routine peacetime activity |
| **Elevated** | ELEV | At or above elevated threshold | Increased activity, possible exercises |
| **Critical** | CRIT | At or above critical threshold | Major deployment, potential crisis |

**Elevated + Strike Capable** is treated as a higher alert state than regular elevated status.

### Trend Detection

Activity trends are computed from rolling historical data:

- **Increasing**: Current activity >10% higher than previous period
- **Stable**: Activity within +/-10% of previous period
- **Decreasing**: Current activity >10% lower than previous period

### Server-Side Caching

Theater posture computations run on edge servers with Redis caching:

| Cache Type | TTL | Purpose |
|------------|-----|---------|
| **Active cache** | 5 minutes | Matches OpenSky refresh rate |
| **Stale cache** | 1 hour | Fallback when upstream APIs fail |

This ensures consistent data across all users and minimizes redundant API calls to OpenSky Network.
