maritimeviz 0.1.0

A Python package designed to analyze and visualize Automatic Identification System (AIS) data, enabling easy exploration of maritime vessel movements through data extraction, cleaning, and analysis. Utilize powerful libraries like NumPy and Pandas for efficient data manipulation, and leverage the interactive mapping capabilities of Leafmap for insightful visualizations of vessel trajectories and other key maritime information.

A Python package to ingest, analyze and visualize Automatic Identification System (AIS) data for maritime vessels, with built-in support for global views, rich export formats, interactive Leafmap maps, and integration with the Global Fishing Watch API.

⚠️ DISCLAIMER: This is the first public release (v0.1.0) and is still under active development. APIs and behaviors may change in future versions.

Installation

pip install maritimeviz

Quickstart

1. Build or open a DuckDB-backed AIS database and ingest a raw AIS stream:

   from maritimeviz.ais_db import AISDatabase
   
   db = AISDatabase("my_data.duckdb")
   db.process("raw_ais_stream.nmea")

2. Query global position reports as GeoJSON:

   geojson = db.get_geojson(report_type="position")

3. Render on an interactive map:

   Note

   The current Map class supports method chaining (e.g. .map_all(...).ship_routes(...)), each call will add a new layer to the map; however we have to manually add layer control as depicted below. Note that this API is still evolving and may be refined in upcoming releases.

   from maritimeviz.viz import Map as VesselMap
   
   m1 = VesselMap()
   m1.map_all(geojson, layer_name="Position Reports") \
     .ship_routes(geojson)
   m1.add_layer_control()
   m1.m  # display in Jupyter or Colab

4. Fetch fishing events from Global Fishing Watch:

   from maritimeviz.gfw_api import GFW_api
   
   client = GFW_api()
   vessels = client.search_vessel(9111254)
   vessel_id = vessels[1]["combinedSourcesInfo"][0]["vesselId"]
   df_events = client.get_fishing_events(
       vessel_id,
       start_date="2023-01-01",
       end_date="2023-06-30",
       limit=20
   )
   df_events.head()

Core Features

• AIS Database Management

  • Ingest raw AIS streams (NMEA, CSV, etc.) sequentially.

  • Materialize global “position” and “static” views

  • Flexible filtering by MMSI, date range, or spatial polygon, and more.

  • Export to GeoJSON, CSV, Shapefile, KML, Excel, or WKT

• Interactive Mapping

  • Leafmap/Folium wrapper for points, routes, heatmaps, and base stations

  • Polygon‐based and MMSI filtering

• Global Fishing Watch API

  • Vessel identity lookup (MMSI/IMO → vesselId)

  • Fetch fishing events, effort statistics, vessel insights

  • Built-in mapping helpers

• Extensible Architecture

  • Pluggable “message processor” classes for Class A, Class B, long‐range, ASM, etc.

  • Utilities for cache clearing, and data cleaning.

  • Roadmap: buoy/water data ingestion, anomaly detection, ML pipelines

Credits

• Global Fishing Watch for vessel & event data (https://globalfishingwatch.org)

• libais for AIS message decoding and parsing (https://github.com/schwehr/libais)

• Mentorship and guidance by Kurt Schewher

• Built on top of: DuckDB, Pandas, GeoPandas, Leafmap, Folium, Shapely, Cachetools, Requests

• Project template courtesy of audreyr/cookiecutter-pypackage

License

Released under the MIT License.