AISdb Tutorials is a collection of runnable Jupyter notebooks with worked examples for the AISdb workflow, walking through the full pipeline from decoding raw AIS messages into a database through querying, cleaning, interpolation, calculations, visualization, and export. Each notebook runs against a bundled SQLite sample database, so no external data downloads are needed to follow along. The tutorials are developed and maintained by the MAPS Lab at Dalhousie University, continuing work that began under the MERIDIAN initiative.
The notebooks require the aisdb package and a Jupyter environment. Install both from PyPI.
pip install aisdb jupyterThe numbered notebooks build on each other and are best read in order. Notebook 0 stands alone and tours the whole pipeline in one sitting.
| # | Notebook | What it teaches |
|---|---|---|
| 0 | 0-quick-start.ipynb | End-to-end tour of the full AISdb pipeline against the sample database |
| 1 | 1-database-loading.ipynb | Decoding raw AIS messages into a SQLite database (and the PostgreSQL equivalent) |
| 2 | 2-data-querying.ipynb | Querying with DBQuery and building vessel tracks with TrackGen |
| 3 | 3-data-cleaning.ipynb | Denoising shared MMSIs, corrupted positions, and impossible jumps with denoising_encoder |
| 4 | 4-data-visualization.ipynb | Mapping AIS tracks with AISdb's web_interface and common Python plotting packages |
| 5 | 5-track-interpolation.ipynb | Filling gaps in vessel tracks with linear, great-circle, and spline interpolation |
| 6 | 6-calculations.ipynb | Great-circle distance, speed, and distance-from-shore calculations with aisdb.gis |
| 7 | 7-using-your-ais-data.ipynb | Turning your own raw AIS files (here, a NOAA daily archive) into queryable tracks |
| 8 | 8-export-data-to-csv.ipynb | Exporting decoded AIS tracks to CSV with aisdb.write_csv and a custom writer |
| 9 | 9-bathymetric-data.ipynb | Merging GEBCO bathymetry depth onto AIS tracks with webdata.bathymetry.Gebco |
Clone this repository and launch Jupyter from the clone so the notebooks can find example_data.db next to them.
git clone git@github.com:MAPS-Lab/AISdb-Tutorials.git
cd AISdb-Tutorials
jupyter lab # or: jupyter notebookThe notebooks also run on Google Colab. Upload the notebook you want together with example_data.db, then add a pip install aisdb cell at the top before running.
example_data.db is a bundled SQLite sample database built with AISdb. It covers vessel traffic in the Gulf of Maine during January 2022 (roughly 54 vessels), small enough to query and plot instantly while still exercising every feature the notebooks demonstrate.
Docs · Tutorials · API reference · Website
- AISdb, the core Python/Rust platform for storing, querying, and analyzing AIS data
- AISdb-lite, a lightweight AISdb variant built on PostGIS and TimescaleDB hypertables
- NOAA-Integrator, an acquisition pipeline from NOAA Marine Cadastre into AISdb-aligned databases
If you use AISdb Tutorials in your work, please cite it. Citation metadata lives in CITATION.cff, and the BibTeX entry follows.
@software{AISdbTutorials2026:GSpadon,
author = {Spadon, Gabriel},
title = {AISdb Tutorials},
year = {2026},
publisher = {MAPS Lab, Dalhousie University},
url = {https://github.com/MAPS-Lab/AISdb-Tutorials},
license = {AGPL-3.0}
}This project is distributed under the terms of the GNU Affero General Public License v3.0 (AGPL-3.0). See LICENSE for details.