knmidata.client module

Composition roots and client facades for asynchronous and synchronous workflows.

The clients expose one namespace per KNMI API, symmetric for async and sync use:

async with AsyncKNMIClient() as client:
    ds = await client.opendata.get_dataset("dataset", "1.0", ...)
    ts = await client.edr.get_location("collection", "0-20000-0-06260", ...)

with KNMIClient() as client:  # same, but blocking
    ds = client.opendata.get_dataset("dataset", "1.0", ...)
    ts = client.edr.get_location("collection", "0-20000-0-06260", ...)
class knmidata.client.AsyncKNMIClient(api_key: str | None = None, edr_key: str | None = None, max_concurrency: int = 15, timeout: float = 60.0, max_retries: int = 3)

Bases: object

Asynchronous client composing all KNMI Data Platform API sub-services.

opendata

Open Data API namespace: list_files, download_files, open_dataset (files already on disk), get_dataset, … (authentication resolved lazily on first access).

Type:

AsyncOpenDataClient

edr

EDR API namespace: collections, locations, get_location, get_position, get_area, get_cube, … (authentication resolved lazily on first access).

Type:

AsyncEDRClient

Parameters:
  • api_key (str | None, default=None) – API key used for the Open Data API. Falls back to the KNMI_OPENDATA_API_KEY environment variable (or KNMI_OPENDATA_API_KEY_FILE), then to the public anonymous key.

  • edr_key (str | None, default=None) – Dedicated EDR API key. KNMI issues separate keys per API, so an Open Data key does not work for EDR. Falls back to KNMI_EDR_API_KEY (or KNMI_EDR_API_KEY_FILE).

  • max_concurrency (int, default=15) – Maximum concurrent network requests.

  • timeout (float, default=60.0) – Read timeout in seconds.

  • max_retries (int, default=3) – Retries for transient failures (429/5xx/transport errors).

async aclose() → None

Close the underlying HTTP transport session.

property edr: AsyncEDRClient

The EDR API namespace, lazily initializing its authentication.

async get_dataset(dataset_name: str, dataset_version: str, **kwargs: Any) → Dataset

Shortcut for client.opendata.get_dataset(…).

See AsyncOpenDataClient.get_dataset for the full parameter list (start_time, end_time, cache_dir, file_pattern, max_files, engine, combine, concat_dim, and per-file xarray.open_dataset kwargs).

async get_timeseries(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, **kwargs: Any) → Dataset

Shortcut for client.edr.get_location(…) (single station time series).

See AsyncEDRClient.get_location for the full parameter list (parameters, output_format).

property opendata: AsyncOpenDataClient

The Open Data API namespace, lazily initializing its authentication.

property transport: AsyncTransport

The shared HTTP transport.

class knmidata.client.KNMIClient(api_key: str | None = None, edr_key: str | None = None, max_concurrency: int = 15, timeout: float = 60.0, max_retries: int = 3)

Bases: object

Synchronous facade wrapping AsyncKNMIClient for non-async environments.

All coroutines are executed on a dedicated background event loop in a separate thread, so the client can be called repeatedly (and from inside environments that already run an event loop, such as Jupyter).

opendata

Synchronous facade for the Open Data API namespace.

Type:

_SyncFacade

edr

Synchronous facade for the EDR API namespace.

Type:

_SyncFacade

Parameters:
  • api_key (str | None, default=None) – API key used for the Open Data API. Falls back to the KNMI_OPENDATA_API_KEY environment variable (or KNMI_OPENDATA_API_KEY_FILE), then to the public anonymous key.

  • edr_key (str | None, default=None) – Dedicated EDR API key. KNMI issues separate keys per API, so an Open Data key does not work for EDR. Falls back to KNMI_EDR_API_KEY (or KNMI_EDR_API_KEY_FILE).

  • max_concurrency (int, default=15) – Maximum concurrent network requests.

  • timeout (float, default=60.0) – Read timeout in seconds.

  • max_retries (int, default=3) – Retries for transient failures (429/5xx/transport errors).

close() → None

Close the underlying connection pool and stop the background loop.

property edr: _SyncFacade

Synchronous facade for the EDR API namespace (cached).

EDR auth is resolved lazily on first access.

get_dataset(dataset_name: str, dataset_version: str, **kwargs: Any) → Dataset

Shortcut for client.opendata.get_dataset(…) (synchronous).

See AsyncOpenDataClient.get_dataset for the full parameter list.

get_timeseries(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, **kwargs: Any) → Dataset

Shortcut for client.edr.get_location(…) (synchronous).

See AsyncEDRClient.get_location for the full parameter list.

property opendata: _SyncFacade

Synchronous facade for the Open Data API namespace (cached).

knmidata.client.get_dataset(dataset_name: str, dataset_version: str, api_key: str | None = None, **kwargs: Any) → Dataset

One-line convenience function to get an Open Data dataset as an xarray.Dataset.

Downloads matching files (reusing cache_dir if given) and opens them.

Parameters:
  • dataset_name (str) – KNMI dataset name.

  • dataset_version (str) – Dataset version identifier.

  • api_key (str | None, default=None) – Optional KNMI Open Data API key. Falls back to environment variables and the public anonymous key if omitted.

  • **kwargs (Any) – Forwarded to AsyncOpenDataClient.get_dataset: start_time, end_time, cache_dir, file_pattern, max_files, engine, combine, concat_dim, and per-file xarray.open_dataset keyword arguments.

Returns:

Multidimensional dataset.

Return type:

xr.Dataset

knmidata.client.get_timeseries(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, edr_key: str | None = None, **kwargs: Any) → Dataset

One-line convenience function to get a station time series via the EDR API.

Parameters:
  • collection_id (str) – EDR collection ID (e.g. ‘daily-in-situ-meteorological-observations’).

  • location_id (str) – Station/location ID (e.g. ‘0-20000-0-06260’ for De Bilt; find ids via AsyncEDRClient.locations).

  • start_time (TimeLike | None, default=None) – Start of the time interval (ISO-8601 string, pandas Timestamp, datetime, or date; naive values are assumed UTC).

  • end_time (TimeLike | None, default=None) – End of the time interval (TimeLike, see start_time).

  • parameters (str | list[str] | None, default=None) – Variable(s) to get, e.g. ‘TG’ or [‘RH’, ‘TG’, ‘EV24’].

  • edr_key (str | None, default=None) – Optional KNMI EDR API key. Falls back to the KNMI_EDR_API_KEY environment variable (or KNMI_EDR_API_KEY_FILE). Note KNMI issues a separate key per API: the Open Data key does not work for EDR.

  • **kwargs (Any) – Forwarded to AsyncEDRClient.get_location (e.g. output_format).

Returns:

In-memory dataset with a time dimension.

Return type:

xr.Dataset