57 national map

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/

In [ ]:

# !pip install leafmap

# !pip install leafmap

In [ ]:

import leafmap

import leafmap

Usage¶

A class groups the functionalities together.

In [ ]:

TNM = leafmap.The_national_map_USGS()

TNM = leafmap.The_national_map_USGS()

Datasets¶

In [ ]:

TNM.datasets

TNM.datasets

Formats¶

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

In [ ]:

TNM.prodFormats

TNM.prodFormats

Looking for files¶

In [ ]:

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

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

A detail¶

In [ ]:

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

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

Using parameters¶

In [ ]:

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

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

params = { "q": "National Elevation Dataset (NED) 1/3 arc-second", "polyCode": "01010002", "polyType": "huc8", } TNM.find_details(**params)["total"]

In [ ]:

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"]

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

In [ ]:

help(TNM.find_details)

help(TNM.find_details)

Max items¶

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

In [ ]:

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

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

In [ ]:

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

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

Use offset to retrieve more batches.

In [ ]:

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]

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¶

In [ ]:

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

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

In [ ]:

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

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

In [ ]:

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

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

Error handling¶

In [ ]:

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

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

In [ ]:

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

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

In [ ]:

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

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

In [ ]:

bool(
    TNM.find_details(
        start="2020-12-01",
        end="2022-01-01",
        q="NED",
        dateType="dateCreated",
        bbox=region,
    )
)

bool( TNM.find_details( start="2020-12-01", end="2022-01-01", q="NED", dateType="dateCreated", bbox=region, ) )

Downloading files¶

In [ ]:

help(TNM.download_tiles)

help(TNM.download_tiles)

In [ ]:

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

TNM.download_tiles(API=params)

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.

In [ ]:

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

leafmap.download_tnm(API=params)

params = { "q": "National Elevation Dataset (NED) 1/3 arc-second", "polyCode": "01010002", "polyType": "huc8", "max": 0, } leafmap.download_tnm(API=params)

In [ ]:

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"}
)

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¶

In [ ]:

TNM.find_tiles(API=params)

TNM.find_tiles(API=params)

Dataset metadata¶

In [ ]:

TNM.datasets_full[0]

TNM.datasets_full[0]

Read the docs¶

In [ ]:

help(TNM)

help(TNM)