An interface to ArcGIS RESTful-, WFS-, and WMS-based services.
Project description
Package |
Description |
Status |
---|---|---|
Access NWIS, HCDN 2009, NLCD, and SSEBop databases |
||
Send queries to any ArcGIS RESTful-, WMS-, and WFS-based services |
||
Convert responses from PyGeoOGC’s supported web services to datasets |
||
Navigate and subset NHDPlus (MR and HR) using web services |
||
Access topographic data through National Map’s 3DEP web service |
||
Access Daymet for daily climate data both single pixel and gridded |
PyGeoOGC: Query ArcGIS RESTful, WMS, and WFS
🚨 This package is under heavy development and breaking changes are likely to happen. 🚨
Features
PyGeoOGC is a part of Hydrodata software stack and provides interfaces to web services that are based on ArcGIS RESTful, WMS, and WFS. It is noted that although all these web service have limits on the number of objects per requests (e.g., 1000 objectIDs for RESTful and 8 million pixels for WMS), PyGeoOGC divides the requests into smaller chunks under-the-hood and then merges the returned responses.
There is also an inventory of URLs for some of these web services in form of a class called ServiceURL. These URLs are in three categories: ServiceURL().restful, ServiceURL().wms, and ServiceURL().wfs. These URLs provide you with some examples of the services that PyGeoOGC supports. All the URLs are read from a YAML file located here. If you had success using PyGeoOGC with a web service please consider adding its URL to this YAML file which is located at pygeoogc/static/urls.yml.
There are three main classes:
ArcGISRESTful: This class can be instantiated by providing the target layer URL. For example, for getting Watershed Boundary Data we can use ServiceURL().restful.wbd. By looking at the web service website (https://hydro.nationalmap.gov/arcgis/rest/services/wbd/MapServer) we see that there are 9 layers; 1 for 2-digit HU (Region), 6 for 12-digit HU (Subregion), and so on. We can either pass the base URL or concatenate the target layer number like so f"{ServiceURL().restful.wbd}/6".
If you want to change the layer you can simply set the layer property of the class. Afterward, we can request for the data in two steps. First, get the object IDs using oids_bygeom (within a geometry), oids_byfield (specific field IDs), or oids_bysql (any valid SQL 92 WHERE clause) class methods. Second, get the actual data using get_features class method. The returned response can be converted into a GeoDataFrame using json2geodf function from PyGeoOGC package.
WMS: Instantiation of this class requires at least 3 arguments: service URL, layer(s) name(s), and output format. Additionally, target CRS and the web service version can be provided. Upon instantiation, we could use getmap_bybox method class to get the raster data within a bounding box. The box can be any valid CRS and if it is different from the default EPSG:4326, it should be passed to the function using box_crs argumnet. The service response can be converted into a xarray.Dataset using gtiff2xarray function from PyGeoOGC package.
WFS: Instantiation of this class is similar to WMS and the only difference is that only one layer name can be passed. Upon instantiation there are three ways to get the data:
getfeature_bybox: Get all the features within a bounding box in any valid CRS.
getfeature_byid: Get all the features based on the IDs. Note that two arguments should be provided: featurename, and featureids. You can get a list of valid feature names using get_validnames class method.
getfeature_byfilter: Get the data based on a valid CQL filter.
You can convert the returned response to a GeoDataFrame using json2geodf function from PyGeoOGC package.
You can try using PyGeoOGC without installing it on you system by clicking on the binder badge below the PyGeoOGC banner. A Jupyter notebook instance with the Hydrodata software stack pre-installed will be launched in your web browser and you can start coding!
Moreover, requests for additional functionalities can be submitted via issue tracker.
Installation
You can install PyGeoOGC using pip:
$ pip install pygeoogc
Alternatively, PyGeoOGC can be installed from the conda-forge repository using Conda:
$ conda install -c conda-forge pygeoogc
Quick start
We can access NHDPlus HR via RESTful service, National Wetlands Inventory from WMS, and FEMA National Flood Hazard via WFS. The output for these functions are of type requests.Response that can be converted to GeoDataFrame or xarray.Dataset using PyGeoOGC.
Let’s start the National Map’s NHDPlus HR web service. We can query the flowlines that are within a geometry as follows:
from pygeoogc import ArcGISRESTful, WFS, WMS, ServiceURL
import pygeoutils as geoutils
from pynhd import NLDI
basin_geom = NLDI().getfeature_byid(
"nwissite",
"USGS-11092450",
basin=True
).geometry[0]
hr = ArcGISRESTful(ServiceURL().restful.nhdplushr, outformat="json")
hr.layer = 2
hr.oids_bygeom(basin_geom, "epsg:4326")
resp = hr.get_features()
flowlines = geoutils.json2geodf(resp)
Note oids_bygeom has an additional argument for passing any valid SQL WHERE clause to further filter the data on the server side.
We can also submit a query based on IDs of any valid field in the database. If the measure property is desired you can pass return_m as True to the get_features class method:
hr.oids_byfield("NHDPLUSID", [5000500013223, 5000400039708, 5000500004825])
resp = hr.get_features(return_m=True)
flowlines = geoutils.json2geodf(resp)
Additionally, any valid SQL 92 WHERE clause can be used. For more details look here.
hr.oids_bysql("NHDPLUSID IN (5000500013223, 5000400039708, 5000500004825)")
resp = hr.get_features()
flowlines = geoutils.json2geodf(resp)
A WMS-based example is shown below:
wms = WMS(
ServiceURL().wms.fws,
layers="0",
outformat="image/tiff",
crs="epsg:3857",
)
r_dict = wms.getmap_bybox(
basin_geom.bounds,
1e3,
box_crs="epsg:4326",
)
wetlands = geoutils.gtiff2xarray(r_dict, basin_geom, "epsg:4326")
Query from a WFS-based web service can be done either within a bounding box or using any valid CQL filter.
wfs = WFS(
ServiceURL().wfs.fema,
layer="public_NFHL:Base_Flood_Elevations",
outformat="esrigeojson",
crs="epsg:4269",
)
r = wfs.getfeature_bybox(basin_geom.bounds, box_crs="epsg:4326")
flood = geoutils.json2geodf(r.json(), "epsg:4269", "epsg:4326")
layer = "wmadata:huc08"
wfs = WFS(
ServiceURL().wfs.waterdata,
layer=layer,
outformat="application/json",
version="2.0.0",
crs="epsg:4269",
)
r = wfs.getfeature_byfilter(f"huc8 LIKE '13030%'")
huc8 = geoutils.json2geodf(r.json(), "epsg:4269", "epsg:4326")
Contributing
Contributions are appreciated and very welcomed. Please read CONTRIBUTING.rst for instructions.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for pygeoogc-0.2.2-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a9f40af0aa0281884db0ff425293b4ab86be29fd7edd937fb5e96c162e842a37 |
|
MD5 | 57e23c002458626f2d0c121f0c7bc834 |
|
BLAKE2b-256 | d1ab86f17d54d2dd3a32fee4468979e24bebaf179089f5ca5b9b27dff47cc8aa |