This educational project provides a visualization of maritime Automatic Identification System (AIS) data for the San Francisco Bay Area, focusing on detecting and displaying anomalous vessel behaviors. The system includes:
- A FastAPI backend for processing and broadcasting AIS messages
- A web frontend for map-based vessel visualization with an alert ticker
- An anomaly simulation tool for generating test cases
Project Motivation (click to expand)
This project was inspired by Maritime Pattern Analysis problem sets explored during the National Security Hackathon. It provided an opportunity to learn and experiment with Windsurf IDE and agentic AI coding workflows through a practical maritime application.
Special thanks to Cerebral Valley, Shield Capital, and Windsurf for organizing, supporting, and inspiring this work!
Prerequisites (click to expand)
- Python 3.8+
- Node.js (for advanced frontend development, optional)
- Windsurf IDE (recommended for AI-assisted development)
Quick Start
# Install dependencies
pip install -r requirements.txt
# Start the backend server
uvicorn ais_websocket_server:app --reload
# Starting the Chat Server
uvicorn chat_enabled_server:app --reload --port 5001
# View the application
# Open http://localhost:8000/static/ais_map.html in your browserTo test anomaly detection:
python anomaly_simulation.pyTroubleshooting (click to expand)
Purging Data When Launching Backend:
- To clear all vessel and anomaly state for a fresh test, use the backend's
/reset_dataendpoint. You can do this with curl:This will clear all in-memory vessel state, history, and spatial index. It is useful if you want to start with a clean slate or encounter stale/duplicate vessel data.curl -X POST http://localhost:8000/reset_data
Other Troubleshooting Tips:
- If the map or chat assistant is not updating, ensure the backend is running and accessible at the expected port (default: 8000).
- If you encounter CORS or WebSocket connection issues, make sure your browser and backend are both using the correct hostname and port.
- To force reload vessel data, refresh the browser after resetting the backend data.
- For persistent issues, check backend logs for errors or stack traces.
- If the chat assistant cannot connect, ensure the chat server is running on port 5001 and that your
.envfile contains a valid OpenAI API key.
This project uses aisstream.io to receive live AIS vessel data for the San Francisco Bay Area.
Getting Your Own API Key (click to expand)
To run the project with live AIS data:
- Register for a free account at aisstream.io
- Navigate to your account dashboard and generate an API key
- Copy your API key into a
.envfile in the project root:AISSTREAM_API_KEY=your_actual_key_here - Restart the backend server to begin streaming live data
Subscription Logic (click to expand)
The subscription request includes a geographic bounding box for the Bay Area and requests comprehensive AIS message types including position reports, static data, and aids to navigation.
Example subscription payload:
{
"APIKey": "<YOUR_API_KEY>",
"BoundingBoxes": [[minLat, minLon, maxLat, maxLon]],
"FilterMessageTypes": [
"PositionReport", "StandardClassBPositionReport", "StaticDataReport",
"ShipStaticData", "AidsToNavigationReport", "BaseStationReport"
]
}AIS Message/Data Type Parsing (click to expand)
| Message/Data Type | Backend Parser Function | Key Fields Parsed | Example Values |
|---|---|---|---|
| PositionReport | process_position_report | Latitude, Longitude, SOG, Heading, NavStatus | 37.8, -122.4, 12.0, 90, 0 |
| StandardClassBPositionReport | process_standard_class_b_position_report | Latitude, Longitude, SOG, Heading | 37.8, -122.4, 10.0, 45 |
| StaticData | parse_static_data_fields | ShipName, IMO, Callsign, ShipType, Destination | USS Enterprise, 2011701, NCC1701, Cargo, Risa |
| ShipStaticData | parse_ship_static_data_fields | ShipType, Draught, Dimensions | Cargo, 8.0, 100x20x10x10 |
| AidsToNavigationReport | parse_aids_to_navigation_fields | Name, Latitude, Longitude | Buoy 1, 37.9, -122.5 |
| BaseStationReport | parse_base_station_report_fields | Latitude, Longitude, EPFD, BaseStationID | 37.7, -122.3, GPS, 12345 |
AIS Navigational Status Lookup Table (click to expand)
| Code | Meaning | Emoji/Icon |
|---|---|---|
| 0 | Under way using engine | 🚢 |
| 1 | At anchor | ⚓ |
| 2 | Not under command | ❗ |
| 3 | Restricted manoeuverability | ⛔ |
| 4 | Constrained by her draught | 🛑 |
| 5 | Moored | 🪢 |
| 6 | Aground | ⛱️ |
| 7 | Engaged in fishing | 🎣 |
| 8 | Under way sailing | ⛵ |
| 14 | AIS-SART (active), MOB-AIS, EPIRB-AIS | 🆘 |
| 15 | Unusual/Reserved/Test |
AIS Ship Type Lookup Table (click to expand)
AIS ship type codes provide a standardized classification for vessels. Common codes include:
| Code | Meaning |
|---|---|
| 30 | Fishing |
| 31-32 | Towing |
| 36 | Sailing |
| 37 | Pleasure craft |
| 50 | Pilot vessel |
| 52 | Tug |
| 60 | Passenger ship |
| 70 | Cargo ship |
| 80 | Tanker |
For a complete list, see official IMO/AIS documentation.
MMSI to Flag (Country) Parsing (click to expand)
The first 3 digits of an MMSI (Maritime Mobile Service Identity) represent the vessel's Maritime Identification Digits (MID), which indicate the country of registration. Example MIDs:
| MMSI Prefix | Country | Flag Emoji |
|---|---|---|
| 366-369 | United States | 🇺🇸 |
| 316 | Canada | 🇨🇦 |
| 232-235 | United Kingdom | 🇬🇧 |
| 636 | Liberia | 🇱🇷 |
The system uses a lookup table to convert MMSI prefixes to country names and emoji flags.
The project includes a basic system for detecting unusual vessel behavior patterns:
Anomaly Types (click to expand)
| Anomaly Type | Description | Detection Method |
|---|---|---|
| Teleportation | Vessel position jumps impossibly far in a short time | Distance/time threshold |
| Circle Spoofing | Vessel moves in an unnaturally perfect circular path | Circular pattern detection |
| Speed Anomaly | Vessel speed changes dramatically or exceeds physical limits | Statistical deviation from typical speeds |
| Dark Period | Vessel stops transmitting for suspicious duration | Time since last update |
| Identity Swap | Vessel appears to change identity | MMSI inconsistency detection |
Anomaly Simulator (click to expand)
The anomaly simulator (anomaly_simulation.py) is designed to:
- Inject synthetic AIS anomalies via backend endpoints
- Exercise the alert ticker and detection logic
- Provide a repeatable way to test detection features
About Circle Spoofing (click to expand)
Circle spoofing is a maritime AIS anomaly in which a vessel appears to move in an unnaturally perfect circular path, often the result of deliberate manipulation to mask a vessel's true movements. For more information, see AIS Spoofing Explained by Pole Star Global
Backend Data Structure (click to expand)
- vessels: Latest state for each MMSI
- vessel_history: List of all received reports per MMSI
- vessel_profiles: Rolling statistics for speed/heading
- spatial_index: Geospatial lookup for vessels
- ais_message_queue: Async queue for processing messages
API Endpoints (click to expand)
| Endpoint | Method | Purpose |
|---|---|---|
/ws |
WS | WebSocket for real-time updates |
/inject/telemetry |
POST | Inject synthetic telemetry |
/inject/teleport |
POST | Inject a teleportation anomaly |
/inject/dark_period |
POST | Inject a dark period anomaly |
/inject/identity_swap |
POST | Inject an identity swap anomaly |
/inject/static_data |
POST | Inject static vessel metadata |
/reset_data |
POST | Clear all vessel/anomaly state |
/spatial_query |
GET | Query vessels in a bounding box |
Map Source and Attribution (click to expand)
This project uses Leaflet.js for interactive map rendering and OpenStreetMap as the map data provider.
Map data © OpenStreetMap contributors.
LLM-Enabled Chat Server (click to expand)
This project includes an LLM-enabled chat server to provide interactive vessel and map chat capabilities using OpenAI or compatible APIs. This server is separate from the main AIS backend and must be started independently.
uvicorn chat_enabled_server:app --reload --port 5001
- The chat server will be available at http://localhost:5001
- Ensure your
.envfile contains a valid OpenAI API key (e.g.,OPENAI_API_KEY=your_key_here) - The frontend will connect to this server for chat assistant features
Known Issues & Future Work (click to expand)
- Dynamic testing to proxy Windsurf messages, allowing for review of the data and formats being sent to Windsurf and Codium Cloud.
- Investigate and resolve missing or unprocessed AIS data fields (e.g., vessel destination, type, dimensions) to improve data completeness and visualization.
- Containerize and scale application functions for robust, cloud-native deployment.
- Apply machine learning to enrich, classify, and detect anomalies in AIS and related maritime data streams.
- Visualize first and second order time derivatives (velocity, acceleration) for vessel movement to enable richer analytics.
- Incorporate additional normalized data sources (e.g., geospatial imaging) for cross-correlation and advanced enrichment.
- Integrate more robust error handling, logging, and testing for reliability.
- Support improved vessel type filtering, area-based spoofing/anomaly scenarios, and collaborative map annotation.
- Enhance UI/UX for alert visualization, vessel details, and user interaction (including chat).
- Enable advanced anomaly and threat detection based on use cases supported by enriched and multi-modal data sets.
AIS Standards & References (click to expand)
This project is informed by several key AIS standards and protocols:
- International Telecommunication Union (ITU). (2014). Recommendation ITU-R M.1371-5: Technical characteristics for an automatic identification system using time division multiple access in the VHF maritime mobile frequency band.
- Raymond, E. S. "AIVDM/AIVDO protocol decoding." GPSD Documentation. Read online
- National Marine Electronics Association. NMEA 0183 Standard. Specifications
This project served as a practical exercise to explore Windsurf IDE's capabilities for AI-assisted development.
Learning Outcomes (click to expand)
Through this project, we gained experience with:
- Collaborative coding between human developers and AI assistants
- Real-time feedback loops in development
- Integration of domain knowledge with technical implementation
- WebSocket communication patterns
- Geospatial data visualization
This represents our initial exploration of AI-assisted development rather than a demonstration of Windsurf's full capabilities.
Windsurf IDE Features Used (click to expand)
- Real-time code editing and debugging
- AI collaboration for implementing features
- Running and visualizing both backend and frontend components locally
- Anomaly simulation and testing
This project builds upon numerous open-source tools and standards:
- AIS Data: aisstream.io
- Mapping: Leaflet.js and OpenStreetMap
- Backend: FastAPI
- Development Environment: Windsurf IDE
Special thanks to Cerebral Valley, Shield Capital, and all the hackathon mentors, open-source contributors, and fellow participants who provided guidance and inspiration.
Major contributor: sockcymbal — for key features including the interactive map chat assistant and substantial improvements to user experience.
Project Status: Educational prototype
Security Policy (click to expand)
If you discover a security vulnerability, privacy concern, or bug, please report it to:
fixit [dot] github [at] attentiontransformer [dot] com
Issues will be addressed on a best-effort basis. We appreciate your help in making this project more secure.
MIT License (click to expand)
Copyright (c) 2025 Maritime AIS Bay Area Visualization
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.