Skip to content

57 national map

image image image

Downloading various shapes from the National Map

The national map (TNM) is a catalog of topological datasources maintained by the USGS.

  • It contains a wide range of dataformats (such as GeoTiff, LAZ, ...) and datasets.
  • It provides an endpoint that can be used to search for published datasets and files.
  • This API supports a wide range of searchable parameters (bounding box, polygon, dates, keyword, ...)
  • It returns detailed information regarding the properties of datasets, file,
  • as well as various download links (file, thumbnail, xml descriptions, ...).

We've created a thin wrapper to expose this treasure trove.

  • For more details about TNM, see https://apps.nationalmap.gov/tnmaccess/#/
  • The same data is also downloable using https://apps.nationalmap.gov/downloader/
1
# !pip install leafmap

1
import leafmap

Usage

A class groups the functionalities together.

1
TNM = leafmap.The_national_map_USGS()

Datasets

1
TNM.datasets

Formats

Note that any format (f.e. 'All') is specific to one or more datasets.

1
TNM.prodFormats

Looking for files

1
TNM.find_details().keys(), TNM.find_details()["total"]

A detail

1
TNM.find_details()["items"][0]

Using parameters

1
2
3
4
5
6
7
params = {
    "q": "National Elevation Dataset (NED) 1/3 arc-second",
    "polyCode": "01010002",
    "polyType": "huc8",
}

TNM.find_details(**params)["total"]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
params = {
    "prodFormats": "LAS,LAZ",
    "datasets": "Lidar Point Cloud (LPC)",
    "polygon": [
        (-104.94262695312236, 41.52867510196275),
        (-102.83325195312291, 40.45065268246805),
        (-104.94262695312236, 40.45065268246805),
        (-104.94262695312236, 41.52867510196275),
    ],
}

TNM.find_details(**params)["total"]

Available parameters

1
help(TNM.find_details)

Max items

Defaults to about 50. You only retrieve about 1000 items in one call.

1
len(TNM.find_details()["items"])

1
len(TNM.find_details(max=1000000)["items"])

Use offset to retrieve more batches.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
params = {
    "q": "National Elevation Dataset (NED) 1/3 arc-second",
    "polyCode": "01010002",
    "polyType": "huc8",
    "max": 2,
}

TNM.find_details(**params, offset=0)["items"][0] == TNM.find_details(
    **params, offset=1
)["items"][0]

Select a region from leafmap

1
2
m = leafmap.Map(center=[40, -100], zoom=4)
m

1
2
3
region = m.user_roi_bounds()
if region is None:
    region = [-115.9689, 35.9758, -115.3619, 36.4721]

1
TNM.find_details(q="LAZ", bbox=region)["total"]

Error handling

1
bool(TNM.find_details(start="01-01-2010", q="NED", bbox=region))

1
bool(TNM.find_details(start="2021-12-01", end="2020-01-01", q="NED", bbox=region))

1
bool(TNM.find_details(start="2021-12-01", end="2022-01-01", q="NED", bbox=region))

1
2
3
4
5
6
7
8
9
bool(
    TNM.find_details(
        start="2020-12-01",
        end="2022-01-01",
        q="NED",
        dateType="dateCreated",
        bbox=region,
    )
)

Downloading files

1
help(TNM.download_tiles)

1
2
3
4
5
6
7
8
params = {
    "q": "National Elevation Dataset (NED) 1/3 arc-second",
    "polyCode": "01010002",
    "polyType": "huc8",
    "max": 0,
}

TNM.download_tiles(API=params)

It can also be accessed without invoking the class.

1
2
3
4
5
6
7
8
params = {
    "q": "National Elevation Dataset (NED) 1/3 arc-second",
    "polyCode": "01010002",
    "polyType": "huc8",
    "max": 0,
}

leafmap.download_tnm(API=params)

1
2
3
4
5
region = [-115.9689, 35.9758, -115.3619, 36.4721]

leafmap.download_ned(region=region, return_url=True) == leafmap.download_tnm(
    region=region, return_url=True, API={"q": "NED"}
)

List of files

1
TNM.find_tiles(API=params)

Dataset metadata

1
TNM.datasets_full[0]

Read the docs

1
help(TNM)