Client

The Client class is the main entry point for querying Colombian hydrological station data. On instantiation it downloads the full CNE station catalog from datos.gov.co and stores it as a GeoDataFrame in client.catalog. No API key or authentication is required — both data sources used by the library are publicly accessible.

colombia_hydrodata.client.Client

High-level client for querying and fetching Colombian hydrological station data.

On instantiation the full station catalog is retrieved from the national catalogue (CNE) and stored as a GeoDataFrame. Every row is assigned a Shapely Point geometry derived from the station's longitude and latitude fields, enabling spatial queries directly on the catalog.

Attributes:

Name	Type	Description
catalog	GeoDataFrame	The full station catalog with point geometries attached to each row.

__init__()

Initialises the client by fetching the station catalog and attaching point geometries.

The catalog is retrieved from the CNE endpoint (with caching) and stored as a GeoDataFrame whose geometry column contains Shapely Point objects built from each station's longitude and latitude fields.

stations_in_list(station_ids)

Returns a subset of the catalog containing only the specified station IDs.

Parameters:

Name	Type	Description	Default
station_ids	Sequence[str]	A sequence of station ID strings to look up in the catalog.	required

Returns:

Type	Description
GeoDataFrame	A GeoDataFrame containing only the rows whose id value is
GeoDataFrame	present in station_ids.

stations_in_region(region)

Returns all catalog stations whose geometry falls within a given region.

Parameters:

Name	Type	Description	Default
region	Polygon | MultiPolygon	A Shapely Polygon or MultiPolygon defining the area of interest.	required

Returns:

Type	Description
GeoDataFrame	A GeoDataFrame containing only the stations that lie within
GeoDataFrame	region.

filter_stations(filters=None, subset=None)

Applies attribute-based filters to a station GeoDataFrame.

Each non-None field on the Filters instance is used as an equality constraint against the corresponding column in the DataFrame. All constraints must be satisfied simultaneously (logical AND).

Parameters:

Name	Type	Description	Default
filters	Filters | None	A Filters instance whose non-None fields are used as equality constraints. If None or otherwise falsy, the input DataFrame is returned unchanged.	None
subset	GeoDataFrame | None	The GeoDataFrame to filter. When None, the full self.catalog is used as the source.	None

Returns:

Type	Description
GeoDataFrame	A GeoDataFrame containing only the rows that satisfy every
GeoDataFrame	constraint specified in filters.

fetch_station(station_id)

Fetches full metadata and available variables for a single station.

Parameters:

Name	Type	Description	Default
station_id	str	The unique identifier string of the station to fetch.	required

Returns:

Type	Description
Station	A Station dataclass populated with the station's metadata,
Station	location, hydrographic context, and available measurement
Station	variables.

fetch_stations(station_ids, filters=None)

Fetches full Station objects for a list of station IDs.

The catalog is first narrowed to the requested IDs and then optionally filtered by filters before each matching station is individually fetched.

Parameters:

Name	Type	Description	Default
station_ids	Sequence[str]	A sequence of station ID strings to fetch.	required
filters	Filters | None	An optional Filters instance used to further restrict which stations are returned.	None

Returns:

Type	Description
Sequence[Station]	A sequence of Station objects for every station that passed
Sequence[Station]	all filters.

fetch_region(region, filters=None)

Fetches all stations within a geographic region.

Stations are first narrowed to those that lie within region and then optionally filtered by filters before being individually fetched.

Parameters:

Name	Type	Description	Default
region	Polygon | MultiPolygon	A Shapely Polygon or MultiPolygon defining the area of interest.	required
filters	Filters | None	An optional Filters instance used to further restrict which stations within the region are returned.	None

Returns:

Type	Description
Sequence[Station]	A sequence of Station objects for every station inside
Sequence[Station]	region that also passed all filters.

fetch_bbox(xmin, ymin, xmax, ymax, filters=None)

Fetches all stations within an axis-aligned bounding box.

The bounding box is constructed from the four corner coordinates and converted to a rectangular Polygon before the spatial query is performed.

Parameters:

Name	Type	Description	Default
xmin	float	Western boundary longitude.	required
ymin	float	Southern boundary latitude.	required
xmax	float	Eastern boundary longitude.	required
ymax	float	Northern boundary latitude.	required
filters	Filters | None	An optional Filters instance used to further restrict which stations within the bounding box are returned.	None

Returns:

Type	Description
Sequence[Station]	A sequence of Station objects for every station inside the
Sequence[Station]	bounding box that also passed all filters.

options: show_source: false show_root_heading: true show_symbol_type_heading: true show_symbol_type_toc: true members_order: source