Groundwater Levels API#

The groundwater levels API provides access to both observed measurements from monitoring stations and modeled predictions. This page documents both the client interfaces and the data models used for groundwater level data.

Overview#

The levels API is accessed through client.levels and provides two main sub-clients:

Observed: Real measurements from groundwater monitoring stations
Modeled: Predicted groundwater levels from the SGU-HYPE model

Quick Example:

from sgu_client import SGUClient

client = SGUClient()

# get observed data
stations = client.levels.observed.get_stations(
    bbox=[12.0, 55.0, 16.0, 58.0],
    limit=50
)
measurements = client.levels.observed.get_measurements_by_names(
    [station.properties.station_id for station in stations.features],
    datetime="2023-01-01/2024-01-01",
    limit=1000
)
df_meas = measurements.to_dataframe()

# get modeled data
areas = client.levels.modeled.get_areas(
   bbox=[12.0, 55.0, 16.0, 58.0],
   limit=10
)
predictions = client.levels.modeled.get_levels_by_areas(
   [area.properties.area_id for area in areas.features],
   limit=100
)
df_pred = predictions.to_dataframe()

Observed Groundwater Levels#

Client Interface#

The ObservedGroundwaterLevelClient provides methods to query monitoring stations and retrieve measurements.

Key Methods:

get_stations() - Retrieve groundwater monitoring stations
get_station_by_name() - Find a specific station by name
get_stations_by_names() - Find multiple stations by names
get_measurements_by_name() - Get measurements for a specific station
get_measurements_by_names() - Get measurements for multiple stations

Filtering Options:

bbox: Spatial filter (bounding box)
datetime: Temporal filter (ISO 8601 datetime or interval)
filter: CQL filter expression for advanced queries
limit: Maximum number of results to return

Observed groundwater level client endpoints.

class sgu_client.client.levels.observed.ObservedGroundwaterLevelClient(base_client)[source]#

Bases: object

Client for observed groundwater level-related SGU API endpoints.

Parameters:: base_client (BaseClient)

BASE_PATH = 'collections'#

__init__(base_client)[source]#

Initialize observed groundwater level client.

Parameters:: base_client (BaseClient) – Base HTTP client instance

get_stations(bbox=None, datetime=None, limit=None, filter_expr=None, sortby=None, **kwargs)[source]#

Get groundwater monitoring stations.

Parameters:

bbox (list[float] | None) – Bounding box as [min_lon, min_lat, max_lon, max_lat]
datetime (str | None) – Date/time filter (RFC 3339 format or interval)
limit (int | None) – Maximum number of features to return (automatically paginated if needed)
filter_expr (str | None) – CQL filter expression
sortby (list[str] | None) – List of sort expressions (e.g., [‘+name’, ‘-date’])
**kwargs (Any) – Additional query parameters

Return type:

GroundwaterStationCollection

Returns:

Typed collection of groundwater monitoring stations

Example

>>> from sgu_client import SGUClient
>>> client = SGUClient()
>>>
>>> # get stations in southern Sweden
>>> stations = client.levels.observed.get_stations(
...     bbox=[12.0, 55.0, 16.0, 58.0]
... )
>>>
>>> # filter stations by municipality using CQL
>>> stations = client.levels.observed.get_stations(
...     filter_expr="kommun='Uppsala' AND akvifer='JS'"
... )

get_station(station_id)[source]#

Get a specific groundwater monitoring station by ID. This endpoint is provided by the OGC API but likely not used by any user.

Parameters:: station_id (str) – Station identifier
Return type:: GroundwaterStation
Returns:: Typed groundwater monitoring station
Raises:: ValueError – If station not found or multiple stations returned

get_measurements(bbox=None, datetime=None, limit=None, filter_expr=None, sortby=None, **kwargs)[source]#

Get groundwater level measurements. This method is used internally by convenience functions like `get_measurements_by_name() by constructing filter expressions. A user may also do this, but readability is greater when using the built-in convenience functions.

Parameters:

bbox (list[float] | None) – Bounding box as [min_lon, min_lat, max_lon, max_lat]
datetime (str | None) – Date/time filter (RFC 3339 format or interval)
limit (int | None) – Maximum number of features to return (automatically paginated if needed)
filter_expr (str | None) – CQL filter expression
sortby (list[str] | None) – List of sort expressions (e.g., [‘+date’, ‘-value’])
**kwargs (Any) – Additional query parameters

Return type:

GroundwaterMeasurementCollection

Returns:

Typed collection of groundwater level measurements

get_measurement(measurement_id)[source]#

Get a specific groundwater level measurement by ID. This endpoint is provided by the OGGC API but likely not used by any user.

Parameters:: measurement_id (str) – Measurement identifier
Return type:: GroundwaterMeasurement
Returns:: Typed groundwater level measurement
Raises:: ValueError – If measurement not found or multiple measurements returned

get_station_by_name(station_id=None, station_name=None, **kwargs)[source]#

Convenience function to get a station by name (‘station_id’ or ‘station_name’).

Parameters:

station_id (str | None) – Station identifier (maps to ‘platsbeteckning’ in API)
station_name (str | None) – Station name (maps to ‘obsplatsnamn’ in API)
**kwargs (Any) – Additional query parameters (e.g., limit)

Return type:

GroundwaterStation

Returns:

Typed groundwater monitoring station

Raises:

ValueError – If neither parameter is provided, both are provided, or if multiple stations are found

Example

>>> from sgu_client import SGUClient
>>> client = SGUClient()
>>>
>>> # find station by platsbeteckning (recommended)
>>> station = client.levels.observed.get_station_by_name(station_id="95_2")
>>>
>>> # find station by obsplatsnamn
>>> station = client.levels.observed.get_station_by_name(
...     station_name="Lagga_2"
... )
>>> print(station.properties.aquifer_description)

get_stations_by_names(station_id=None, station_name=None, **kwargs)[source]#

Convenience function to get multiple stations by name (‘station_id’ or ‘station_name’).

Parameters:

station_id (list[str] | None) – List of station identifiers (maps to ‘platsbeteckning’ in API)
station_name (list[str] | None) – List of station names (maps to ‘obsplatsnamn’ in API)
**kwargs (Any) – Additional query parameters (e.g., limit)

Return type:

GroundwaterStationCollection

Returns:

Typed collection of groundwater monitoring stations

Raises:

ValueError – If neither parameter is provided or both are provided

Example

>>> from sgu_client import SGUClient
>>> client = SGUClient()
>>>
>>> # get multiple stations by their IDs
>>> stations = client.levels.observed.get_stations_by_names(
...     station_id=["95_2", "101_1", "102_3"]
... )
>>> for station in stations.features:
...     print(f"{station.properties.station_id}: {station.properties.aquifer_code}")

get_measurements_by_name(station_id=None, station_name=None, tmin=None, tmax=None, limit=None, **kwargs)[source]#

Get measurements for a specific station by name with optional time filtering.

Parameters:

station_id (str | None) – Station identifier (maps to ‘platsbeteckning’ in API)
station_name (str | None) – Station name (maps to ‘obsplatsnamn’ in API)
tmin (str | datetime | None) – Start time (ISO string or datetime object)
tmax (str | datetime | None) – End time (ISO string or datetime object)
limit (int | None) – Maximum number of measurements to return
**kwargs (Any) – Additional query parameters

Return type:

GroundwaterMeasurementCollection

Returns:

Typed collection of groundwater level measurements

Raises:

ValueError – If neither or both name parameters are provided, or if station lookup fails

Example

>>> from sgu_client import SGUClient
>>> from datetime import datetime, timezone
>>> client = SGUClient()
>>>
>>> # get all measurements for a station
>>> measurements = client.levels.observed.get_measurements_by_name(
...     station_id="95_2",
...     limit=100
... )
>>>
>>> # get measurements with time filtering
>>> measurements = client.levels.observed.get_measurements_by_name(
...     station_id="95_2",
...     tmin=datetime(2020, 1, 1, tzinfo=timezone.utc),
...     tmax=datetime(2021, 1, 1, tzinfo=timezone.utc)
... )
>>>
>>> # using ISO string for time filtering
>>> measurements = client.levels.observed.get_measurements_by_name(
...     station_id="95_2",
...     tmin="2020-01-01T00:00:00Z",
...     tmax="2021-01-01T00:00:00Z"
... )

get_measurements_by_names(station_id=None, station_name=None, tmin=None, tmax=None, limit=None, **kwargs)[source]#

Get measurements for multiple stations by name with optional time filtering.

Parameters:

station_id (list[str] | None) – List of station identifiers (maps to ‘platsbeteckning’ in API)
station_name (list[str] | None) – List of station names (maps to ‘obsplatsnamn’ in API)
tmin (str | datetime | None) – Start time (ISO string or datetime object)
tmax (str | datetime | None) – End time (ISO string or datetime object)
limit (int | None) – Maximum number of measurements to return
**kwargs (Any) – Additional query parameters

Return type:

GroundwaterMeasurementCollection

Returns:

Typed collection of groundwater level measurements

Raises:

ValueError – If neither or both name parameters are provided, or if station lookup fails

Example

>>> from sgu_client import SGUClient
>>> client = SGUClient()
>>>
>>> # get measurements for multiple stations
>>> measurements = client.levels.observed.get_measurements_by_names(
...     station_id=["95_2", "101_1"],
...     tmin="2020-01-01T00:00:00Z",
...     tmax="2021-01-01T00:00:00Z",
...     limit=1000
... )
>>> print(f"Found {len(measurements.features)} measurements")

Data Models#

Pydantic models for groundwater data from SGU API.

class sgu_client.models.observed.GroundwaterStationProperties(**data)[source]#

Bases: SGUBaseModel

Properties for a groundwater monitoring station.

Parameters:: data (Any)

row_id: int#

station_id: str | None#

station_name: str | None#

sample_site_id: str | None#

active_since: str | None#

active_until: str | None#

reference_level: float | None#

elevation_method: str | None#

elevation_system: str | None#

well_height: float | None#

well_length: float | None#

aquifer_code: str | None#

aquifer_description: str | None#

soil_code: str | None#

soil_description: str | None#

soil_genesis_code: str | None#

soil_genesis_description: str | None#

overlying_soil_code: str | None#

overlying_soil_description: str | None#

soil_depth: float | None#

soil_depth_qualifier: str | None#

inner_diameter: float | None#

well_material_code: str | None#

well_material_description: str | None#

borehole_completion: float | None#

screen_length: float | None#

hydrogeological_setting_code: str | None#

hydrogeological_setting_description: str | None#

municipality_code: str | None#

municipality: str | None#

county_code: str | None#

county: str | None#

eu_groundwater_body: str | None#

north_coordinate: float | None#

east_coordinate: float | None#

aquifer_symbol: str | None#

impact_symbol: str | None#

station_remark: str | None#

comments: str | None#

model_config: ClassVar[ConfigDict] = {'extra': 'allow', 'use_enum_values': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class sgu_client.models.observed.GroundwaterStation(**data)[source]#

Bases: SGUBaseModel

A groundwater monitoring station (GeoJSON Feature).

Parameters:: data (Any)

type: Literal['Feature']#

id: str#

geometry: Point | MultiPoint | LineString | Polygon | MultiPolygon#

properties: GroundwaterStationProperties#

model_config: ClassVar[ConfigDict] = {'extra': 'allow', 'use_enum_values': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class sgu_client.models.observed.GroundwaterMeasurementProperties(**data)[source]#

Bases: SGUBaseModel

Properties for a groundwater level measurement.

Parameters:: data (Any)

row_id: int#

station_id: str | None#

observation_date: str | None#

water_level_below_ground_m: float | None#

water_level_masl_m: float | None#

water_level_below_surface_m: float | None#

measurement_method: str | None#

level_remark: str | None#

last_updated: str | None#

property observation_datetime: datetime | None#: Parse observation date as datetime object.

property last_updated_datetime: datetime | None#: Parse last update as datetime object.

model_config: ClassVar[ConfigDict] = {'extra': 'allow', 'use_enum_values': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class sgu_client.models.observed.GroundwaterMeasurement(**data)[source]#

Bases: SGUBaseModel

A groundwater level measurement (GeoJSON Feature).

Parameters:: data (Any)

type: Literal['Feature']#

id: str#

geometry: Point | MultiPoint | LineString | Polygon | MultiPolygon | None#

properties: GroundwaterMeasurementProperties#

model_config: ClassVar[ConfigDict] = {'extra': 'allow', 'use_enum_values': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class sgu_client.models.observed.GroundwaterStationCollection(**data)[source]#

Bases: SGUResponse

Collection of groundwater monitoring stations (GeoJSON FeatureCollection).

Parameters:: data (Any)

type: Literal['FeatureCollection']#

features: list[GroundwaterStation]#

totalFeatures: int | None#

numberMatched: int | None#

numberReturned: int | None#

timeStamp: str | None#

links: list[Link] | None#

crs: CRS | None#

to_dataframe(**kwargs) → pd.DataFrame#

Convert to pandas DataFrame with flattened station properties.

Returns:: DataFrame containing station data with geometry columns.

Examples

>>> from sgu_client import SGUClient
>>> client = SGUClient()
>>> stations = client.levels.observed.get_stations(limit=10)
>>> df = stations.to_dataframe()
>>>
>>> # dataFrame includes flattened properties and geometry coordinates
>>> print(df.columns)  # station_id, longitude, latitude, station_name, municipality, etc.
>>> print(df[['station_id', 'station_name', 'municipality', 'longitude', 'latitude']].head())

model_config: ClassVar[ConfigDict] = {'extra': 'allow', 'use_enum_values': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class sgu_client.models.observed.GroundwaterMeasurementCollection(**data)[source]#

Bases: SGUResponse

Collection of groundwater level measurements (GeoJSON FeatureCollection).

Parameters:: data (Any)

type: Literal['FeatureCollection']#

features: list[GroundwaterMeasurement]#

totalFeatures: int | None#

numberMatched: int | None#

numberReturned: int | None#

timeStamp: str | None#

links: list[Link] | None#

crs: CRS | None#

to_dataframe(**kwargs) → pd.DataFrame#

Convert to pandas DataFrame with measurement data.

Args: sort_by_date: Whether to sort the DataFrame by observation date.
Returns: DataFrame containing measurement data.

Examples

>>> from sgu_client import SGUClient
>>> client = SGUClient()
>>> measurements = client.levels.observed.get_measurements(limit=100)
>>> df = measurements.to_dataframe()
>>>
>>> # dataFrame is sorted by observation_date by default
>>> print(df[['observation_date', 'water_level_masl_m', 'station_id']].head())

to_series(**kwargs) → pd.Series#

Convert to pandas Series with measurement data.

Parameters:

index – Column name to use as index. If None, observation_date is used.
data – Column name to use as data. If None, water_level_masl_m is used.
sort_by_date – Whether to sort the data by observation date before creating the Series.

Returns:

Series containing measurement data.

Examples

>>> from sgu_client import SGUClient
>>> client = SGUClient()
>>> measurements = client.levels.observed.get_measurements_by_name(
...     platsbeteckning="95_2", limit=100
... )
>>>
>>> # create time series with default columns (observation_date, water_level_masl_m)
>>> series = measurements.to_series()
>>> print(series.head())
>>>
>>> # use custom columns for index and data
>>> series_custom = measurements.to_series(
...     index="observation_date",
...     data="water_level_below_ground_m"
... )

model_config: ClassVar[ConfigDict] = {'extra': 'allow', 'use_enum_values': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Modeled Groundwater Levels#

Client Interface#

The ModeledGroundwaterLevelClient provides access to predicted groundwater levels from hydrological models.

Key Methods:

get_area()
get_areas()
get_levels_by_area()
get_levels_by_areas()
get_levels_by_coords()

Modeled groundwater level client endpoints.

class sgu_client.client.levels.modeled.ModeledGroundwaterLevelClient(base_client)[source]#

Bases: object

Client for modeled groundwater level-related SGU API endpoints.

Parameters:: base_client (BaseClient)

BASE_PATH = 'collections'#

MODELED_BASE_URL = 'https://api.sgu.se/oppnadata/grundvattennivaer-sgu-hype-omraden/ogc/features/v1/'#

__init__(base_client)[source]#

Initialize modeled groundwater level client.

Parameters:: base_client (BaseClient) – Base HTTP client instance

get_areas(bbox=None, limit=None, filter_expr=None, sortby=None, **kwargs)[source]#

Get modeled groundwater areas.

Parameters:

bbox (list[float] | None) – Bounding box as [min_lon, min_lat, max_lon, max_lat]
limit (int | None) – Maximum number of features to return (automatically paginated if needed)
filter_expr (str | None) – CQL filter expression
sortby (list[str] | None) – List of sort expressions (e.g., [‘+omrade_id’] - use Swedish field names for API)
**kwargs (Any) – Additional query parameters

Return type:

ModeledAreaCollection

Returns:

Typed collection of modeled groundwater areas

Example

>>> from sgu_client import SGUClient
>>> client = SGUClient()
>>>
>>> # get all modeled areas
>>> areas = client.levels.modeled.get_areas(limit=100)
>>>
>>> # get areas in a specific region
>>> areas = client.levels.modeled.get_areas(
...     bbox=[15.0, 58.0, 17.0, 60.0]
... )
>>> for area in areas.features:
...     print(f"area: {area.properties.area_id}")

get_area(area_id)[source]#

Get a specific modeled groundwater area by ID. This endpoint is provided by OGC API but not likely used by any user.

Parameters:: area_id (str) – Area identifier
Return type:: ModeledArea
Returns:: Typed modeled groundwater area
Raises:: ValueError – If area not found or multiple areas returned

get_levels(bbox=None, datetime=None, limit=None, filter_expr=None, sortby=None, **kwargs)[source]#

Get modeled groundwater levels.

Parameters:

bbox (list[float] | None) – Bounding box as [min_lon, min_lat, max_lon, max_lat]
datetime (str | None) – Date/time filter (RFC 3339 format or interval)
limit (int | None) – Maximum number of features to return (automatically paginated if needed)
filter_expr (str | None) – CQL filter expression
sortby (list[str] | None) – List of sort expressions (e.g., [‘+datum’, ‘-omrade_id’] - use Swedish field names for API)
**kwargs (Any) – Additional query parameters

Return type:

ModeledGroundwaterLevelCollection

Returns:

Typed collection of modeled groundwater levels

Example

>>> from sgu_client import SGUClient
>>> client = SGUClient()
>>>
>>> # get modeled levels
>>> levels = client.levels.modeled.get_levels(limit=100)
>>>
>>> # get levels for a specific time period
>>> levels = client.levels.modeled.get_levels(
...     datetime="2023-01-01/2024-01-01",
...     limit=1000
... )

get_level(level_id)[source]#

Get a specific modeled groundwater level by ID. This endpoint is provided by the OGC API but not likely used by any user.

Parameters:: level_id (str) – Level identifier
Return type:: ModeledGroundwaterLevel
Returns:: Typed modeled groundwater level
Raises:: ValueError – If level not found or multiple levels returned

get_levels_by_area(area_id, **kwargs)[source]#

Get modeled groundwater levels for a specific area.

Parameters:

area_id (int) – Area ID to filter by
**kwargs (Any) – Additional query parameters (limit, datetime, bbox, etc.)

Return type:

ModeledGroundwaterLevelCollection

Returns:

Typed collection of modeled groundwater levels for the specified area

Example

>>> from sgu_client import SGUClient
>>> client = SGUClient()
>>>
>>> # get all modeled levels for a specific area
>>> levels = client.levels.modeled.get_levels_by_area(
...     area_id=30125,
...     limit=500
... )
>>>
>>> # with time filtering
>>> levels = client.levels.modeled.get_levels_by_area(
...     area_id=30125,
...     datetime="2023-01-01/2024-01-01"
... )

get_levels_by_areas(area_ids, **kwargs)[source]#

Get modeled groundwater levels for multiple areas.

Parameters:

area_ids (list[int]) – List of area IDs to filter by
**kwargs (Any) – Additional query parameters (limit, datetime, bbox, etc.)

Return type:

ModeledGroundwaterLevelCollection

Returns:

Typed collection of modeled groundwater levels for the specified areas

Example

>>> from sgu_client import SGUClient
>>> client = SGUClient()
>>> levels = client.levels.modeled.get_levels_by_areas(
...     area_ids=[30125, 30126],
...     datetime="2024-09-31/2025-10-01"
... )
>>> print(f"Found {len(levels.features)} modeled levels")

get_levels_by_coords(lat, lon, buffer=0.01, **kwargs)[source]#

Get modeled groundwater levels for a specific coordinate.

This convenience function first finds relevant areas containing or near the specified coordinates, then retrieves modeled levels for those areas.

Parameters:

lat (float) – Latitude coordinate (WGS84)
lon (float) – Longitude coordinate (WGS84)
buffer (float) – Buffer distance in degrees around the point (default 0.01 ≈ 1km)
**kwargs (Any) – Additional query parameters (limit, datetime, etc.)

Return type:

ModeledGroundwaterLevelCollection

Returns:

Typed collection of modeled groundwater levels for areas near the coordinates

Raises:

ValueError – If no areas found near the specified coordinates

Example

>>> from sgu_client import SGUClient
>>> client = SGUClient()
>>>
>>> # get modeled levels for a specific location (Stockholm)
>>> levels = client.levels.modeled.get_levels_by_coords(
...     lat=59.33,
...     lon=18.07,
...     limit=100
... )
>>>
>>> # increase buffer for larger search area
>>> levels = client.levels.modeled.get_levels_by_coords(
...     lat=59.33,
...     lon=18.07,
...     buffer=0.05,  # ~5km radius
...     datetime="2023-01-01/2024-01-01"
... )

Data Models#

Pydantic models for modeled groundwater data from SGU API.

class sgu_client.models.modeled.ModeledAreaProperties(**data)[source]#

Bases: SGUBaseModel

Properties for a modeled groundwater area.

Parameters:: data (Any)

model_config: ClassVar = {'extra': 'allow', 'use_enum_values': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

area_id: int#

time_series_url: str | None#

class sgu_client.models.modeled.ModeledArea(**data)[source]#

Bases: SGUBaseModel

A modeled groundwater area (GeoJSON Feature).

Parameters:: data (Any)

type: Literal['Feature']#

id: str#

geometry: Point | MultiPoint | LineString | Polygon | MultiPolygon#

properties: ModeledAreaProperties#

model_config: ClassVar[ConfigDict] = {'extra': 'allow', 'use_enum_values': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class sgu_client.models.modeled.ModeledGroundwaterLevelProperties(**data)[source]#

Bases: SGUBaseModel

Properties for a modeled groundwater level.

Parameters:: data (Any)

model_config: ClassVar = {'extra': 'allow', 'use_enum_values': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

date: str | None#

area_id: int#

deviation_small_resources: int | None#

deviation_large_resources: int | None#

relative_level_small_resources: int | None#

relative_level_large_resources: int | None#

object_id: int#

classmethod transform_missing_values(v)[source]#: Transform -1 values to None for large resource fields.

property date_parsed: datetime | None#: Parse date as datetime object (daily data, no timezone).

class sgu_client.models.modeled.ModeledGroundwaterLevel(**data)[source]#

Bases: SGUBaseModel

A modeled groundwater level (GeoJSON Feature).

Parameters:: data (Any)

type: Literal['Feature']#

id: str#

geometry: Point | MultiPoint | LineString | Polygon | MultiPolygon | None#

properties: ModeledGroundwaterLevelProperties#

model_config: ClassVar[ConfigDict] = {'extra': 'allow', 'use_enum_values': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class sgu_client.models.modeled.ModeledAreaCollection(**data)[source]#

Bases: SGUResponse

Collection of modeled groundwater areas (GeoJSON FeatureCollection).

Parameters:: data (Any)

type: Literal['FeatureCollection']#

features: list[ModeledArea]#

totalFeatures: int | None#

numberMatched: int | None#

numberReturned: int | None#

timeStamp: str | None#

links: list[Link] | None#

crs: CRS | None#

classmethod handle_unknown_total_features(v)[source]#: Handle ‘unknown’ string values for totalFeatures.

to_dataframe(**kwargs) → pd.DataFrame#

Convert to pandas DataFrame with flattened area properties.

Returns:: DataFrame containing area data with centroid coordinates.

Examples

>>> from sgu_client import SGUClient
>>> client = SGUClient()
>>> areas = client.levels.modeled.get_areas(limit=10)
>>> df = areas.to_dataframe()
>>>
>>> # dataFrame includes area properties and centroid coordinates
>>> print(df.columns)  # feature_id, centroid_longitude, centroid_latitude, area_id, time_series_url
>>> print(df[['area_id', 'centroid_longitude', 'centroid_latitude']].head())

model_config: ClassVar[ConfigDict] = {'extra': 'allow', 'use_enum_values': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class sgu_client.models.modeled.ModeledGroundwaterLevelCollection(**data)[source]#

Bases: SGUResponse

Collection of modeled groundwater levels (GeoJSON FeatureCollection).

Parameters:: data (Any)

type: Literal['FeatureCollection']#

features: list[ModeledGroundwaterLevel]#

totalFeatures: int | None#

numberMatched: int | None#

numberReturned: int | None#

timeStamp: str | None#

links: list[Link] | None#

crs: CRS | None#

classmethod handle_unknown_total_features(v)[source]#: Handle ‘unknown’ string values for totalFeatures.

to_dataframe(**kwargs) → pd.DataFrame#

Convert to pandas DataFrame with modeled level data.

Parameters:: sort_by_date – Whether to sort the DataFrame by date.
Returns:: DataFrame containing modeled level data.

Examples

>>> from sgu_client import SGUClient
>>> client = SGUClient()
>>> levels = client.levels.modeled.get_levels(limit=100)
>>> df = levels.to_dataframe()

>>> # dataFrame includes modeled percentile data sorted by date
>>> print(df[['date', 'area_id', 'relative_level_small_resources', 'deviation_small_resources']].head())

to_series(**kwargs) → pd.Series#

Convert to pandas Series with modeled data.

Parameters:

index – Column name to use as index. If None, date is used.
data – Column name to use as data. If None, relative_level_small_resources is used.
sort_by_date – Whether to sort the data by observation date before creating the Series.

Returns:

Series containing modeled data.

Examples

>>> from sgu_client import SGUClient
>>> client = SGUClient()
>>> levels = client.levels.modeled.get_levels(limit=100)
>>>
>>> # create time series with default columns (date, relative_level_small_resources)
>>> series = levels.to_series()
>>> print(series.head())
>>>
>>> # use custom columns - compare small vs large resources
>>> series_large = levels.to_series(
...     index="date",
...     data="relative_level_large_resources"
... )

model_config: ClassVar[ConfigDict] = {'extra': 'allow', 'use_enum_values': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Groundwater Levels API#

Overview#

Observed Groundwater Levels#

Client Interface#

Data Models#

Modeled Groundwater Levels#

Client Interface#

Data Models#

See Also#

This Page