Modeled groundwater levels#

Groundwater levels modeled with SGU-HYPE, available as client.levels.modeled. See Groundwater levels for a walkthrough.

Methods#

`get_areas`	Get modeled groundwater areas.
`get_area`	Get a specific modeled groundwater area by ID.
`get_levels`	Get modeled groundwater levels.
`get_level`	Get a specific modeled groundwater level by ID.
`get_levels_by_area`	Get modeled groundwater levels for a specific area.
`get_levels_by_areas`	Get modeled groundwater levels for multiple areas.
`get_levels_by_coords`	Get modeled groundwater levels for a specific coordinate.

Models#

`ModeledAreaCollection`	Collection of modeled groundwater areas (GeoJSON FeatureCollection).
`ModeledArea`	A modeled groundwater area (GeoJSON Feature).
`ModeledAreaProperties`	Properties for a modeled groundwater area.
`ModeledGroundwaterLevelCollection`	Collection of modeled groundwater levels (GeoJSON FeatureCollection).
`ModeledGroundwaterLevel`	A modeled groundwater level (GeoJSON Feature).
`ModeledGroundwaterLevelProperties`	Properties for a modeled groundwater level.

Client#

class ModeledGroundwaterLevelClient(base_client)[source]#

Client for modeled groundwater level-related SGU API endpoints.

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
>>> with SGUClient() as client:
...     # 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, tmin=None, tmax=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) – Raw OGC date/time filter; prefer tmin/tmax
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)
tmin (str | datetime | None) – Earliest date (ISO string or datetime object)
tmax (str | datetime | None) – Latest date (ISO string or datetime object)
**kwargs (Any) – Additional query parameters

Return type:

ModeledGroundwaterLevelCollection

Returns:

Typed collection of modeled groundwater levels

Example

>>> from sgu_client import SGUClient
>>> with SGUClient() as client:
...     # get modeled levels
...     levels = client.levels.modeled.get_levels(limit=100)
...     # get levels for a specific time period
...     levels = client.levels.modeled.get_levels(
...         tmin="2023-01-01",
...         tmax="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, tmin=None, tmax=None, **kwargs)[source]#

Get modeled groundwater levels for a specific area.

Parameters:

area_id (int) – Area ID to filter by
tmin (str | datetime | None) – Earliest date (ISO string or datetime object)
tmax (str | datetime | None) – Latest date (ISO string or datetime object)
**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
>>> with SGUClient() as client:
...     # 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,
...         tmin="2023-01-01",
...         tmax="2024-01-01"
...     )

get_levels_by_areas(area_ids, tmin=None, tmax=None, **kwargs)[source]#

Get modeled groundwater levels for multiple areas.

Parameters:

area_ids (list[int]) – List of area IDs to filter by
tmin (str | datetime | None) – Earliest date (ISO string or datetime object)
tmax (str | datetime | None) – Latest date (ISO string or datetime object)
**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
>>> with SGUClient() as client:
...     levels = client.levels.modeled.get_levels_by_areas(
...         area_ids=[30125, 30126],
...         tmin="2024-09-30",
...         tmax="2025-10-01"
...     )
...     print(f"Found {len(levels.features)} modeled levels")

get_levels_by_coords(lat, lon, buffer=0.01, tmin=None, tmax=None, **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)
tmin (str | datetime | None) – Earliest date (ISO string or datetime object)
tmax (str | datetime | None) – Latest date (ISO string or datetime object)
**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
>>> with SGUClient() as client:
...     # 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
...         tmin="2023-01-01",
...         tmax="2024-01-01"
...     )

Model details#

Pydantic models for modeled groundwater data from SGU API.

pydantic model ModeledAreaProperties[source]#

Properties for a modeled groundwater area.

field area_id: int [Required] (alias 'omrade_id')#: Area ID

field time_series_url: str | None = None (alias 'url_tidsserie')#: Time series URL for this area

pydantic model ModeledArea[source]#: A modeled groundwater area (GeoJSON Feature).

pydantic model ModeledGroundwaterLevelProperties[source]#

Properties for a modeled groundwater level.

field date: Annotated[datetime | None] = None (alias 'datum')#

Date (midnight UTC)

Constraints:

func = <function _parse_api_datetime at 0x7fa47d9d60c0>
json_schema_input_type = PydanticUndefined

field area_id: int [Required] (alias 'omrade_id')#: Area ID

field deviation_small_resources: int | None = None (alias 'grundvattensituation_sma')#: Deviation for small resources (percentile 0-100)

field deviation_large_resources: int | None = None (alias 'grundvattensituation_stora')#: Deviation for large resources (percentile 0-100)

field relative_level_small_resources: int | None = None (alias 'fyllnadsgrad_sma')#: Relative level for small resources (percentile 0-100)

field relative_level_large_resources: int | None = None (alias 'fyllnadsgrad_stora')#: Relative level for large resources (percentile 0-100)

field object_id: int [Required] (alias 'objectid')#: Object ID

pydantic model ModeledGroundwaterLevel[source]#: A modeled groundwater level (GeoJSON Feature).

pydantic model ModeledAreaCollection[source]#

Collection of modeled groundwater areas (GeoJSON FeatureCollection).

Areas are grid cells, so the DataFrame has centroid_longitude and centroid_latitude columns: the centre of the cell. SGU sends only the cell’s outline; the centre is computed by sgu-client.

Examples

>>> from sgu_client import SGUClient
>>> with SGUClient() as client:
...     areas = client.levels.modeled.get_areas(limit=10)
...     df = areas.to_dataframe()
...     print(df[['area_id', 'centroid_longitude', 'centroid_latitude']].head())

pydantic model ModeledGroundwaterLevelCollection[source]#

Collection of modeled groundwater levels (GeoJSON FeatureCollection).

Its DataFrame has no geometry columns. Sorted by date; to_series() defaults to relative_level_small_resources.

Examples

>>> from sgu_client import SGUClient
>>> with SGUClient() as client:
...     levels = client.levels.modeled.get_levels(limit=100)
...     df = levels.to_dataframe()
...     print(df[['date', 'area_id', 'relative_level_small_resources']].head())
...     series = levels.to_series(data="relative_level_large_resources")