georest.usgs.nationalmap

Clients for The National Map: point elevations and product downloads.

Two USGS services behind The National Map:

  • the Elevation Point Query Service (EPQS), which returns the 3DEP elevation at any point in the US, from the best data available there (down to 1 meter lidar-derived models where they exist);

  • TNM Access, the catalog of downloadable National Map products: 3DEP elevation models and lidar, US Topo maps, NAIP imagery, hydrography, boundaries, structures and more, each with a direct download link.

from georest.usgs import nationalmap

nationalmap.elevation(-105.75, 40.62)              # meters, e.g. 3149.6
tiles = nationalmap.find_products(
    (-105.8, 40.6, -105.7, 40.7), "Digital Elevation Model (DEM) 1 meter")
tiles[["title", "size_mb", "download_url"]]

Tables come back as pandas DataFrames.

Copyright 2026 Ryan Rock and Ian Housman

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

Functions

elevation(lon, lat, *[, units])

The 3DEP elevation at a point.

elevations(points, *[, units])

The 3DEP elevation at each of several points.

find_products(bbox, dataset, *[, formats, ...])

Downloadable National Map products covering an area.

list_datasets()

The National Map products you can search with find_products().
georest.usgs.nationalmap.elevation(lon: float, lat: float, *, units: str = 'meters') → float | None[source]

The 3DEP elevation at a point.

Parameters:

  • lon – The point, in decimal degrees.

  • lat – The point, in decimal degrees.

  • units – "meters" (the default) or "feet".

Returns:

The elevation, or None where there is no data, such as over the open ocean. (EPQS reports that case as “Call failed” rather than as an error, so it is not raised.) Coverage reaches past US borders into parts of Canada and Mexico.

Example:

from georest.usgs import nationalmap

nationalmap.elevation(-105.75, 40.62)                  # meters
nationalmap.elevation(-105.75, 40.62, units="feet")
georest.usgs.nationalmap.elevations(points: Iterable[tuple[float, float]], *, units: str = 'meters') → Any[source]

The 3DEP elevation at each of several points.

EPQS answers one point per request, so this makes one request per point.

Parameters:

  • points – (lon, lat) pairs in decimal degrees.

  • units – "meters" (the default) or "feet".

Returns:

pandas.DataFrame with lon, lat, elevation (empty where there is no data), resolution_m (the resolution of the source data at that point) and acquired (when that data was collected).

Example:

from georest.usgs import nationalmap

# A transect across the Continental Divide at Rocky Mountain National Park
transect = [(-105.90 + i * 0.05, 40.40) for i in range(7)]
nationalmap.elevations(transect, units="feet")
georest.usgs.nationalmap.list_datasets() → Any[source]

The National Map products you can search with find_products().

Returns:

dataset (the exact name to pass to find_products()), title, category (the group it belongs to), extents (tile sizes) and info_url.

Return type:

pandas.DataFrame, one row per product type

Example:

from georest.usgs import nationalmap

datasets = nationalmap.list_datasets()
datasets[datasets["category"].str.contains("Elevation")]
georest.usgs.nationalmap.find_products(bbox: tuple[float, float, float, float] | str, dataset: str, *, formats: str | Iterable[str] | None = None, start: str | None = None, end: str | None = None) → Any[source]

Downloadable National Map products covering an area.

Every matching product is returned; TNM Access pages are followed.

Parameters:

  • bbox – (west, south, east, north) in decimal degrees.

  • dataset – The product type, exactly as list_datasets() gives it in its dataset column, e.g. "Digital Elevation Model (DEM) 1 meter" or "National Elevation Dataset (NED) 1/3 arc-second".

  • formats – Keep only these formats, e.g. "GeoTIFF" or ["LAS", "LAZ"].

  • start – Publication date range, "YYYY-MM-DD".

  • end – Publication date range, "YYYY-MM-DD".

Returns:

title, dataset, format, size_mb, publication_date, its bounding box (west, south, east, north), download_url, metadata_url and source_id.

Return type:

pandas.DataFrame, one row per product

Example:

from georest.usgs import nationalmap

# 1 meter lidar-derived elevation tiles over part of Rocky Mountain National Park
tiles = nationalmap.find_products((-105.8, 40.3, -105.6, 40.4),
                                  "Digital Elevation Model (DEM) 1 meter")
tiles[["title", "publication_date", "size_mb", "download_url"]]