knmidata.edr package¶
Submodules¶
Module contents¶
KNMI OGC EDR API client components.
- class knmidata.edr.AsyncEDRClient(*, transport: AsyncTransport, auth: Auth)¶
Bases:
objectClient for querying the KNMI OGC EDR API service.
- Parameters:
transport (AsyncTransport) – Shared HTTP transport and concurrency semaphore.
auth (httpx.Auth) – Authentication strategy providing the personal EDR API key.
- auth: Auth¶
- async collection(collection_id: str) dict[str, Any]¶
Get metadata for a collection, including available parameters and output formats.
- Parameters:
collection_id (str) – EDR collection ID (e.g. ‘daily-in-situ-meteorological-observations’).
- Returns:
Parsed JSON response of the /collections/{id} endpoint.
- Return type:
dict[str, Any]
- async collections() dict[str, Any]¶
List all collections available in the EDR API.
- Returns:
Parsed JSON response of the /collections endpoint.
- Return type:
dict[str, Any]
- async get_area(collection: str, bbox: tuple[float, float, float, float], start_time: str | Timestamp | datetime | date | None = None, end_time: str | Timestamp | datetime | date | None = None, parameters: str | list[str] | None = None, output_format: Literal['CoverageJSON', 'GeoJSON'] = 'CoverageJSON', crs: str | None = None) Dataset¶
Get data over a spatial bounding box via /collections/{id}/area.
- Parameters:
collection (str) – EDR collection ID.
bbox (BBox) – Bounding box as (minx, miny, maxx, maxy).
start_time (TimeLike | None, default=None) – Start of the queried time interval (see get_position).
end_time (TimeLike | None, default=None) – End of the queried time interval (see get_position).
parameters (list[str] | None, default=None) – Parameter name or list of parameter names to query.
output_format (str, default="CoverageJSON") – Response format: ‘CoverageJSON’ or ‘GeoJSON’.
crs (str | None, default=None) – Coordinate reference system of bbox.
- Returns:
In-memory xarray dataset.
- Return type:
xr.Dataset
- async get_cube(collection: str, bbox: tuple[float, float, float, float], z: str | tuple[float, float], start_time: str | Timestamp | datetime | date | None = None, end_time: str | Timestamp | datetime | date | None = None, parameters: str | list[str] | None = None, output_format: Literal['CoverageJSON', 'GeoJSON'] = 'CoverageJSON', crs: str | None = None) Dataset¶
Get a 3D volume via /collections/{id}/cube.
- Parameters:
collection (str) – EDR collection ID.
bbox (BBox) – Bounding box as (minx, miny, maxx, maxy).
z (ZLevel) – Vertical level or interval (e.g. ‘100’ or (100, 500)).
start_time (TimeLike | None, default=None) – Start of the queried time interval (see get_position).
end_time (TimeLike | None, default=None) – End of the queried time interval (see get_position).
parameters (list[str] | None, default=None) – Parameter name or list of parameter names to query.
output_format (str, default="CoverageJSON") – Response format: ‘CoverageJSON’ or ‘GeoJSON’.
crs (str | None, default=None) – Coordinate reference system of bbox and z.
- Returns:
In-memory xarray dataset.
- Return type:
xr.Dataset
- async get_location(collection_id: str, location_id: str, start_time: str | Timestamp | datetime | date | None = None, end_time: str | Timestamp | datetime | date | None = None, parameters: str | list[str] | None = None, output_format: Literal['CoverageJSON', 'GeoJSON'] = 'CoverageJSON') Dataset¶
Get data for a single location (weather station) as an xarray.Dataset.
Uses /collections/{id}/locations/{location_id}. This is the typical way to get a time series for a station collection: note that /position with a POINT coordinate can return HTTP 404 (“The query returned no stations”) for these collections.
- Parameters:
collection_id (str) – EDR collection ID.
location_id (str) – Location identifier (station id, e.g. ‘0-20000-0-06260’ for De Bilt; see locations()).
start_time (TimeLike | None, default=None) – Start of the time interval (see get_position).
end_time (TimeLike | None, default=None) – End of the time interval (see get_position).
parameters (list[str] | None, default=None) – Parameter name or list of parameter names to query.
output_format (OutputFormat, default="CoverageJSON") – Response format: ‘CoverageJSON’ or ‘GeoJSON’.
- Returns:
In-memory xarray dataset.
- Return type:
xr.Dataset
- async get_position(collection: str, coords: tuple[float, float], start_time: str | Timestamp | datetime | date | None = None, end_time: str | Timestamp | datetime | date | None = None, parameters: str | list[str] | None = None, output_format: Literal['CoverageJSON', 'GeoJSON'] = 'CoverageJSON', crs: str | None = None) Dataset¶
Get station or point time-series via /collections/{id}/position.
Note: /position does server-side nearest-station matching, but only within a tolerance — it returns HTTP 404 (“The query returned no stations”) when no station is close enough to the point. For a reliable client-side nearest lookup use nearest_location(), then get_location() with the returned station id.
- Parameters:
collection (str) – EDR collection ID.
coords (Coords) – Point coordinates (lon, lat).
start_time (TimeLike | None, default=None) – Start of the queried time interval (ISO-8601 string, pandas Timestamp, datetime, or date; naive values are assumed UTC). Sent as an RFC 3339 interval: with both start and end as ‘start/end’, with only start_time as ‘start/..’.
end_time (TimeLike | None, default=None) – End of the queried time interval. With only end_time given the interval ‘../end’ is sent. For a single instant, pass the same value as start_time and end_time.
parameters (list[str] | None, default=None) – Parameter name or list of parameter names to query (see collection metadata).
output_format (str, default="CoverageJSON") – Response format: ‘CoverageJSON’ or ‘GeoJSON’.
crs (str | None, default=None) – Coordinate reference system of coords, e.g. ‘EPSG:4326’.
- Returns:
In-memory xarray dataset.
- Return type:
xr.Dataset
- async instances(collection_id: str) dict[str, Any]¶
List the instances of a collection.
- Parameters:
collection_id (str) – EDR collection ID.
- Returns:
Parsed JSON response of the /collections/{id}/instances endpoint.
- Return type:
dict[str, Any]
- async location(collection_id: str, location_id: str) dict[str, Any]¶
Get metadata for a single location.
- Parameters:
collection_id (str) – EDR collection ID.
location_id (str) – Location identifier.
- Returns:
GeoJSON Feature.
- Return type:
dict[str, Any]
- async locations(collection_id: str) dict[str, Any]¶
List the measurement locations of a collection as GeoJSON.
- Parameters:
collection_id (str) – EDR collection ID.
- Returns:
GeoJSON FeatureCollection.
- Return type:
dict[str, Any]
- async nearest_location(collection_id: str, coords: tuple[float, float]) dict[str, Any]¶
Find the measurement location nearest to coords (client-side).
/position does server-side nearest-station matching but only within a tolerance — it returns HTTP 404 “The query returned no stations” when no station is close enough. This helper always returns the closest station: it fetches /locations and computes haversine distances.
- Parameters:
collection_id (str) – EDR collection ID.
coords (Coords) – Point coordinates (lon, lat).
- Returns:
The nearest location: {‘id’, ‘name’, ‘coordinates’, ‘distance_km’, ‘properties’}.
- Return type:
dict[str, Any]
- Raises:
KNMIError – If the collection has no locations.
- transport: AsyncTransport¶
- knmidata.edr.parse_coverage(payload: dict[str, Any], shared_parameters: dict[str, Any] | None = None) Dataset¶
Parse a single OGC CoverageJSON coverage into an xarray.Dataset.
Dimension order follows the order of the axes in
domain.axes, matching the flattened order of the range values.- Parameters:
payload (dict[str, Any]) – A single CoverageJSON coverage object.
shared_parameters (dict[str, Any] | None, default=None) – Parameter metadata from the enclosing CoverageCollection, used when the coverage itself has no “parameters” member (KNMI puts them at the collection level and only “ranges” in each coverage).
- Returns:
Multidimensional dataset.
- Return type:
xr.Dataset
- knmidata.edr.parse_coveragejson(payload: dict[str, Any]) Dataset¶
Parse an OGC CoverageJSON payload into an xarray.Dataset.
Handles both single coverages and CoverageCollections (as returned by /area, /cube, or multi-location queries on station collections). Coverages are concatenated along the
stationdimension, labelled with the station id (WSI) when the response carries it, else the grid origin, else acoverageindex.- Parameters:
payload (dict[str, Any]) – Parsed JSON response from an EDR data query with f=CoverageJSON.
- Returns:
Multidimensional dataset.
- Return type:
xr.Dataset
- knmidata.edr.parse_geojson(payload: dict[str, Any]) Dataset¶
Parse a GeoJSON FeatureCollection into an xarray.Dataset.
Used for EDR responses with f=GeoJSON (e.g. /locations or point queries on station collections). The dataset gets a ‘feature’ dimension, lon/lat/time coordinates when present, and one data variable per numeric property.
- Parameters:
payload (dict[str, Any]) – Parsed JSON response from an EDR query with f=GeoJSON.
- Returns:
Dataset with one entry per feature.
- Return type:
xr.Dataset