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:
objectAsynchronous 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:
- edr¶
EDR API namespace: collections, locations, get_location, get_position, get_area, get_cube, … (authentication resolved lazily on first access).
- Type:
- 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:
objectSynchronous 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