pynhd.core ========== .. py:module:: pynhd.core .. autoapi-nested-parse:: Base classes for PyNHD functions. Module Contents --------------- .. py:class:: AGRBase(base_url, layer = None, outfields = '*', crs = 4326, outformat = 'json') Base class for getting geospatial data from a ArcGISRESTful service. :Parameters: * **base_url** (:class:`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** (:class:`str`, *optional*) -- A valid service layer. To see a list of available layers instantiate the class without passing any argument. * **outfields** (:class:`str` or :class:`list`, *optional*) -- Target field name(s), default to "*" i.e., all the fields. * **crs** (:class:`str`, :class:`int`, or :class:`pyproj.CRS`, *optional*) -- Target spatial reference, default to ``EPSG:4326`` * **outformat** (:class:`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``. .. py:method:: 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** (:class:`Polygon` or :class:`tuple`) -- A geometry (Polygon) or bounding box (tuple of length 4). * **geo_crs** (:class:`str`) -- The spatial reference of the input geometry. * **sql_clause** (:class:`str`, *optional*) -- A valid SQL 92 WHERE clause, defaults to an empty string. * **distance** (:class:`int`, *optional*) -- The buffer distance for the input geometries in meters, default to None. * **return_m** (:class:`bool`, *optional*) -- Whether to activate the Return M (measure) in the request, defaults to False. * **return_geom** (:class:`bool`, *optional*) -- Whether to return the geometry of the feature, defaults to ``True``. :returns: :class:`geopandas.GeoDataFrame` -- The requested features as a GeoDataFrame. .. py:method:: byids(field, fids, return_m = False, return_geom = True) Get features based on a list of field IDs. :Parameters: * **field** (:class:`str`) -- Name of the target field that IDs belong to. * **fids** (:class:`str` or :class:`list`) -- A list of target field ID(s). * **return_m** (:class:`bool`) -- Whether to activate the Return M (measure) in the request, defaults to False. * **return_geom** (:class:`bool`, *optional*) -- Whether to return the geometry of the feature, defaults to ``True``. :returns: :class:`geopandas.GeoDataFrame` -- The requested features as a GeoDataFrame. .. py:method:: bysql(sql_clause, return_m = False, return_geom = True) Get feature IDs using a valid SQL 92 WHERE clause. .. rubric:: Notes Not all web services support this type of query. For more details look `here `__ :Parameters: * **sql_clause** (:class:`str`) -- A valid SQL 92 WHERE clause. * **return_m** (:class:`bool`) -- Whether to activate the measure in the request, defaults to False. * **return_geom** (:class:`bool`, *optional*) -- Whether to return the geometry of the feature, defaults to ``True``. :returns: :class:`geopandas.GeoDataFrame` -- The requested features as a GeoDataFrame. .. py:method:: get_validlayers(url) :staticmethod: Get a list of valid layers. :Parameters: **url** (:class:`str`) -- The URL of the ArcGIS REST service. :returns: :class:`dict` -- A dictionary of valid layers. .. py:property:: service_info :type: ServiceInfo Get the service information. .. py:class:: GeoConnex(item = None, dev = False, max_nfeatures = 10000) Access to the GeoConnex API. .. rubric:: 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** (:class:`bool`, *optional*) -- Whether to use the development endpoint, defaults to ``False``. * **max_nfeatures** (:class:`int`, *optional*) -- The maximum number of features to request from the service, defaults to 10000. .. py:method:: 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. .. rubric:: 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, :meth:`.bygeometry`. :Parameters: * **cql_dict** (:class:`dict`) -- A valid CQL dictionary (non-spatial queries). * **skip_geometry** (:class:`bool`, *optional*) -- If ``True``, no geometry will not be returned, by default ``False``. :returns: :class:`geopandas.GeoDataFrame` -- The query result as a ``geopandas.GeoDataFrame``. .. py:method:: 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** (:class:`Polygon` or :class:`tuple` of :class:`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** (:class:`Polygon` or :class:`tuple` of :class:`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** (:class:`str`, *optional*) -- The predicate to use, by default ``intersects``. Supported predicates are ``intersects``, ``within``, ``contains``, ``overlaps``, ``crosses``, ``disjoint``, ``touches``, and ``equals``. * **crs** (:class:`int` or :class:`str` or :class:`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** (:class:`bool`, *optional*) -- If ``True``, no geometry will not be returned. :returns: :class:`geopandas.GeoDataFrame` -- The query result as a ``geopandas.GeoDataFrame``. .. py:method:: 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. .. py:property:: dev :type: bool Return the name of the endpoint. .. py:property:: item :type: str | None Return the name of the endpoint. .. py:class:: ScienceBase Access and explore items on USGS's ScienceBase. .. py:method:: get_children(item) :staticmethod: Get children items of an item. .. py:method:: get_file_urls(item) :staticmethod: Get download and meta URLs of all the available files for an item.