knmidata.edr package

Submodules

Module contents

KNMI OGC EDR API client components.

class knmidata.edr.AsyncEDRClient(*, transport: AsyncTransport, auth: Auth)

Bases: object

Client 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 station dimension, labelled with the station id (WSI) when the response carries it, else the grid origin, else a coverage index.

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