pynhd.pygeoapi#

Access NLDI and WaterData databases.

Module Contents#

class pynhd.pygeoapi.PyGeoAPI#

Access PyGeoAPI service.

cross_section(coord, width, numpts, crs=4326)#

Return a GeoDataFrame from the xsatpoint service.

Parameters:

  • coord (tuple) – The coordinate of the point to extract the cross-section as a tuple,e.g., (lon, lat).

  • width (float) – The width of the cross-section in meters.

  • numpts (int) – The number of points to extract the cross-section from the DEM.

  • crs (str, int, or pyproj.CRS, optional) – The coordinate reference system of the coordinates, defaults to EPSG:4326.

Returns:

geopandas.GeoDataFrame – A GeoDataFrame containing the cross-section at the requested point.

Return type:

geopandas.GeoDataFrame

Examples

>>> from pynhd import PyGeoAPI
>>> pga = PyGeoAPI()
>>> gdf = pga.cross_section((-103.80119, 40.2684), width=1000.0, numpts=101, crs=4326)  
>>> print(gdf.iloc[-1, 1])  
1000.0
elevation_profile(line, numpts, dem_res, crs=4326)#

Return a GeoDataFrame from the xsatpathpts service.

Parameters:

  • line (shapely.LineString or shapely.MultiLineString) – The line to extract the elevation profile for.

  • numpts (int) – The number of points to extract the elevation profile from the DEM.

  • dem_res (int) – The target resolution for requesting the DEM from 3DEP service.

  • crs (str, int, or pyproj.CRS, optional) – The coordinate reference system of the coordinates, defaults to EPSG:4326.

Returns:

geopandas.GeoDataFrame – A GeoDataFrame containing the elevation profile along the requested endpoints.

Return type:

geopandas.GeoDataFrame

Examples

>>> from pynhd import PyGeoAPI
>>> from shapely import LineString
>>> pga = PyGeoAPI()
>>> line = LineString([(-103.801086, 40.26772), (-103.80097, 40.270568)])
>>> gdf = pga.elevation_profile(line, 101, 1, 4326)  
>>> print(gdf.iloc[-1, 2])  
1299.8727
endpoints_profile(coords, numpts, dem_res, crs=4326)#

Return a GeoDataFrame from the xsatendpts service.

Parameters:

  • coords (list) – A list of two coordinates to trace as a list of tuples, e.g., [(x1, y1), (x2, y2)].

  • numpts (int) – The number of points to extract the elevation profile from the DEM.

  • dem_res (int) – The target resolution for requesting the DEM from 3DEP service.

  • crs (str, int, or pyproj.CRS, optional) – The coordinate reference system of the coordinates, defaults to EPSG:4326.

Returns:

geopandas.GeoDataFrame – A GeoDataFrame containing the elevation profile along the requested endpoints.

Return type:

geopandas.GeoDataFrame

Examples

>>> from pynhd import PyGeoAPI
>>> pga = PyGeoAPI()
>>> gdf = pga.endpoints_profile(
...     [(-103.801086, 40.26772), (-103.80097, 40.270568)], numpts=101, dem_res=1, crs=4326
... )  
>>> print(gdf.iloc[-1, 1])  
411.5906
flow_trace(coord, crs=4326, direction='none')#

Return a GeoDataFrame from the flowtrace service.

Parameters:

  • coord (tuple) – The coordinate of the point to trace as a tuple,e.g., (lon, lat).

  • crs (str) – The coordinate reference system of the coordinates, defaults to EPSG:4326.

  • direction (str, optional) – The direction of flowpaths, either down, up, or none. Defaults to none.

Returns:

geopandas.GeoDataFrame – A GeoDataFrame containing the traced flowline.

Return type:

geopandas.GeoDataFrame

Examples

>>> from pynhd import PyGeoAPI
>>> pga = PyGeoAPI()
>>> gdf = pga.flow_trace(
...     (1774209.63, 856381.68), crs="ESRI:102003", direction="none"
... )  
>>> print(gdf.comid.iloc[0])  
22294818
split_catchment(coord, crs=4326, upstream=False)#

Return a GeoDataFrame from the splitcatchment service.

Parameters:

  • coord (tuple) – The coordinate of the point to trace as a tuple,e.g., (lon, lat).

  • crs (str, int, or pyproj.CRS, optional) – The coordinate reference system of the coordinates, defaults to EPSG:4326.

  • upstream (bool, optional) – If True, return all upstream catchments rather than just the local catchment, defaults to False.

Returns:

geopandas.GeoDataFrame – A GeoDataFrame containing the local catchment or the entire upstream catchments.

Return type:

geopandas.GeoDataFrame

Examples

>>> from pynhd import PyGeoAPI
>>> pga = PyGeoAPI()
>>> gdf = pga.split_catchment((-73.82705, 43.29139), crs=4326, upstream=False)  
>>> print(gdf.catchmentID.iloc[0])  
22294818
pynhd.pygeoapi.pygeoapi(geodf, service)#

Return a GeoDataFrame from the flowtrace service.

Parameters:

  • geodf (geopandas.GeoDataFrame) – A GeoDataFrame containing geometries to query. The required columns for each service are:

    • flow_trace: direction that indicates the direction of the flow trace. It can be up, down, or none (both directions).

    • split_catchment: upstream that indicates whether to return all upstream catchments or just the local catchment.

    • elevation_profile: numpts that indicates the number of points to extract along the flowpath and 3dep_res that indicates the target resolution for requesting the DEM from 3DEP service.

    • endpoints_profile: numpts that indicates the number of points to extract along the flowpath and 3dep_res that indicates the target resolution for requesting the DEM from 3DEP service.

    • cross_section: numpts that indicates the number of points to extract along the flowpath and width that indicates the width of the cross-section in meters.

  • service (str) – The service to query, can be flow_trace, split_catchment, elevation_profile, endpoints_profile, or cross_section.

Returns:

geopandas.GeoDataFrame – A GeoDataFrame containing the results of requested service.

Return type:

geopandas.GeoDataFrame

Examples

>>> from shapely import Point
>>> import geopandas as gpd
>>> gdf = gpd.GeoDataFrame(
...     {
...         "direction": [
...             "none",
...         ]
...     },
...     geometry=[Point((1774209.63, 856381.68))],
...     crs="ESRI:102003",
... )
>>> trace = nhd.pygeoapi(gdf, "flow_trace")
>>> print(trace.comid.iloc[0])
22294818