MaritimeService

AIS vessel tracking and NGA navigational warnings

The MaritimeService provides APIs for civilian AIS (Automatic Identification System) vessel data and NGA (National Geospatial-Intelligence Agency) navigational warnings for maritime domain awareness.

Base Path

/api/maritime/v1

GetVesselSnapshot

Retrieves a point-in-time view of AIS vessel traffic and disruptions within a geographic bounding box.

Endpoint: GET /api/maritime/v1/get-vessel-snapshot

Request Parameters

ne_lat · double

North-east corner latitude of bounding box

ne_lon · double

North-east corner longitude of bounding box

sw_lat · double

South-west corner latitude of bounding box

sw_lon · double

South-west corner longitude of bounding box

Response

snapshot · VesselSnapshot

The vessel traffic snapshot

Show VesselSnapshot

snapshot_at · int64

Snapshot timestamp, as Unix epoch milliseconds

density_zones · AisDensityZone[]

Density zones showing vessel concentrations

Show AisDensityZone

id · string · required

Zone identifier

name · string

Zone name (e.g., “Strait of Malacca”)

location · GeoCoordinates

Zone centroid location

intensity · double

Traffic intensity score (0-100)

delta_pct · double

Change from baseline as a percentage

ships_per_day · int32

Estimated ships per day

note · string

Analyst note

disruptions · AisDisruption[]

Detected AIS disruptions

Show AisDisruption

id · string · required

Disruption identifier

name · string

Descriptive name

type · AisDisruptionType

Type of AIS disruption: AIS_DISRUPTION_TYPE_GAP_SPIKE or AIS_DISRUPTION_TYPE_CHOKEPOINT_CONGESTION

location · GeoCoordinates

Location of the disruption

severity · AisDisruptionSeverity

Disruption severity: AIS_DISRUPTION_SEVERITY_LOW, AIS_DISRUPTION_SEVERITY_ELEVATED, or AIS_DISRUPTION_SEVERITY_HIGH

change_pct · double

Percentage change from normal

window_hours · int32

Analysis window in hours

dark_ships · int32

Number of dark ships (AIS off) detected

vessel_count · int32

Number of vessels in the affected area

region · string

Region name

description · string

Human-readable description

Example Request

curl "https://your-domain.com/api/maritime/v1/get-vessel-snapshot?ne_lat=1.5&ne_lon=104.5&sw_lat=1.0&sw_lon=103.5"

Example Response

{
  "snapshot": {
    "snapshot_at": 1709251200000,
    "density_zones": [
      {
        "id": "malacca-strait",
        "name": "Strait of Malacca",
        "location": {
          "latitude": 1.25,
          "longitude": 104.0
        },
        "intensity": 87.5,
        "delta_pct": 12.3,
        "ships_per_day": 450,
        "note": "Elevated traffic due to port congestion in Singapore"
      }
    ],
    "disruptions": [
      {
        "id": "disr-001",
        "name": "Malacca AIS Gap Spike",
        "type": "AIS_DISRUPTION_TYPE_GAP_SPIKE",
        "location": {
          "latitude": 1.3,
          "longitude": 103.9
        },
        "severity": "AIS_DISRUPTION_SEVERITY_ELEVATED",
        "change_pct": 45.2,
        "window_hours": 24,
        "dark_ships": 23,
        "vessel_count": 156,
        "region": "Southeast Asia",
        "description": "Unusual increase in AIS signal gaps detected in the Strait of Malacca"
      }
    ]
  }
}

---

ListNavigationalWarnings

Retrieves active maritime safety warnings from NGA (National Geospatial-Intelligence Agency).

Endpoint: GET /api/maritime/v1/list-navigational-warnings

Request Parameters

page_size · int32

Maximum items per page (1-100)

cursor · string

Cursor for next page

area · string

Optional area filter (e.g., “NAVAREA IV”, “Persian Gulf”)

Response

warnings · NavigationalWarning[]

The list of navigational warnings

Show NavigationalWarning

id · string

Warning identifier

title · string

Warning title

text · string

Full warning text

area · string

Geographic area affected

location · GeoCoordinates

Location of the warning

issued_at · int64

Warning issue date, as Unix epoch milliseconds

expires_at · int64

Warning expiry date, as Unix epoch milliseconds

authority · string

Warning source authority

pagination · PaginationResponse

Pagination metadata

Example Request

curl "https://your-domain.com/api/maritime/v1/list-navigational-warnings?area=NAVAREA+IV&page_size=25"

Example Response

{
  "warnings": [
    {
      "id": "NGA-2024-001",
      "title": "Missile Test Area - Red Sea",
      "text": "Mariners are advised to exercise caution in the vicinity of 15-30N 042-45E due to ongoing missile testing operations.",
      "area": "Red Sea",
      "location": {
        "latitude": 22.5,
        "longitude": 43.5
      },
      "issued_at": 1709164800000,
      "expires_at": 1709424000000,
      "authority": "U.S. National Geospatial-Intelligence Agency"
    }
  ],
  "pagination": {
    "cursor": "eyJvZmZzZXQiOjI1fQ==",
    "has_more": false
  }
}