If you are new to AIS topics, to learn about the Automatic Identification System (AIS).

If you are starting from scratch, download the example ".db" file from our AISdb Tutorial GitHub repository so you can follow this guide with real data.

Python Environment and Installation

To work with the AISdb Python package, please ensure you have Python version 3.10 or higher. If you plan to use SQLite, no additional installation is required, as it is included with Python by default. Those who prefer using a PostgreSQL server must install it separately and can optionally enable the TimescaleDB extension for better performance on large time-series ingests.

User Installation

The AISdb Python package can be conveniently installed using pip. It's highly recommended that a virtual Python environment be created and the package installed within it.

python -m venv 

python -m venv 

You can test your installation by running the following commands:

python
>>> import aisdb
>>> aisdb.__version__  # '1.8.0a0' when built from source, or the latest PyPI release

If you are running Jupyter, ensure it is installed in the same environment as AISdb:

source ./.venv/bin/activate
pip install jupyter
jupyter notebook

The Python code in the rest of this document can be run in the Python environment you created.

To use nightly builds (not mandatory), you can install AISdb from source:

Alternatively, you can use nightly builds (not mandatory) on Google Colab as follows:

AISdb supports SQLite and PostgreSQL databases. When using PostgreSQL, is an optional extension that AISdb can take advantage of for its automatic partitioning and compression of time-series data. It is not required (PostgreSQL alone works fine), but for large ingests it is worth setting up. decode_msgs() exposes a timescaledb argument (default False) that switches on the TimescaleDB-aware table schema when inserting data. If you want to enable it, follow these steps first.

This uses psycopg, which installs automatically with pip install aisdb, so there's nothing extra to add for interfacing with PostgreSQL databases. PostgreSQL accepts these . Alternatively, a connection string may be used. Information on connection strings and PostgreSQL URI format can be found .

Querying SQLite is as easy as providing the name of a ".db" file with the same entity-relationship model as the databases supported by AISdb, which are detailed in the section. We prepared an example SQLite database example_data.db based on AIS data from a small region near Maine, United States, in January 2022 from , which is available in the AISdb GitHub repository.

If you want to create your database using your data, we have a with examples that show you how to create an SQLite database from open-source data.

Parameters for the database query can be defined using . Iterate over rows returned from the database for each vessel with . Convert the results into a generator yielding dictionaries with NumPy arrays describing position vectors, e.g., lon, lat, and time, using .

The following query will return vessel trajectories from a given 1-hour time window:

A specific region can be queried for AIS data using or one of its sub-classes to define a collection of shapely polygon features. For this example, the domain contains a single bounding box polygon derived from a longitude/latitude coordinate pair and radial distance specified in meters. If multiple features are included in the domain object, the domain boundaries will encompass the convex hull of all features.

Additional query callbacks for filtering by region, timeframe, identifier, etc., can be found in and .

The above generator can be input into a processing function, yielding modified results. For example, when modeling the activity of vessels on a per-voyage or per-transit basis, each voyage is defined as a continuous vector of positions where the time between observed timestamps never exceeds 24 hours.

A common problem with AIS data is noise, where multiple vessels might broadcast using the same identifier (sometimes simultaneously). AISdb denoises this data in three steps.

First, denoising with the encoder. The function checks the approximate distance between each vessel's position. It separates vectors where a vessel couldn't reasonably travel using the most direct path, such as when the implied speed exceeds 50 knots.

Second, distance and speed thresholds. These thresholds limit the maximum distance or time between messages that can be considered continuous.

Third, scoring and segment concatenation. A score is computed for each position delta, with sequential messages nearby at shorter intervals given a higher score. This score is calculated by dividing the Haversine distance by elapsed time. Any deltas with a score not reaching the minimum threshold are considered the start of a new segment. New segments are compared to the end of existing segments with the same vessel identifier, and if the score exceeds the minimum, they are concatenated. If multiple segments meet the minimum score, the new segment is concatenated to the existing segment with the highest score.

Notice that processing functions may be executed in sequence as a chain or pipeline, so after segmenting the individual voyages as shown above, results can be input into the encoder to remove noise and correct for vessels with duplicate identifiers.

Building on the above processing pipeline, the resulting cleaned trajectories can be geofenced and filtered for results contained by at least one domain polygon and interpolated for uniformity.

Additional processing functions can be found in the module.

The resulting processed voyage data can be exported in CSV format instead of being printed:

AISdb supports integrating external data sources such as bathymetric charts and other raster grids.

To determine the approximate ocean depth at each vessel position, the module can be used.

Once the data has been downloaded, the class may be used to append bathymetric data to tracks in the context of a processing pipeline like the processing functions described above.

Also, see for determining the approximate nearest distance to shore from vessel positions.

Similarly, arbitrary coordinate-gridded raster data may be appended to vessel tracks.

AIS data from the database may be overlaid on a map such as the one shown below using the function. This function accepts a generator of track dictionaries such as those output by .

For a complete plug-and-play solution, you may clone our .

This quick start covers the basics of loading, querying, and visualizing AIS data. The section goes deeper into each step, starting with , then , and for handling noisy or duplicate position reports.

Overview

Welcome to AISdb, a comprehensive gateway for Automatic Identification System (AIS) data use and applications. AISdb is part of the Making Maritime Informatics Accessible to Everyone (AISViz) project, developed and maintained by the MAPS Lab at Dalhousie University and building on earlier work from the MERIDIAN initiative. It is designed to streamline the collection, processing, and analysis of AIS data, both in live-streaming scenarios and through historical records.

SQL database for storing AIS position reports and vessel metadata

At the heart of AISdb is a database built on SQLite, giving users a friendly Python interface with which to interact. This interface simplifies tasks like database creation, data querying, processing, visualization, and exporting data to CSV format for diverse uses. To cater to advanced needs, AISdb also supports PostgreSQL, including an optional TimescaleDB extension, offering superior concurrency handling and data-sharing capabilities for collaborative environments.

Vessel data cleaning and trajectory modeling

AISdb includes vessel position cleaning and trajectory modeling features. This ensures that the data used for analyses is accurate and reliable, providing a solid foundation for further studies and applications.

Integration with environmental context and external metadata

One of AISdb's unique features is its ability to enrich AIS datasets with environmental context. Users can seamlessly integrate oceanographic and bathymetric data in raster formats to bring depth to their analyses, quite literally, as the tool allows for incorporating seafloor depth data underneath vessel positions. Such versatility ensures that AISdb users can merge various environmental data points with AIS information, resulting in richer, multi-faceted maritime studies.

AISdb offers network graph analysis, MMSI deduplication, interpolation, and other processing utilities. These features enable advanced data processing and analysis, supporting complex maritime studies and applications.

AISdb includes a Python interface with a Rust core, built through PyO3 and Maturin, that paves the way for incorporating machine learning and deep learning techniques into vessel behavior modeling in an optimized way. This aspect of AISdb enhances the reproducibility and scalability of research, be it for academic exploration or practical industry applications.

AISdb is more than just a storage and processing tool. It is a comprehensive platform designed to support research. Through a formal partnership with our research initiative (contact us for more information), academics, industry experts, and researchers can access extensive Canadian AIS data up to 100 km from the Canadian coastline. This dataset spans from January 2012 to the present and is updated monthly. AISdb offers raw and parsed data formats, eliminating preprocessing needs and streamlining AIS-related research.

The MAPS Lab team is based in the lab in collaboration with the research group at Dalhousie University. Our team is funded by the , and our mission revolves around democratizing AIS data use, making it accessible and understandable across multiple sectors, from government and academia to NGOs and the broader public. In addition, AISViz aims to introduce machine learning applications into AISdb's AIS data handling. This effort seeks to streamline user interactions with AIS data, enhancing the user experience by simplifying data access.

Our commitment goes beyond just providing tools. Through AISViz, we're opening doors to innovative research and policy development, targeting environmental conservation, maritime traffic management, and much more. Whether you're a professional in the field, an educator, or a maritime enthusiast, AISViz and its components, including AISdb, offer the knowledge and technology to deepen your understanding and significantly impact marine vessel tracking and the well-being of our oceans.

• Ruixin Song is a research assistant in the Computer Science Department at Dalhousie University. She has an M.Sc. in Computer Science and a B.Eng. in Spatial Information and Digital Technology. Her recent work focuses on marine traffic data analysis and physics-inspired models, particularly in relation to biological invasions in the ocean. Her research interests include mobility data mining, graph neural networks, and network flow and optimization problems.

  • Contact:

• Gabriel Spadon is an Assistant Professor at the Faculty of Computer Science at Dalhousie University, Halifax - NS, Canada. He holds a Ph.D. and an MSc in Computer Science from the University of Sao Paulo, Sao Carlos - SP, Brazil. His research focuses on spatio-temporal analytics, time-series forecasting, and complex network mining, with a deep involvement in data science and engineering, as well as geoinformatics.

• Vaishnav Vaidheeswaran is a Master's student in Computer Science at Dalhousie University. He holds a B.Tech in Computer Science and Engineering and has three years of experience as a software engineer in India, working at cutting-edge startups. His ongoing work focuses on incorporating spatial knowledge into trajectory forecasting models to reduce the aleatoric uncertainty arising from stochastic interactions between the vessel and the environment. His research interests include large language models, graph neural networks, and reinforcement learning.

  • Contact:

• Parth Doshi is a Bachelor's student in Computer Science at Dalhousie University. His ongoing work focuses on developing a Generative Adversarial Network that generates vessel trajectories through agents, as well as on vessel spoofing detection. His research interests include time-series-based forecasting and inverse reinforcement learning.

• Jinkun Chen is a Ph.D. student in Computer Science at Dalhousie University, specializing in Explainable AI, Natural Language Processing (NLP), and Visualization. He earned a bachelor's degree in Computer Science with First-Class Honours from Dalhousie University. Jinkun is actively involved in research, working on advancing fairness, responsibility, trustworthiness, and explainability within Large Language Models (LLMs) and AI.

• Jay Kumar has a Ph.D. in Computer Science and Technology and was a postdoctoral fellow at the Department of Industrial Engineering at Dalhousie University. He has researched AI models for time-series data for over five years, focusing on Recurrent Neural models, probabilistic modeling, and feature engineering data analytics applied to ocean traffic. His research interests include Spatio-temporal Data Mining, Stochastic Modeling, Machine Learning, and Deep Learning.

• Matthew Smith has a BSc degree in Applied Computer Science from Dalhousie University and specializes in managing and analyzing vessel tracking data. He is currently a Software Engineer at Radformation in Toronto, ON. Matt served as the AIS data manager on the MERIDIAN project, where he supported research groups across Canada in accessing and utilizing AIS data. The data was used to answer a range of scientific queries, including the impact of shipping on underwater noise pollution and the danger posed to endangered marine mammals by vessel collisions.

We are passionate about fostering a collaborative and engaged community. We welcome your questions, insights, and feedback as vital components of our continuous improvement and innovation. Should you have any inquiries about AISdb, desire further information on our research, or wish to explore potential collaborations, please don't hesitate to contact us. Staying connected with users and researchers plays a crucial role in shaping the tool's development and ensuring it meets the diverse needs of our growing user base. You can easily contact our team via email or our . In addition to addressing individual queries, we organize webinars and workshops and present at conferences to share knowledge, gather feedback, and widen our outreach. Together, let's advance the understanding and utilization of marine data for a brighter, more informed future in ocean research and preservation.

In addition to utilizing AIS data provided by Spire for the Canadian coasts, you can install AIS receiver hardware to capture AIS data directly. The received data can be processed and stored in databases, which can then be used with AISdb. This approach offers additional data sources and allows you to collect and process your own data (as illustrated in the pipeline below). Doing so lets you customize your data collection efforts to meet specific needs and seamlessly integrate the data with AISdb for enhanced analysis and application. At the same time, you can share the data you collect with others.

Requirements

• Raspberry Pi or other computers with internet connectivity

• 162MHz receiver, such as the

• An antenna in the VHF frequency band (30MHz - 300MHz), e.g., Shakespeare QC-4 VHF Antenna

• Optionally, you may want

  • Antenna mount

  • A filtered preamp, such as , to improve signal range and quality

Another option is free AIS receivers from . This option may require you to share the data with the organization to help expand its AIS-receiving network.

• When setting up your antenna, place it as high as possible and as far away from obstructions and other equipment as is practical.

• Connect the antenna to the receiver. If using a preamp filter, connect it between the antenna and the receiver.

• Connect the receiver to your Linux device via a USB cable. If using a preamp filter, power it with a USB cable.

Below is the antenna hardware setup MERIDIAN uses.

AISdb's receiver is a Rust component exposed to Python as aisdb.start_receiver(). It listens for AIS traffic on a UDP or TCP socket, parses the NMEA sentences, and writes the decoded positions and static reports straight into an SQLite or PostgreSQL database. It does not read a serial port directly, so a USB receiver such as the dAISy needs a small bridge program in front of it to forward the serial bytes onto a local network port. mproxy-client, the same crate the AISdb receiver links against internally, does that job.

On the Raspberry Pi (or whatever Linux box the receiver is plugged into), install Python 3.10 or newer and pull AISdb from PyPI.

pip install aisdb ships prebuilt wheels for the common platforms, so a Rust toolchain is not required just to run the receiver. You only need Rust if you are building AISdb from source.

With the bridge forwarding raw NMEA onto 127.0.0.1:9921, point aisdb.start_receiver() at that port. Save this as ./run_receiver.py.

sqlite_dbpath can be swapped for postgres_connection_string if you would rather write straight into PostgreSQL. connect_addr defaults to aisviz.cs.dal.ca:9920, MERIDIAN's public aggregator. Leaving it at the default also merges MERIDIAN's live feed into your own stream, which is convenient if you want a fuller picture of traffic than your antenna alone can see, but set it to None (as above) if you only want the messages your own receiver decodes.

Wrap the script in its own systemd service the same way as the bridge, pointing ExecStart at your Python interpreter and run_receiver.py, and enable it so both services come up together on boot.

For some Raspberry Pi hardware (the Raspberry Pi 4 Model B is a common example), the device file Linux assigns to the receiver is not always /dev/ttyACM0 as used in the systemd unit above.

Check which device file is actually in use.

On some boards serial0 is linked to ttyS0 rather than a ttyACM* device.

Simply changing /dev/ttyACM0 to /dev/ttyS0 in the service file may produce garbled AIS sentences, because the default baud rate on that port does not match what the receiver expects. Set the baud rate explicitly.

AISdb stores decoded AIS messages in a relational database rather than flat files, which is what makes range queries, joins across message types, and multi-year aggregations practical. Two backends are supported. SQLite is the default for local work, a single-file database that needs no server and is easy to copy or drop into version control for small projects. PostgreSQL is the option for shared or production deployments, and it can optionally run on top of TimescaleDB for large, high-ingest-rate collections. Both backends expose the same table layout and the same DBQuery/TrackGen query interface, so switching between them later mostly means swapping the connection object.

Choosing a Database Backend

Every AISdb database connection is opened through one of two classes in aisdb.database.dbconn, both of which subclass a shared DBConn base and both of which support the context manager protocol (with ... as dbconn:).

SQLiteDBConn wraps a sqlite3.Connection and only needs a filesystem path. If the file does not exist yet, it will be created the first time you decode messages into it.

PostgresDBConn wraps a psycopg connection and accepts either a libpq connection string or individual keyword arguments (host, port, user, dbname, password, and any other keyword recognized by ).

Pick SQLite for quick exploration on your own machine, and PostgreSQL when several people or processes need to read and write the same database, when the collection grows past what a single SQLite file handles comfortably, or when you plan to enable TimescaleDB (see below). Regardless of the backend, accepts either connection type as its dbconn argument, and the same DBQuery/TrackGen code works unchanged against both.

When loading data into the database, messages are sorted into SQL tables determined by the message type and month. The table names follow this format, where {YYYYMM} is the four-digit year and two-digit month.

Some additional tables containing computed data may be created depending on the indexes used. Examples include an aggregate of vessel static data by month and a virtual table used as a covering index.

Additional tables are also included for storing data not directly derived from AIS message reports.

For quick reference to data types and detailed explanations of these table entries, please see the .

In addition to querying the database using the module, there is an option to customize the query with your own SQL code. The examples below connect directly with sqlite3, which works against an SQLite database file. Against PostgreSQL, swap sqlite3.connect(dbpath) for psycopg.connect(...) (or reuse the connection already opened through aisdb.PostgresDBConn) and the same SQL runs unchanged, since both backends share identical table and column names.

Example of listing all the tables in your database:

As messages are separated into tables by message type and month, queries spanning multiple message types or months should use UNIONs and JOINs to combine results as appropriate.

Example of querying tables with JOIN:

Each row in results is a plain tuple, one element per selected column, in the order listed in the SELECT. A row from the query above looks like this.

The exact rows you see depend on what is in your database. Rows come back in whatever order SQLite returns them unless you add an ORDER BY clause, and vessel_name/ship_type will be None for any MMSI with no matching row in the static table (since the query uses a LEFT JOIN).

More information about SQL queries can be found in .

The ais_{YYYYMM}_dynamic tables are created with a composite primary key over (mmsi, time, longitude, latitude, sog, cog, source) on SQLite, which acts as a covering index for the queries DBQuery generates. Filtering on a narrow range of MMSIs, timestamps, longitudes, and latitudes lets SQLite satisfy most of the query directly from that index, so query performance improves the more you narrow those bounds. Broad, unbounded queries will scan a much larger share of the table and will not benefit as much. If you need custom indexes for a specific manual query, define them directly on the monthly ais_{YYYYMM}_dynamic and ais_{YYYYMM}_static tables rather than trying to add a separate index structure alongside them.

Timestamps are stored as epoch seconds in the database (seconds since 1970-01-01 UTC), matching the time column described in the . To facilitate querying the database manually, use the dt_2_epoch() function to convert datetime values to epoch seconds and the epoch_2_dt() function to convert epoch seconds back to datetime values. Here is how you can use dt_2_epoch() with the example above:

For more examples, please see the SQL code in that is used to create database tables and associated queries.

is a PostgreSQL extension for time-series data, and AISdb can use it in place of the plain PostgreSQL table layout described above. It is entirely optional. If your PostgreSQL server has the extension installed, opt in when decoding messages by passing timescaledb=True to :

With timescaledb=True, AISdb creates the monthly ais_{YYYYMM}_dynamic and ais_{YYYYMM}_static tables as partitioned on time (and space-partitioned on mmsi), rather than as plain PostgreSQL tables. This is what lets TimescaleDB spread the ingest and query workload for a large, continuously growing AIS collection across many chunks instead of one ever-larger table. The column layout is identical to the plain PostgreSQL schema, so DBQuery, custom SQL, and everything else on this page works the same way regardless of whether TimescaleDB is enabled underneath.

PostgresDBConn also exposes a few maintenance methods that are aware of the timescaledb flag, useful when you are managing indexes or cleaning up a bulk ingest by hand.

Dropping the indexes before a large bulk insert and rebuilding them afterward is significantly faster than maintaining the indexes row by row during the insert. Pass timescaledb=False (the default) for these same methods against a plain PostgreSQL database, which manages indexes named idx_{YYYYMM}_dynamic_mmsi, idx_{YYYYMM}_dynamic_time, idx_{YYYYMM}_dynamic_longitude, and idx_{YYYYMM}_dynamic_latitude instead of the two combined TimescaleDB indexes.

The tutorial walks through decoding raw AIS messages into these tables from scratch, and the tutorial covers DBQuery and TrackGen in more depth than the quick reference above. Reach for the custom SQL approach on this page when you need a query shape those two interfaces do not support directly.

This tutorial will guide you in using the AISdb package to load AIS data into a database and perform queries. We will begin with AISdb installation and environment setup, then proceed to examples of querying the loaded data and creating simple visualizations.

Preparing a Python virtual environment for AISdb is a good practice. It allows you to manage dependencies and prevent conflicts with other projects, ensuring a clean and isolated setup for your work with AISdb. Run these commands in your terminal based on the operating system you are using:

Now you can check your installation by running:

If you're using AISdb in a Notebook, please include the following commands in your notebook cells:

Then, import the required packages:

This section will show you how to efficiently load AIS data into a database.

AISdb includes two database connection approaches:

A common issue with AIS data is noise, where multiple vessels transmit under the same identifier, receivers pick up corrupted or drifting positions, or a single vessel's track jumps in ways no real ship could follow. AISdb ships a dedicated denoising module, , to detect and correct these problems before a track is analyzed or visualized.

The module exposes three functions and one class, each targeting a different kind of noise.

• encode_greatcircledistance() splits a track wherever consecutive pings imply an impossible speed or distance, then reassembles the pieces that most plausibly belong together.

• encode_score()

Track interpolation with AISdb involves generating estimated positions of vessels at specific intervals when actual AIS data points are unavailable. This process is important for filling in gaps in the vessel's trajectory, which can occur due to signal loss, data filtering, or other disruptions.

In this tutorial, we introduce different types of track interpolation implemented in AISdb with usage examples.

Example data preparation

First, we define functions to transform and visualize the track data (a generator object), with options to view the data points or the tracks:

import plotly.graph_objects as go
import plotly.express as px
import pandas as pd

def track2dataframe(tracks):
    data = []
    for track in tracks:
        times = track['time']
        mmsi = track['mmsi']
        lons = track['lon']
        lats = track['lat']
    
        # Iterate over the dynamic arrays and create a row for each time point
        for i in range(len(times)):
            data.append({
                'mmsi': mmsi,
                'time': times[i],
                'longitude': lons[i],
                'latitude': lats[i],
            })
            
    return pd.DataFrame(data)

def plotly_visualize(data, visual_type='lines'):
    if (visual_type=='scatter'):
        # Create a scatter plot for the vessel data points using scatter_geo
        fig = px.scatter_geo(
            data,
            lat="latitude",
            lon="longitude",
            color="mmsi",  # Color by vessel identifier
            hover_name="mmsi",
            hover_data={"time": True},
            title="Vessel Data Points"
        )
    else:
        # Create a line plot for the vessel trajectory using line_geo
        fig = px.line_geo(
            data,
            lat="latitude",
            lon="longitude",
            color="mmsi",  # Color by vessel identifier
            hover_name="mmsi",
            hover_data={"time": True},
            title="Vessel Trajectory"
        )
    
    # Set the map style and projection
    fig.update_geos(
        projection_type="azimuthal equal area",  # Change this to 'natural earth', 'azimuthal equal area', etc.
        showland=True,
        landcolor="rgb(243, 243, 243)",
        countrycolor="rgb(204, 204, 204)",
    )
    
    # Set the layout to focus on a specific area or zoom level
    fig.update_layout(
        geo=dict(
            projection_type="azimuthal equal area",
        ),
        width=1200,  # Increase the width of the plot
        height=800,  # Increase the height of the plot
    )
    
    fig.show()

We will use an actual track retrieved from the database for the examples in this tutorial and interpolate additional data points based on this track. The visualization will show the original track data points:

import aisdb
import numpy as np
import nest_asyncio
from aisdb import DBConn, DBQuery
from datetime import timedelta, datetime

nest_asyncio.apply()
dbpath='YOUR_DATABASE.db' # Define the path to your database

MMSI = 636017611 # MMSI of the vessel

# Set the start and end times for the query
start_time = datetime.strptime("2018-03-10 00:00:00", '%Y-%m-%d %H:%M:%S')
end_time = datetime.strptime("2018-03-31 00:00:00", '%Y-%m-%d %H:%M:%S')

with aisdb.SQLiteDBConn(dbpath=dbpath) as dbconn:
    qry = aisdb.DBQuery(
        dbconn=dbconn, start=start_time, end=end_time, mmsi = MMSI,
        callback=aisdb.database.sqlfcn_callbacks.in_timerange_hasmmsi,
    )
    rowgen = qry.gen_qry()
    tracks = aisdb.track_gen.TrackGen(rowgen, decimate=False)
    
    # Visualize the original track data points
    df = track2dataframe(tracks)
    plotly_visualize(df, 'scatter')

Linear interpolation

Linear interpolation estimates the vessel's position by drawing a straight line between two known points and calculating the positions at intermediate times. It is simple, fast, and straightforward but may not accurately represent complex movements.

With equal time window intervals

This method estimates the position of a vessel at regular time intervals (e.g., every 10 minutes). To perform linear interpolation with an equal time window on the track defined above:

This method estimates the position of a vessel at regular spatial intervals (e.g., every 1 km along its path). To perform linear interpolation with equal distance intervals on the track defined above:

This method estimates the positions of a vessel along a curved path using the principles of geometry, in particular great-circle routes.

Given a set of data points, cubic spline interpolation fits a smooth curve through these points. The curve is represented as a series of cubic polynomials between each pair of data points. Each polynomial ensures a smooth curve at the data points (i.e., the first and second derivatives are continuous).

In addition to the standard interpolation methods provided by AISdb, users can implement other interpolation techniques tailored to their specific analytical needs. For instance, B-spline (Basis Spline) interpolation is a mathematical technique that creates a smooth curve through data points. This smoothness is important in trajectory analysis as it avoids sharp, unrealistic turns and maintains a natural flow.

Here is an implementation and example of using B-spline interpolation:

Then, we can apply the function we just implemented to the vessel track generator:

The visualization of the interpolation is shown below.

Linear interpolation is the right default when speed matters more than geometric precision; it is cheap to compute and good enough for short gaps. For long ocean legs where a straight line would cut across the curvature of the Earth, geodesic interpolation follows the great-circle route instead. Cubic spline interpolation is worth reaching for when the downstream analysis is sensitive to smoothness, such as estimating heading or turn rate, since it avoids the sharp kinks a linear fit produces at each waypoint.

Whichever method is chosen, interpolation invents positions between what the receiver actually reported. Feeding it a noisy or duplicated track will smooth over errors rather than correct them, so denoise the track first.

See for removing bad pings and duplicate reports before interpolating a track.

Data querying with AISdb involves setting up a connection to the database, defining query parameters, creating and executing the query, and processing the results. Following the previous tutorial, Database Loading, we set up a database connection and made simple queries and visualizations. This tutorial will dig into data query functions and parameters and show you the queries you can make with AISdb.

Query functions

Data querying with AISdb involves two components, DBQuery and TrackGen. In this section, we will introduce each component with examples. Before starting data querying, please ensure you have connected to the database. If you have not done so, please follow the instructions and examples in Database Loading or Quick Start.

Query database

The DBQuery class is used to create a query object that specifies the parameters for data retrieval, including the time range, spatial domain, and any filtering callbacks. Here is an example of creating a DBQuery object and using parameters to specify the time range and geographical locations:

import aisdb

# Specify database path
dbpath = 'YOUR_DATABASE.db'

# Specify constraints (optional)
start_time = ...
end_time = ...
domain = ...

with aisdb.SQLiteDBConn(dbpath=dbpath) as dbconn:
    # Create a query object to fetch data within time and geographical range
    qry = aisdb.DBQuery(
        dbconn=dbconn,                   # Database connection object
        start=start_time,                # Start time for the query
        end=end_time,                    # End time for the query
        xmin=domain.boundary['xmin'],    # Minimum longitude of the domain
        xmax=domain.boundary['xmax'],    # Maximum longitude of the domain
        ymin=domain.boundary['ymin'],    # Minimum latitude of the domain
        ymax=domain.boundary['ymax'],    # Maximum latitude of the domain
        callback=aisdb.database.sqlfcn_callbacks.in_time_bbox_validmmsi,  # Callback function to filter data
    )

Callback functions

Callback functions are used in the DBQuery class to filter data based on specific criteria. Some common callbacks include in_validmmsi_bbox, in_time_bbox, in_timerange_validmmsi, and in_time_bbox_validmmsi. These callbacks ensure that the data retrieved matches the specific criteria defined in the query. Please find examples of using different callbacks with other parameters in .

For more callback functions, refer to the API documentation here:

The method of the class runs the query and streams back the matching data. It does not yield one AIS record at a time. Instead, it is a generator that yields a batch of rows for each unique MMSI, sorted by MMSI first and then by time within each batch, fetching results in chunks under the hood so large queries stay memory-efficient. That grouping is exactly what TrackGen expects downstream, since a "track" is just a time-ordered run of positions for one vessel.

The SQL-generating function used internally is controlled by the fcn argument. AISdb ships two of them in aisdb.database.sqlfcn.

• crawl_dynamic iterates only over the position reports table. This is the default.

• crawl_dynamic_static iterates over both the position reports and static message tables, so each row also carries fields such as vessel name and ship type.

After creating the DBQuery object, generate the grouped rows with gen_qry.

Each element of mmsi_rows is a sqlite3.Row (or a dict-like row when querying PostgreSQL) representing one position report. In practice you will rarely iterate gen_qry directly. Pass it straight to TrackGen, which does this grouping work for you and returns ready-to-use track dictionaries.

The class converts the generated rows from gen_qry into tracks (trajectories). It takes the row generator and, optionally, a decimate parameter to control point reduction. This conversion is essential for analyzing vessel movements, identifying patterns, and visualizing trajectories in later steps.

Following the generated rows above, here is how to use the TrackGen class:

The TrackGen class returns a generator object that yields "tracks." While iterating over the tracks, each item is a dictionary representing the track of a specific vessel:

This is the output with our sample data:

In this section, we will provide practical examples of the most common query types you can make using the DBQuery class, including querying within a time range, querying within a geographical area, and tracking vessels by MMSI. Different queries can be achieved by changing the parameter and other parameters defined in the DBQuery class. Then, we will use TrackGen to convert these query results into structured tracks for further analysis and visualization.

First, we need to import the necessary packages and prepare data:

Querying data within a specified time range can be done by using the callback in the DBQuery class:

This will display the queried vessel tracks (within a time range, with a valid MMSI) on the map:

You may find noise in some of the track data. In , we introduced the de-noising methods in AISdb that can effectively remove unreasonable or erroneous data points, ensuring more accurate and reliable vessel trajectories.

In practical scenarios, people may have specific points/areas of interest. DBQuery includes parameters to define a bounding box and has relevant callbacks. Let's look at an example:

This will show all the vessel tracks with valid MMSI in the defined bounding box:

In the above examples, we queried data in a time range and a geographical area. If you want to combine multiple query criteria, please check out available in the API Docs. In the last example above, we can simply modify the callback type to obtain vessel tracks within both the time range and geographical area:

The displayed vessel tracks:

In addition to time and location range, you can track one or more vessels of interest by specifying their MMSIs in the query. Here is an example of tracking several vessels within a time range:

The tracks pulled here still carry the noise inherent to raw AIS, duplicate points, GPS jumps, and implausible speeds among them. See for denoising them before further analysis. Once a track is clean, covers plotting it on a map alongside other vessels and points of interest.

In AISdb, the speed of a vessel is calculated using the aisdb.gis.delta_knots function, which computes the speed over ground (SOG) in knots between consecutive positions within a given track. This calculation matters for the denoising encoder, which compares a vessel's speed against a set threshold to flag implausible jumps in the data.

Vessel speed calculation requires the distance the vessel has traveled between two consecutive positions and the time interval between them. The distance is computed using the haversine distance function (aisdb.gis.delta_meters), and the time interval comes from aisdb.gis.delta_seconds, which takes the difference between consecutive timestamps in a track's time array. The speed is then computed using the formula:

The factor 1.9438445 converts speed from meters per second to knots, the standard speed unit used in maritime contexts. Internally, delta_knots clamps each elapsed-time value to a minimum of one second before dividing, so a duplicate or near-duplicate timestamp in a track can't produce a division by zero or an unrealistically inflated speed.

With the example track we created in , we can calculate the vessel speed between each pair of consecutive positions:

The four values correspond to the four gaps between the five positions in the track. The first three positions are an hour apart and produce speeds around 3.8 knots, consistent with a vessel moving at a leisurely pace. The gap between the fourth and fifth positions spans three hours and covers a much greater distance, which is why the last value jumps to roughly 10.3 knots. This is exactly the kind of signal aisdb.denoising_encoder.remove_pings_wrt_speed relies on when filtering a track. A speed that spikes far above what a vessel of that type could plausibly sustain usually points to a corrupted or duplicated AIS position report rather than real movement.

This tutorial covers the visualization options available for vessel trajectories processed with AISdb, including AISdb's integrated web interface and alternative approaches built on popular Python visualization packages. Each tool comes with a working example, so you can see exactly how to turn queried AISdb tracks into a map.

Internal visualization

AISdb provides an integrated data visualization feature through the aisdb.web_interface.visualize module, which allows users to generate interactive maps displaying vessel tracks. This built-in tool is designed for simplicity and ease of use, offering customizable visualizations directly from AIS data without requiring extensive setup.

Here is an example of using the web interface module to show queried data with colors. To display vessel tracks in a single color:

import aisdb
from datetime import datetime
from aisdb.database.dbconn import SQLiteDBConn
from aisdb import DBConn, DBQuery, DomainFromPoints

import nest_asyncio
nest_asyncio.apply()

dbpath='YOUR_DATABASE.db' # Define the path to your database

# Set the start and end times for the query
start_time = datetime.strptime("2018-01-01 00:00:00", '%Y-%m-%d %H:%M:%S')
end_time = datetime.strptime("2018-01-03 00:00:00", '%Y-%m-%d %H:%M:%S')

# Define a circle with a 100km radius around the location point
domain = DomainFromPoints(points=[(-63.6, 44.6)], radial_distances=[100000]) 

def color_tracks(tracks):
    """ Set the color of each vessel track using a color name or RGB value. """
    for track in tracks:
        track['color'] = 'yellow'
        yield track

with aisdb.SQLiteDBConn(dbpath=dbpath) as dbconn:
    qry = aisdb.DBQuery(
        dbconn=dbconn, start=start_time, end=end_time,
        xmin=domain.boundary['xmin'], xmax=domain.boundary['xmax'],
        ymin=domain.boundary['ymin'], ymax=domain.boundary['ymax'],
        callback=aisdb.database.sqlfcn_callbacks.in_time_bbox_validmmsi,
    )
    rowgen = qry.gen_qry()
    
    tracks = aisdb.track_gen.TrackGen(rowgen, decimate=False)
    colored_tracks = color_tracks(tracks)

    # Visualization
    aisdb.web_interface.visualize(
        colored_tracks,
        domain=domain,
        visualearth=True,
        open_browser=True,
    )

If you want to visualize vessel tracks in different colors based on MMSI, here's an example that demonstrates how to color-code tracks for easy identification:

import random

def color_tracks2(tracks):
    colors = {}
    for track in tracks:
        mmsi = track.get('mmsi')
        if mmsi not in colors:
            # Assign a random color to this MMSI if not already assigned
            colors[mmsi] = "#{:06x}".format(random.randint(0, 0xFFFFFF))
            track['color'] = colors[mmsi] # Set the color for the current track
        yield track


with aisdb.SQLiteDBConn(dbpath=dbpath) as dbconn:
    qry = aisdb.DBQuery(
        dbconn=dbconn, start=start_time, end=end_time,
        xmin=domain.boundary['xmin'], xmax=domain.boundary['xmax'],
        ymin=domain.boundary['ymin'], ymax=domain.boundary['ymax'],
        callback=aisdb.database.sqlfcn_callbacks.in_time_bbox_validmmsi,
    )
    rowgen = qry.gen_qry()
    
    tracks = aisdb.track_gen.TrackGen(rowgen, decimate=False)
    colored_tracks = list(color_tracks2(tracks))

    # Visualization
    aisdb.web_interface.visualize(
        colored_tracks,
        domain=domain,
        visualearth=True,
        open_browser=True,
    )

Alternative visualization

If you need more advanced or specialized visualization, several Python packages pair well with AISdb tracks. Contextily, Basemap, and Cartopy are solid choices for detailed 2D plots, while Plotly gives you interactive, web-based graphs. Kepler.gl is the better fit for large-scale or 3D visualizations. Each package handles the same track data differently, so pick whichever fits how you want to present and explore your AIS data.

Note: mpl_toolkits.basemap uses numpy v1, so downgrade numpy to v1.26.4 to use Basemap, or turn to one of the other alternatives mentioned here, such as Contextily.

Which tool to reach for depends on what you're checking. web_interface.visualize is the fastest way to eyeball a query while you're still iterating on it, since it needs no extra dependencies beyond AISdb itself. Matplotlib with Contextily or Cartopy is the right choice once you need a static figure for a report or paper, where projection control and print quality matter more than interactivity. Kepler.gl is built for the opposite case, large track sets that need to be filtered, layered, and explored interactively rather than viewed once and discarded.

Once tracks are visualized, covers filling gaps between AIS position reports so the tracks you plot are continuous rather than jumping between sparse pings.

Two AIS positions are almost never on a flat plane. A vessel moving between consecutive reports is tracing an arc across a curved Earth, and treating that arc as a straight line introduces error that grows with distance. AISdb solves this with the haversine formula, which computes great-circle distance directly from pairs of latitude/longitude coordinates. The formula itself is implemented in Rust for speed and exposed to Python as aisdb.gis.delta_meters, which calculates the haversine distance in meters between consecutive positions within a vessel track. This is the building block behind several other AISdb calculations, including vessel speed and the denoising encoder, which compares consecutive-position distances against a threshold to help flag noisy AIS pings.

Here is an example of calculating the haversine distance between each pair of consecutive points on a track:

import aisdb
import numpy as np
from aisdb.gis import dt_2_epoch
from datetime import datetime

y1, x1 = 44.57039426840729, -63.52931373766157
y2, x2 = 44.51304767533133, -63.494075674952555
y3, x3 = 44.458038982492134, -63.535634138077945
y4, x4 = 44.393941339104074, -63.53826396955358
y5, x5 = 44.14245580737021, -64.16608964280064

t1 = dt_2_epoch( datetime(2021, 1, 1, 1) )
t2 = dt_2_epoch( datetime(2021, 1, 1, 2) )
t3 = dt_2_epoch( datetime(2021, 1, 1, 3) )
t4 = dt_2_epoch( datetime(2021, 1, 1, 4) )
t5 = dt_2_epoch( datetime(2021, 1, 1, 7) )

# Create a sample track
tracks_short = [
    dict(
        lon=np.array([x1, x2, x3, x4, x5]),
        lat=np.array([y1, y2, y3, y4, y5]),
        time=np.array([t1, t2, t3, t4, t5]),
        mmsi=123456789,
        dynamic=set(['lon', 'lat', 'time']),
        static=set(['mmsi'])
    )
]

# Calculate the Haversine distance
for track in tracks_short:
    print(aisdb.gis.delta_meters(track))

[ 6961.401286 6948.59446128 7130.40147082 57279.94580704]

delta_meters returns one value fewer than the number of positions in the track, because each output is the distance between a position and the one that follows it. The last leg (57,279 meters) is noticeably longer than the first three, which makes sense given the three-hour gap between t4 and t5 in the timestamps above, plenty of time for a vessel to cover more ground.

If we visualize this track on the map, we can observe:

The haversine formula only accounts for horizontal distance across the Earth's surface. When the reference point isn't at sea level, such as a hydrophone, a pipeline, or any other piece of subsea infrastructure, AISdb adds a vertical (depth) component using aisdb.gis.distance3D. It combines the haversine distance with the depth via the Pythagorean theorem, treating the depth as the third leg of a right triangle:

aisdb.gis.vesseltrack_3D_dist applies this calculation across an entire track, appending the result to each position under a new dynamic key (distance_metres by default). Reusing the track from above, here is the distance from each position to a fixed subsea point 150 meters below the surface, near the entrance to Halifax Harbour:

Unlike delta_meters, this returns one value per position rather than one per leg, since each distance is measured from the fixed subsea point rather than between consecutive track positions.

In addition to accessing data stored on the AISdb server, you can download open-source AIS data or import your own datasets for processing and analysis using AISdb. This tutorial walks through the full pipeline for working with your own AIS files, from downloading a raw CSV and loading it into a database, through querying, cleaning, and processing the resulting tracks. We provide two loading examples, Downloading and Processing Individual Files, which demonstrates working with a small data sample and a SQLite database, and Pipeline for Bulk File Downloads and Database Integration, which outlines our approach to handling multiple data file downloads and a PostgreSQL database. From there, the tutorial covers querying your database with DBQuery, cleaning the resulting tracks, and processing them into a usable form.

Data Source

U.S. vessel traffic data across user-defined geographies and periods is available at MarineCadastre. This resource offers comprehensive AIS data that can be accessed for various maritime analysis purposes. We can tailor the dataset based on research needs by selecting specific regions and timeframes.

Downloading and Processing Individual Files

In the following example, we will show how to download and process a single data file and import the data to a newly created SQLite database.

First, download the AIS data for a single day using the curl command:

curl -o ./data/AIS_2020_01_01.zip https://coast.noaa.gov/htdata/CMSP/AISDataHandler/2020/AIS_2020_01_01.zip

Then, extract the downloaded ZIP file to a specific path:

We will look at the columns in the downloaded CSV file.

The required columns for AISdb have specific names and may differ from those in the imported dataset. Therefore, let's define the exact list of columns needed.

Next, we update the column names in the existing dataframe df_ and change the time format as required. The timestamp of an AIS message is represented by BaseDateTime in the default format YYYY-MM-DDTHH:MM:SS. For AISdb, however, the time is represented in UNIX format. We now read the CSV and apply the necessary changes to the date format:

In the code, we can see that we have mapped the column names accordingly. The data type of some columns has also been changed. An nm4 file usually contains raw messages with a Message_ID separating static messages from dynamic ones; however, the MarineCadastre data does not have such an indicator of message type. Thus, adding static messages is necessary for database creation so that a table related to metadata is created.

Let's process the CSV to create an SQLite database using the aisdb package.

A SQLite database has now been created.

If you would rather load the same file into PostgreSQL, connect with PostgresDBConn instead of SQLiteDBConn and pass the same filepaths list to decode_msgs. PostgresDBConn accepts either a set of keyword arguments or a libpq connection string.

The keyword-argument form is equivalent and often easier to keep in a config file or environment variables.

Everything downstream, querying, cleaning, and processing, works identically against a PostgreSQL connection, since DBQuery accepts any SQLiteDBConn or PostgresDBConn object.

Once your file is decoded and sitting in a database, the loading step is done and the rest of the pipeline is the same regardless of where the data came from. Querying uses DBQuery to select rows by time range and location, then TrackGen to reshape those rows into per-vessel track dictionaries. Both classes are covered in more depth in ; here we apply them directly to the SQLite database created above.

in_timerange_validmmsi restricts the query to the given window and drops rows with a malformed MMSI, which is a sensible default when the source data has not been cleaned yet. gen_qry() yields rows sorted by MMSI and time, and TrackGen collapses those rows into one dictionary per vessel, with decimate=True applying linear curve decimation to drop redundant points along straight segments.

Data pulled from a real-world source such as MarineCadastre or your own receiver will contain some amount of noise, duplicate MMSIs, anchored vessels, and the occasional impossible jump in position. AISdb's denoising_encoder module handles this. The tutorial covers the module in detail; a minimal pipeline on the tracks queried above looks like this.

remove_pings_wrt_speed() and encode_greatcircledistance() both accept and return a track generator, so they chain in whatever order suits the noise in your data. Since these are generators, nothing is computed until the tracks are consumed downstream.

With the tracks queried and cleaned, the last step is turning them into something usable, whether that is an interpolated trajectory, a CSV file, or a map. aisdb.interp_time() resamples a track to a fixed time step, which is useful for aligning trajectories to a common temporal grid before further analysis.

To save the processed tracks to disk, aisdb.write_csv() writes each track's column vectors as rows in a CSV file.

Or, to inspect the result visually instead, pass the tracks straight to aisdb.web_interface.visualize(), the same way earlier tutorials do.

That covers the full pipeline for your own AIS files, loading raw messages into a database with decode_msgs, querying them back out with DBQuery and TrackGen, cleaning the result with the denoising_encoder functions, and processing the cleaned tracks into an interpolated trajectory, a CSV export, or a visualization.

This section provides an example of downloading and processing multiple files and loading the data into an AISdb-aligned database. The pipeline is packaged as the noaa-integrator command-line tool, available in this . Each stage is a subcommand; run the stages you need, in order.