Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

NOAA’s National Bathymetric Source builds and publishes the best available high-resolution bathymetric data of U.S. waters. The program’s workflow is designed for continuous throughput, ensuring the best bathymetric data is always available to professionals and the public. This data provides depth measurements nationwide, along with vertical uncertainty estimates and information on the originating survey source. It is available in multiple formats (GeoTIFF compilations like BlueTopo and Modeling, BAG, and IHO S-102) hosted on a public S3 bucket.

This package simplifies downloading bathymetric data from NOAA and optionally assembling them into per-UTM-zone GDAL Virtual Rasters for use in GIS applications. It supports six data sources (BlueTopo, Modeling, BAG, S-102 v2.1/v2.2/v3.0).

Note: The S-102 data available through this package are for test and evaluation and should not be used for navigation. For official S-102 data, see the data available from Precision Marine Navigation.

Who this package is for

This package gives you a straightforward way to get high-resolution bathymetric data from NOAA’s National Bathymetric Source.

Point the package at your area of interest and it handles discovery, download, checksum verification, and optional mosaic assembly, ready to open in QGIS, ArcGIS, or any GDAL-compatible tool.

Common use cases include:

  • Hydrographic surveying and chart production. Access the latest compiled depths and survey source metadata.
  • Coastal and ocean modeling. Pull seamless bathymetry grids as input to storm surge, tsunami, or circulation models.
  • Marine construction and engineering. Get site-specific depth data for port design, cable routing, or dredging planning.
  • Environmental and habitat research. Combine bathymetry with other datasets to study benthic environments.
  • Education and exploration. Visualize the seafloor for teaching, outreach, or personal curiosity.

Documentation

  • User Guide — the fetch-then-build workflow, what gets created on disk, and resolution filtering.
  • Data Sources — each data source with its file format, bands, and GDAL requirements.
  • API Reference — complete reference for the Python API and CLI commands.
  • Browser UI App — a standalone UI app built on this python package.
  • About NBS — background on NOAA’s National Bathymetric Source.
  • Troubleshooting — common errors and how to fix them.
  • Quickstart Helper — draw your area of interest on a map and generate usage examples.

Installation

Install conda if you haven’t already: conda installation

Create an environment with the required packages:

conda create -n noaabathymetry_env -c conda-forge 'gdal>=3.9'
conda activate noaabathymetry_env
pip install noaabathymetry

Note: The libgdal-hdf5 package is required for BAG and S-102 data sources. If you only need BlueTopo or Modeling data, gdal>=3.4 alone is sufficient.

Quick start

After installation, you have access to a Python API and a CLI. You can use fetch for downloading tiles and mosaic for assembling them together.

See the Python API and CLI sections below to get started. You can also use the Quickstart Helper to draw your area of interest on a map and generate usage examples.

Python API

from nbs.noaabathymetry import fetch_tiles, mosaic_tiles

result = fetch_tiles('/path/to/project', geometry='area_of_interest.gpkg')
mosaic_result = mosaic_tiles('/path/to/project')

Both functions return structured result objects (FetchResult, MosaicResult) you can inspect:

result = fetch_tiles('/path/to/project', geometry='area_of_interest.gpkg')
print(f"Downloaded: {len(result.downloaded)}")
print(f"Failed: {len(result.failed)}")
print(f"Not found: {len(result.not_found)}")
print(f"Already up to date: {len(result.existing)}")

mosaic_result = mosaic_tiles('/path/to/project')
print(f"Built {len(mosaic_result.built)} UTM zone mosaics")
print(f"Skipped {len(mosaic_result.skipped)} already up-to-date zones")

CLI

The same workflow is available from the command line:

nbs fetch -d /path/to/project -g area_of_interest.gpkg
nbs mosaic -d /path/to/project

Geometry formats

The geometry parameter accepts four formats. File inputs use the CRS defined in the file. All other formats assume EPSG:4326 (WGS 84).

File — any GDAL-compatible vector file (shapefile, geopackage, GeoJSON file, etc.):

result = fetch_tiles('/path/to/project', geometry='/path/to/area_of_interest.gpkg')

Bounding box — xmin,ymin,xmax,ymax as longitude/latitude:

result = fetch_tiles('/path/to/project', geometry='-76.1,36.9,-75.9,37.1')

WKT — Well-Known Text geometry:

result = fetch_tiles('/path/to/project', geometry='POLYGON((-76.1 36.9, -75.9 36.9, -75.9 37.1, -76.1 37.1, -76.1 36.9))')

GeoJSON — geometry or Feature object:

result = fetch_tiles('/path/to/project', geometry='{"type":"Polygon","coordinates":[[[-76.1,36.9],[-75.9,36.9],[-75.9,37.1],[-76.1,37.1],[-76.1,36.9]]]}')

Other data sources

You can specify any S3-hosted source by name with the data_source parameter:

result = fetch_tiles('/path/to/project', geometry='aoi.gpkg', data_source='bag')
mosaic_result = mosaic_tiles('/path/to/project', data_source='bag')

nbs fetch -d /path/to/project -g aoi.gpkg -s modeling
nbs mosaic -d /path/to/project -s modeling

See Data Sources for details on all available sources.