---
title: "GetVesselSnapshot"
method: GET
path: "/api/maritime/v1/get-vessel-snapshot"
tags: ["MaritimeService"]
---

# GetVesselSnapshot

`GET /api/maritime/v1/get-vessel-snapshot`

## Request

- Base URL: `https://api.worldmonitor.app`
- URL: `https://api.worldmonitor.app/api/maritime/v1/get-vessel-snapshot`
- Auth: one of:
  - API key in header `X-WorldMonitor-Key`
  - API key in header `X-Api-Key`

GetVesselSnapshot retrieves a point-in-time view of AIS vessel traffic and disruptions. Empty/absent snapshot with fetched_at=0 or data_available=false means the relay snapshot is unavailable/degraded, not that traffic is confirmed absent.

## Query parameters

- `ne_lat` number, double
- `ne_lon` number, double
- `sw_lat` number, double
- `sw_lon` number, double
- `include_candidates` boolean
- `include_tankers` boolean
- `jmespath` string

## Response `200`

OK

- WorldmonitorMaritimeV1GetVesselSnapshotResponse: GetVesselSnapshotResponse contains the vessel traffic snapshot.
  - `snapshot` WorldmonitorMaritimeV1VesselSnapshot: VesselSnapshot represents a point-in-time view of civilian AIS vessel data.
    - `snapshotAt` integer: Warning: Values > 2^53 may lose precision in JavaScript
    - `densityZones` WorldmonitorMaritimeV1AisDensityZone[]
      - `id` string, required: Zone identifier.
      - `name` string: Zone name (e.g., "Strait of Malacca").
      - `location` WM4: GeoCoordinates represents a geographic location using WGS84 coordinates.
        - `latitude` number, double: Latitude in decimal degrees (-90 to 90).
        - `longitude` number, double: Longitude in decimal degrees (-180 to 180).
      - `intensity` number, double: Traffic intensity score (0-100).
      - `deltaPct` number, double: Change from baseline as a percentage.
      - `shipsPerDay` integer: Estimated ships per day.
      - `note` string: Analyst note.
    - `disruptions` WorldmonitorMaritimeV1AisDisruption[]
      - `id` string, required: Disruption identifier.
      - `name` string: Descriptive name.
      - `type` 'AIS_DISRUPTION_TYPE_UNSPECIFIED' | 'AIS_DISRUPTION_TYPE_GAP_SPIKE' | 'AIS_DISRUPTION_TYPE_CHOKEPOINT_CONGESTION': AisDisruptionType represents the type of AIS tracking anomaly. Maps to TS union: 'gap_spike' | 'chokepoint_congestion'.
      - `location` WM4: GeoCoordinates represents a geographic location using WGS84 coordinates.
        - `latitude` number, double: Latitude in decimal degrees (-90 to 90).
        - `longitude` number, double: Longitude in decimal degrees (-180 to 180).
      - `severity` 'AIS_DISRUPTION_SEVERITY_UNSPECIFIED' | 'AIS_DISRUPTION_SEVERITY_LOW' | 'AIS_DISRUPTION_SEVERITY_ELEVATED' | 'AIS_DISRUPTION_SEVERITY_HIGH': AisDisruptionSeverity represents the severity of an AIS disruption.
      - `changePct` number, double: Percentage change from normal.
      - `windowHours` integer: Analysis window in hours.
      - `darkShips` integer: Number of dark ships (AIS off) detected.
      - `vesselCount` integer: Number of vessels in the affected area.
      - `region` string: Region name.
      - `description` string: Human-readable description.
    - `sequence` integer: Monotonic sequence number from the relay. Clients use this to detect stale responses during polling.
    - `status` WorldmonitorMaritimeV1AisSnapshotStatus: AisSnapshotStatus reports relay health at the time of the snapshot.
      - `connected` boolean: Whether the relay WebSocket is connected to the AIS provider.
      - `vessels` integer: Number of vessels currently tracked by the relay.
      - `messages` integer: Total AIS messages processed in the current session.
    - `candidateReports` WorldmonitorMaritimeV1SnapshotCandidateReport[]
      - `mmsi` string: Maritime Mobile Service Identity.
      - `name` string: Vessel name (may be empty if unknown).
      - `lat` number, double: Latitude in decimal degrees.
      - `lon` number, double: Longitude in decimal degrees.
      - `shipType` integer: AIS ship type code (0 if unknown).
      - `heading` integer: Heading in degrees (0-359, or 511 for unavailable).
      - `speed` number, double: Speed over ground in knots.
      - `course` integer: Course over ground in degrees.
      - `timestamp` integer: Warning: Values > 2^53 may lose precision in JavaScript
    - `tankerReports` WorldmonitorMaritimeV1SnapshotCandidateReport[]
      - `mmsi` string: Maritime Mobile Service Identity.
      - `name` string: Vessel name (may be empty if unknown).
      - `lat` number, double: Latitude in decimal degrees.
      - `lon` number, double: Longitude in decimal degrees.
      - `shipType` integer: AIS ship type code (0 if unknown).
      - `heading` integer: Heading in degrees (0-359, or 511 for unavailable).
      - `speed` number, double: Speed over ground in knots.
      - `course` integer: Course over ground in degrees.
      - `timestamp` integer: Warning: Values > 2^53 may lose precision in JavaScript
  - `fetchedAt` integer: Warning: Values > 2^53 may lose precision in JavaScript
  - `dataAvailable` boolean: True when snapshot is populated. False means an absent snapshot is graceful degradation because the relay snapshot is unavailable.

## Other responses

- `400`: Validation error
- `401`: Missing or invalid API key.
- `403`: API access requires an active subscription (the API key's subscription is inactive or expired).
- `429`: Rate limit exceeded.
- `503`: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
- `default`: Gateway or handler error response.

---

[API](https://skmtc.dev/worldmonitor/apis/worldmonitor-api.md) · [All operations](https://skmtc.dev/worldmonitor/apis/worldmonitor-api/llms.txt) · [OpenAPI document](https://skmtc.dev/worldmonitor/apis/worldmonitor-api/revisions/e3dc8463a5c9?raw)