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 Basinc CQL2 queries. For more information and examples visit this link. 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: GeoType, geometry2: GeoType | None = ..., predicate: str = ..., crs: CRSType = ..., skip_geometry: Literal[False] = False) → geopandas.GeoDataFrame

bygeometry(geometry1: GeoType, geometry2: GeoType | 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, equals, disjoint, touches, within, overlaps, crosses and contains.

• 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.

Parameters:

• feature_name (str) – The name of the feature to query.

• feature_ids (list or str) – The IDs of the feature to query.

• 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 or a pandas.DataFrame.

byitem(item_id)

Query the GeoConnex endpoint by an item ID.

Parameters:

item_id (str) – The ID of the item to query. Note that this GeoConnex’s item ID which is not necessarily the same as the provider’s item ID. For example, for querying gages, the item ID is not the same as the USGS gage ID but for querying HUC02, the item ID is the same as the HUC02 ID.

Returns:

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

Return type:

geopandas.GeoDataFrame

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.