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.

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]

property service_info: ServiceInfo#

Get the service information.

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.

bybox(bbox, skip_geometry=False)#

Query the GeoConnex endpoint by bounding box.

Parameters:

bbox (tuple) – A bounding box in the form of (xmin, ymin, xmax, ymax), in EPSG:4326 CRS, i.e., decimal degrees.
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.

Return type:

geopandas.GeoDataFrame | pandas.DataFrame

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.

byfilter(filter_str, skip_geometry=False)#

Query the GeoConnex endpoint.

Notes

GeoConnex only supports simple CQL queries. For more information and examples visit https://portal.ogc.org/files/96288

Parameters:

filter_str (dict) – A valid filter string. The filter string shouldn’t be long since a GET request is used.
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.

Return type:

geopandas.GeoDataFrame | pandas.DataFrame

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

bygeometry(geometry1: GTYPE, geometry2: GTYPE | None = ..., predicate: str = ..., crs: CRSTYPE = ..., 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.

property dev: bool#

Return the name of the endpoint.

property item: str | None#

Return the name of the 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.