Developer Interface

Main Interface

resolver.py

The primary client-facing API for resolving spatial geometries to environmental descriptions.

class geoenv.resolver.Resolver(data_source: List[DataSource])[source]

The Resolver class serves as the primary client-facing API for querying environmental data. Clients configure an instance with one or more DataSource objects and use the resolve method to retrieve environment descriptions based on geographic locations.

The results are mapped to a specified semantic resource (default: ENVO) and returned in a structured Response object.

async resolve(geometry: Geometry, semantic_resource: str = 'ENVO', identifier: str = None, description: str = None) → Response[source]

Resolves a given Geometry to one or more environments using the configured data sources. The results are mapped to a semantic resource (e.g., ENVO) and returned as a Response object.

Parameters:

  • geometry – The spatial geometry to resolve.

  • semantic_resource – The semantic resource to use for mapping (default: “ENVO”).

  • identifier – An optional identifier for tracking the resolution request.

  • description – An optional description to annotate the resolution request.

Returns:

A Response object containing the resolved environmental data.

Data Sources

class geoenv.data_sources.WorldTerrestrialEcosystems(grid_size: float = None)[source]

A concrete implementation of DataSource that retrieves terrestrial ecosystem classifications from the World Terrestrial Ecosystems dataset (Sayre 2022).

Note

  • This data source only accepts Point geometries directly. Polygon geometries are supported indirectly via the grid_size property, which enables subsampling of the polygon into representative points. Each point is resolved individually, and the results are aggregated into the final response. By default, Polygon geometries are resolved using the centroid of the polygon.

Further Information
Citation

Sayre, R., 2022, World Terrestrial Ecosystems (WTE) 2020: U.S. Geological Survey data release, https://doi.org/10.5066/P9DO61LP.

property grid_size: float

Retrieves the grid size used for spatial resolution. The size of the grid cells are in the same units as the geometry coordinates.

Note, if a Polygon geometry is provided, this property determines the spacing of the representative points used for subsampling. Each point is resolved individually, and the results are combined in the final response.

Returns:

The grid size as a float.

class geoenv.data_sources.EcologicalCoastalUnits(buffer: float = None)[source]

A concrete implementation of DataSource that retrieves coastal environmental classifications from the Ecological Coastal Units dataset (Sayre 2023).

Note

  • Note, this data source does not accept Point geometries directly. Because coastal units are represented as vector polygons, input geometries must overlap with them for successful resolution. However, Point geometries can be processed by setting the buffer property, which converts them into circular polygons of a given radius (in kilometers). These polygons are then resolved against the dataset, and all overlapping coastal units are returned in the response.

Further Information

  • Spatial Resolution: Global coverage with a resolution of 1 km (or shorter).

  • Coverage: Costal ecosystems worldwide, classified by sinuosity, erodibility, temperature and moisture regime, river discharge, wave height, tidal range, marine physical environment, turbidity, and chlorophyll.

  • Explore the Dataset: https://www.arcgis.com/home/item.html?id= 54df078334954c5ea6d5e1c34eda2c87.

Citation

Sayre, R., 2023, Global Ecological Classification of Coastal Segment Units: U.S. Geological Survey data release, https://doi.org/10.5066/P9HWHSPU.

property buffer: float

Retrieves the buffer distance used for spatial resolution.

Since this data source does not accept Point geometries directly, setting the buffer parameter converts them into circular polygons of a given radius (in kilometers) before resolution. All overlapping coastal units within the buffered area will be included in the response.

Returns:

The buffer radius as a float. Units are in kilometers.

class geoenv.data_sources.EcologicalMarineUnits[source]

A concrete implementation of DataSource that retrieves marine environmental classifications from the Ecological Marine Units dataset (Sayre 2023).

Note

  • This data source supports the resolution of geometries with z values (depth). To retrieve environmental data at different depths, include the z component in the input geometry. No additional property is required.

  • If no z value is specified in the geometry, all vertically stacked environments will be returned. If a z value is included, only the intersecting environment layers at that depth will be returned.

Further Information
Citation

Sayre, R., 2023, Ecological Marine Units (EMUs): U.S. Geological Survey data release, https://doi.org/10.5066/P9Q6ZSGN.

Geometry

geometry.py

class geoenv.geometry.Geometry(geometry: dict)[source]

The Geometry class manages spatial geometries in GeoJSON format and provides utilities for transformation and spatial processing.

Currently, the geometry parameter only supports GeoJSON Point and Polygon types, with plans to support additional types, including GeometryCollection, in the future.

property data: dict

Retrieves the stored geometry data.

Returns:

A dictionary representing the GeoJSON geometry.

geometry_type() → str[source]

Retrieves the type of the stored geometry (e.g., “Point” or “Polygon”).

Returns:

A string representing the geometry type.

is_supported() → bool[source]

Checks if the stored geometry is supported by the resolver. A valid geometry must be a GeoJSON object with a top-level type of either “Point” or “Polygon”.

Returns:

True if the geometry is supported, otherwise False.

point_to_polygon(buffer=None) → dict[source]

Converts a Point geometry into a Polygon by buffering it.

Parameters:

buffer – The buffer distance used to create the polygon (optional).

Returns:

A dictionary representing the buffered polygon in GeoJSON format.

polygon_to_points(grid_size) → list[dict][source]

Converts a Polygon geometry into a set of representative points using grid-based sampling.

Parameters:

grid_size – The size of the grid cells used for sampling.

Returns:

A list of dictionaries representing sampled points in GeoJSON format.

to_esri() → dict[source]

Converts the GeoJSON geometry to an Esri-compatible format.

Returns:

A dictionary representing the Esri-formatted geometry.

Response

response.py

class geoenv.response.Response(data: dict = None)[source]

The Response class structures the results returned by the Resolver into a standardized format. The response follows the GeoJSON format, with resolved environments and their descriptions stored in the properties field.

apply_term_mapping(semantic_resource: str = 'ENVO') → Response[source]

Maps environmental terms in the response data to a specified semantic resource.

Parameters:

semantic_resource – The semantic resource for mapping (default: “ENVO”). Options include: “ENVO”.

Returns:

The updated Response object with mapped terms.

property data: dict

Retrieves the response data.

Returns:

The response data as a dictionary.

read(file_path: str) → Response[source]

Reads response data from a JSON file and updates the object’s data.

Parameters:

file_path – The file path from which to read response data.

Returns:

The updated Response object.

to_schema_org() → dict[source]

Converts the response data to a Schema.org-compliant format.

Returns:

A dictionary formatted according to Schema.org conventions.

write(file_path: str) → None[source]

Writes the response data to a file in JSON format.

Parameters:

file_path – The file path where the response should be saved.

Environment

environment.py

class geoenv.environment.Environment(data: dict = None)[source]

The Environment class represents environmental descriptions retrieved from a DataSource. It provides a structured way to store and manage environmental data.

property data: dict

Retrieves the stored environmental data.

Returns:

A dictionary representing the environmental data.

Utilities

utilities.py

geoenv.utilities.user_agent() → dict[source]

Defines the geoenv user agent for HTTP requests.

Returns:

A dictionary containing the user agent string.

Package Version

geoenv.get_version() → str[source]

Returns the current semantic version of the geoenv package.