pygeoogc.pygeoogc#

Base classes and function for REST, WMS, and WMF services.

Module Contents#

class pygeoogc.pygeoogc.ArcGISRESTful(base_url, layer=None, outformat='geojson', outfields='*', crs=4326, max_workers=1, verbose=False, disable_retry=False)#

Access to an ArcGIS REST service.

Notes

By default, all retrieval methods retry to get the missing feature IDs, if there are any. You can disable this behavior by setting disable_retry to True. If there are any missing feature IDs after the retry, they are saved to a text file, ipath of which can be accessed by self.client.failed_path.

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 (int, optional) – Target layer number, defaults to None. If None layer number must be included as after the last / in base_url.
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 geojson.
outfields (str or list) – The output fields to be requested. Setting * as outfields requests all the available fields which is the default behaviour.
crs (str, int, or pyproj.CRS, optional) – The spatial reference of the output data, defaults to epsg:4326.
max_workers (int, optional) – Number of simultaneous download, default to 1, i.e., no threading. Note that some services might face issues when several requests are sent simultaneously and will return the requests partially. It’s recommended to avoid using too many workers unless you are certain the web service can handle it.
verbose (bool, optional) – If True, prints information about the requests and responses, defaults to False.
disable_retry (bool, optional) – If True in case there are any failed queries, no retrying attempts is done and object IDs of the failed requests is saved to a text file which its ipath can be accessed via self.client.failed_path.

get_features(featureids, return_m=False, return_geom=True)#

Get features based on the feature IDs.

Parameters:

featureids (list) – List of feature IDs.
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:

dict – (Geo)json response from the web service.

Return type:

list[dict[str, Any]]

oids_byfield(field, ids)#

Get Object IDs based on a list of field IDs.

Parameters:

field (str) – Name of the target field that IDs belong to.
ids (str or list) – A list of target ID(s).

Returns:

list of tuples – A list of feature IDs partitioned by self.max_nrecords.

Return type:

Iterator[tuple[str, Ellipsis]]

oids_bygeom(geom, geo_crs=4326, spatial_relation='esriSpatialRelIntersects', sql_clause=None, distance=None)#

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

Parameters:

geom (LineString, Polygon, Point, MultiPoint, tuple, or list of tuples) – A geometry (LineString, Polygon, Point, MultiPoint), tuple of length two ((x, y)), a list of tuples of length 2 ([(x, y), ...]), or bounding box (tuple of length 4 ((xmin, ymin, xmax, ymax))).
geo_crs (str, int, or pyproj.CRS, optional) – The spatial reference of the input geometry, defaults to epsg:4326.
spatial_relation (str, optional) – The spatial relationship to be applied on the input geometry while performing the query. If not correct a list of available options is shown. It defaults to esriSpatialRelIntersects. Valid predicates are:
- esriSpatialRelIntersects
- esriSpatialRelContains
- esriSpatialRelCrosses
- esriSpatialRelEnvelopeIntersects
- esriSpatialRelIndexIntersects
- esriSpatialRelOverlaps
- esriSpatialRelTouches
- esriSpatialRelWithin
- esriSpatialRelRelation
sql_clause (str, optional) – Valid SQL 92 WHERE clause, default to None.
distance (int, optional) – Buffer distance in meters for the input geometries, default to None.

Returns:

list of tuples – A list of feature IDs partitioned by self.max_nrecords.

Return type:

Iterator[tuple[str, Ellipsis]]

oids_bysql(sql_clause)#

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.
Returns:: list of tuples – A list of feature IDs partitioned by self.max_nrecords.
Return type:: Iterator[tuple[str, Ellipsis]]

partition_oids(oids)#

Partition feature IDs based on self.max_nrecords.

Parameters:: oids (list of int or int) – A list of feature ID(s).
Returns:: list of tuples – A list of feature IDs partitioned by self.max_nrecords.
Return type:: Iterator[tuple[str, Ellipsis]]

class pygeoogc.pygeoogc.HttpURLs#: URLs of the supported HTTP services.

class pygeoogc.pygeoogc.RESTfulURLs#: URLs of the supported RESTful services.

class pygeoogc.pygeoogc.ServiceURL#: URLs of the supported services.

class pygeoogc.pygeoogc.WFS(url, layer=None, outformat=None, version='2.0.0', crs=4326, read_method='json', max_nrecords=1000, validation=True)#

Data from any WFS service within a geometry or by featureid.

Parameters:

url (str) – The base url for the WFS service, for examples: https://hazards.fema.gov/nfhl/services/public/NFHL/MapServer/WFSServer
layer (str) – The layer from the service to be downloaded, defaults to None which throws an error and includes all the available layers offered by the service.
outformat (str) –

The data format to request for data from the service, defaults to None which
throws an error and includes all the available format offered by the service.
version (str, optional) – The WFS service version which should be either 1.0.0, 1.1.0, or 2.0.0. Defaults to 2.0.0.
crs (str, int, or pyproj.CRS, optional) – The spatial reference system to be used for requesting the data, defaults to epsg:4326.
read_method (str, optional) – Method for reading the retrieved data, defaults to json. Valid options are json, binary, and text.
max_nrecords (int, optional) – The maximum number of records in a single request to be retrieved from the service, defaults to 1000. If the number of records requested is greater than this value, it will be split into multiple requests.
validation (bool, optional) – Validate the input arguments from the WFS service, defaults to True. Set this to False if you are sure all the WFS settings such as layer and crs are correct to avoid sending extra requests.

getfeature_bybox(bbox, box_crs=4326, always_xy=False, sort_attr=None)#

Get data from a WFS service within a bounding box.

Parameters:

bbox (tuple) – A bounding box for getting the data: [west, south, east, north]
box_crs (str, or pyproj.CRS, optional) – The spatial reference system of the input bbox, defaults to epsg:4326.
always_xy (bool, optional) – Whether to always use xy axis order, defaults to False. Some services change the axis order from xy to yx, following the latest WFS version specifications but some don’t. If the returned value does not have any geometry, it indicates that most probably the axis order does not match. You can set this to True in that case.
sort_attr (str, optional) – The column name in the database to sort request by, defaults to the first attribute in the schema that contains id in its name.

Returns:

list of str or bytes or dict – WFS query response within a bounding box.

Return type:

RESPONSE

getfeature_byfilter(cql_filter, method='GET', sort_attr=None)#

Get features based on a valid CQL filter.

Notes

The validity of the input CQL expression is user’s responsibility since the function does not perform any checks and just sends a request using the input filter.

Parameters:

cql_filter (str) – A valid CQL filter expression.
method (str) – The request method, could be GET or POST (for long filters).
sort_attr (str, optional) – The column name in the database to sort request by, defaults to the first attribute in the schema that contains id in its name.

Returns:

str or bytes or dict – WFS query response

Return type:

RESPONSE

getfeature_bygeom(geometry, geo_crs=4326, always_xy=False, predicate='INTERSECTS', sort_attr=None)#

Get features based on a geometry.

Parameters:

geometry (shapely.Polygon or shapely.MultiPolygon) – The input geometry
geo_crs (str, or pyproj.CRS, optional) – The CRS of the input geometry, default to epsg:4326.
always_xy (bool, optional) – Whether to always use xy axis order, defaults to False. Some services change the axis order from xy to yx, following the latest WFS version specifications but some don’t. If the returned value does not have any geometry, it indicates that most probably the axis order does not match. You can set this to True in that case.
predicate (str, optional) – The geometric predicate to use for requesting the data, defaults to INTERSECTS. Valid predicates are:
- EQUALS
- DISJOINT
- INTERSECTS
- TOUCHES
- CROSSES
- WITHIN
- CONTAINS
- OVERLAPS
- RELATE
- BEYOND
sort_attr (str, optional) – The column name in the database to sort request by, defaults to the first attribute in the schema that contains id in its name.

Returns:

str or bytes or dict – WFS query response based on the given geometry.

Return type:

RESPONSE

getfeature_byid(featurename, featureids)#

Get features based on feature IDs.

Parameters:

featurename (str) – The name of the column for searching for feature IDs.
featureids (int, str, or list of them) – The feature ID(s).

Returns:

str or bytes or dict – WMS query response.

Return type:

RESPONSE

class pygeoogc.pygeoogc.WFSURLs#: URLs of the supported WFS services.

class pygeoogc.pygeoogc.WMS(url, layers, outformat, version='1.3.0', crs=4326, validation=True, ssl=True)#

Get data from a WMS service within a geometry or bounding box.

Parameters:

url (str) – The base url for the WMS service e.g., https://www.mrlc.gov/geoserver/mrlc_download/wms
layers (str or list) – A layer or a list of layers from the service to be downloaded. You can pass an empty string to get a list of available layers.
outformat (str) – The data format to request for data from the service. You can pass an empty string to get a list of available output formats.
crs (str, int, or pyproj.CRS, optional) – The spatial reference system to be used for requesting the data, defaults to epsg:4326.
version (str, optional) – The WMS service version which should be either 1.1.1 or 1.3.0, defaults to 1.3.0.
validation (bool, optional) – Validate the input arguments from the WMS service, defaults to True. Set this to False if you are sure all the WMS settings such as layer and crs are correct to avoid sending extra requests.
ssl (bool, optional) – Whether to use SSL for the connection, defaults to True.

get_validlayers()#

Get the layers supported by the WMS service.

getmap_bybox(bbox: tuple[float, float, float, float], resolution: float, box_crs: CRSTYPE = ..., always_xy: bool = ..., max_px: int = ..., kwargs: dict[str, Any] | None = ..., tiff_dir: Literal[None] = None) → dict[str, bytes]#

getmap_bybox(bbox: tuple[float, float, float, float], resolution: float, box_crs: CRSTYPE = ..., always_xy: bool = ..., max_px: int = ..., kwargs: dict[str, Any] | None = ..., tiff_dir: str | pathlib.Path = ...) → list[pathlib.Path]

Get data from a WMS service within a geometry or bounding box.

Parameters:

bbox (tuple) – A bounding box for getting the data.
resolution (float) – The output resolution in meters. The width and height of output are computed in pixel based on the geometry bounds and the given resolution.
box_crs (str, int, or pyproj.CRS, optional) – The spatial reference system of the input bbox, defaults to epsg:4326.
always_xy (bool, optional) – Whether to always use xy axis order, defaults to False. Some services change the axis order from xy to yx, following the latest WFS version specifications but some don’t. If the returned value does not have any geometry, it indicates that most probably the axis order does not match. You can set this to True in that case.
max_px (int, optional) – The maximum allowable number of pixels (width x height) for a WMS requests, defaults to 8 million based on some trial-and-error.
kwargs (dict, optional) – Optional additional keywords passed as payload, defaults to None. For example, {"styles": "default"}.
tiff_dir (str or pathlib.Path, optional) – If given, the retrieved data will be stored on disk instead of returning it, defaults to None, i.e., saving to memory and returning the data.

Returns:

dict of bytes or list of pathlib.Path – If to_disk=False, a dict where the keys are the layer name and values are the returned response from the WMS service as bytes. If to_disk=True, a list of pathlib.Path objects to the saved files.

class pygeoogc.pygeoogc.WMSURLs#: URLs of the supported WMS services.