pynhd.core#

Base classes for PyNHD functions.

Module Contents#

class pynhd.core.AGRBase(base_url, layer=None, outfields='*', crs=4326, outformat='json')#

Base class for getting geospatial data from a ArcGISRESTful service.

Parameters:

  • base_url (str, optional) – The ArcGIS RESTful service url. The URL must either include a layer number after the last / in the url or the target layer must be passed as an argument.

  • layer (str, optional) – A valid service layer. To see a list of available layers instantiate the class without passing any argument.

  • outfields (str or list, optional) – Target field name(s), default to “*” i.e., all the fields.

  • crs (str, int, or pyproj.CRS, optional) – Target spatial reference, default to EPSG:4326

  • outformat (str, optional) – One of the output formats offered by the selected layer. If not correct a list of available formats is shown, defaults to json.

property service_info: ServiceInfo#

Get the service information.

bygeom(geom, geo_crs=4326, sql_clause='', distance=None, return_m=False, return_geom=True)#

Get feature within a geometry that can be combined with a SQL where clause.

Parameters:

  • geom (Polygon or tuple) – A geometry (Polygon) or bounding box (tuple of length 4).

  • geo_crs (str) – The spatial reference of the input geometry.

  • sql_clause (str, optional) – A valid SQL 92 WHERE clause, defaults to an empty string.

  • distance (int, optional) – The buffer distance for the input geometries in meters, default to None.

  • return_m (bool, optional) – Whether to activate the Return M (measure) in the request, defaults to False.

  • return_geom (bool, optional) – Whether to return the geometry of the feature, defaults to True.

Returns:

geopandas.GeoDataFrame – The requested features as a GeoDataFrame.

Return type:

geopandas.GeoDataFrame

byids(field, fids, return_m=False, return_geom=True)#

Get features based on a list of field IDs.

Parameters:

  • field (str) – Name of the target field that IDs belong to.

  • fids (str or list) – A list of target field ID(s).

  • return_m (bool) – Whether to activate the Return M (measure) in the request, defaults to False.

  • return_geom (bool, optional) – Whether to return the geometry of the feature, defaults to True.

Returns:

geopandas.GeoDataFrame – The requested features as a GeoDataFrame.

Return type:

geopandas.GeoDataFrame

bysql(sql_clause, return_m=False, return_geom=True)#

Get feature IDs using a valid SQL 92 WHERE clause.

Notes

Not all web services support this type of query. For more details look here

Parameters:

  • sql_clause (str) – A valid SQL 92 WHERE clause.

  • return_m (bool) – Whether to activate the measure in the request, defaults to False.

  • return_geom (bool, optional) – Whether to return the geometry of the feature, defaults to True.

Returns:

geopandas.GeoDataFrame – The requested features as a GeoDataFrame.

Return type:

geopandas.GeoDataFrame

static get_validlayers(url)#

Get a list of valid layers.

Parameters:

url (str) – The URL of the ArcGIS REST service.

Returns:

dict – A dictionary of valid layers.

Return type:

dict[str, int]

class pynhd.core.GeoConnex(item=None, dev=False, max_nfeatures=10000)#

Access to the GeoConnex API.

Notes

The geometry field of the query can be a Polygon, MultiPolygon, or tuple/list of length 4 (bbox) in EPSG:4326 CRS. They should be within the extent of the GeoConnex endpoint.

Parameters:

  • The item (service endpoint) to query. Valid endpoints are –

    • hu02 for Two-digit Hydrologic Regions

    • hu04 for Four-digit Hydrologic Subregion

    • hu06 for Six-digit Hydrologic Basins

    • hu08 for Eight-digit Hydrologic Subbasins

    • hu10 for Ten-digit Watersheds

    • nat_aq for National Aquifers of the United States from

      USGS National Water Information System National Aquifer code list.

    • principal_aq for Principal Aquifers of the United States from

      2003 USGS data release

    • sec_hydrg_reg for Secondary Hydrogeologic Regions of the

      Conterminous United States from 2018 USGS data release

    • gages for US Reference Stream Gauge Monitoring Locations

    • mainstems for US Reference Mainstem Rivers

    • states for U.S. States

    • counties for U.S. Counties

    • aiannh for Native American Lands

    • cbsa for U.S. Metropolitan and Micropolitan Statistical Areas

    • ua10 for Urbanized Areas and Urban Clusters (2010 Census)

    • places for U.S. legally incororated and Census designated places

    • pws for U.S. Public Water Systems

    • dams for US Reference Dams

  • dev (bool, optional) – Whether to use the development endpoint, defaults to False.

  • max_nfeatures (int, optional) – The maximum number of features to request from the service, defaults to 10000.

property dev: bool#

Return the name of the endpoint.

property item: str | None#

Return the name of the endpoint.

bycql(cql_dict: dict[str, Any], skip_geometry: Literal[False] = False) → geopandas.GeoDataFrame#
bycql(cql_dict: dict[str, Any], skip_geometry: Literal[True]) → pandas.DataFrame

Query the GeoConnex endpoint.

Notes

GeoConnex only supports simple CQL queries. For more information and examples visit https://portal.ogc.org/files/96288#simple-cql-JSON. Use this for non-spatial queries, since there’s a dedicated method for spatial queries, bygeometry().

Parameters:

  • cql_dict (dict) – A valid CQL dictionary (non-spatial queries).

  • skip_geometry (bool, optional) – If True, no geometry will not be returned, by default False.

Returns:

geopandas.GeoDataFrame – The query result as a geopandas.GeoDataFrame.

bygeometry(geometry1: GTYPE, geometry2: GTYPE | None = None, predicate: str = 'intersects', crs: CRSTYPE | None = 4326, skip_geometry: Literal[False] = False) → geopandas.GeoDataFrame#
bygeometry(geometry1: GTYPE, geometry2: GTYPE | None = None, predicate: str = 'intersects', crs: CRSTYPE | None = 4326, skip_geometry: Literal[True] = True) → pandas.DataFrame

Query the GeoConnex endpoint by geometry.

Parameters:

  • geometry1 (Polygon or tuple of float) – The first geometry or bounding boxes to query. A bounding box is a tuple of length 4 in the form of (xmin, ymin, xmax, ymax). For example, an spatial query for a single geometry would be INTERSECTS(geom, geometry1).

  • geometry2 (Polygon or tuple of float, optional) – The second geometry or bounding boxes to query. A bounding box is a tuple of length 4 in the form of (xmin, ymin, xmax, ymax). Default is None. For example, an spatial query for a two geometries would be CROSSES(geometry1, geometry2).

  • predicate (str, optional) – The predicate to use, by default intersects. Supported predicates are intersects, within, contains, overlaps, crosses, disjoint, touches, and equals.

  • crs (int or str or pyproj.CRS, optional) – The CRS of the polygon, by default EPSG:4326. If the input is a geopandas.GeoDataFrame or geopandas.GeoSeries, this argument will be ignored.

  • skip_geometry (bool, optional) – If True, no geometry will not be returned.

Returns:

geopandas.GeoDataFrame – The query result as a geopandas.GeoDataFrame.

byid(feature_name: str, feature_ids: list[str] | str, skip_geometry: Literal[False] = False) → geopandas.GeoDataFrame#
byid(feature_name: str, feature_ids: list[str] | str, skip_geometry: Literal[True]) → pandas.DataFrame

Query the GeoConnex endpoint.

class pynhd.core.ScienceBase#

Access and explore items on USGS’s ScienceBase.

static get_children(item)#

Get children items of an item.

static get_file_urls(item)#

Get download and meta URLs of all the available files for an item.