knmidata.edr.client module

OGC Environmental Data Retrieval (EDR) query client.

class knmidata.edr.client.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