Skip to content

API reference

The Weather Controller class

WeatherController

Controller for the Weather Provider API.

This class is responsible for handling all requests for weather data, including fetching data from the appropriate sources and models, converting units, and formatting the output.

__init__ 

__init__()

Load the available weather sources and their models into the controller.

get_weather 

get_weather(source_id: str, model_id: str, fetch_async: bool, coords: list[list[tuple[float, float]]], begin: datetime | None = None, end: datetime | None = None, factors: list[str] | None = None) -> xr.Dataset | None

Get specific weather factors for a specific time and specific location(s).

Parameters:

Name Type Description Default
source_id str

The weather source that need to be queried (e.g.: knmi, cds)

 required
model_id str

The model identifier of the model that needs to be queried (has to be a model that exists within the specific source requested through source_id

 required
fetch_async bool

A boolean indicated if the request was made to asynchronously fetch the data or not

 required
coords list[list[tuple[float, float]]]

A nested 3-layer list representing a list of polygons in the case of points, they are treated as a one-point polygon D0: different polygons D1: sequence of points in each polygon D2: coordinates of each point (lat, lon in coordinates)

 required
begin datetime | None

The starting time of the requested output data

 None
end datetime | None

The ending time of the requested output data

 None
factors list[str] | None

A list of the requested weather factors for the output (default is all available)

 None

Returns:

Type Description
Dataset | None

A Xarray Dataset containing the weather data for the selected model, period(s), location(s) and factor(s)

convert_names_and_units 

convert_names_and_units(source_id: str, model_id: str, fetch_async: bool, weather_data: Dataset, unit: OutputUnit) -> xr.Dataset

Convert the names and units of the weather data to match the requested output unit format.

lat_lon_to_coords staticmethod 

lat_lon_to_coords(lat: float, lon: float) -> list[list[tuple[float, float]]]

Convert a single pair of coordinates into a nested list format representing a single-point polygon.

str_to_coords staticmethod 

str_to_coords(locations_string: str) -> list[list[tuple[float, float]]]

Convert a string containing coordinates into a list of tuples containing those coordinates.

get_source_keys 

get_source_keys() -> list[str]

Get a list of all available source keys.

get_sources 

get_sources() -> list[WeatherSourceBase]

Get a list of all available sources.

get_source 

get_source(source_id: str) -> WeatherSourceBase | None

Get a specific source by its ID.

get_models 

get_models(source_id: str, fetch_async: bool = False) -> list[WeatherModelBase]

Get a list of all available models for a specific source.

get_model 

get_model(source_id: str, model_id: str, fetch_async: bool = False) -> WeatherModelBase | None

Get a specific model by its ID for a specific source.

Weather Base classes

WeatherSourceBase

Base class that contains the basic functionality for all sources.

Any new sources should implement this as their base class!

models property 

models: list[WeatherModelBase]

Get all synchronous models from the source.

async_models property 

async_models: list[WeatherModelBase]

Get all asynchronous models from the source.

__init__ 

__init__(source_id: str, name: str, url: str, model_instances: list[WeatherModelBase], *args: Any, **kwargs: Any) -> None

Initialize the WeatherSourceBase with an ID and set up the models.

get_model 

get_model(model_id: str, fetch_async: bool = False) -> WeatherModelBase | None

Get a specific model from the source based on the provided model ID and whether it is an asynchronous request or not.

get_models 

get_models(fetch_async: bool = False) -> list[WeatherModelBase]

Get all models from the source based on whether it is an asynchronous request or not.

WeatherModelBase

Base class for all Weather Models. All new models should use this base class!

__init__ 

__init__()

Initialize the WeatherModelBase with default conversion dictionaries.

get_weather abstractmethod 

get_weather(coords: list[GeoPosition], begin: datetime | None = None, end: datetime | None = None, weather_factors: list[str] | None = None) -> xr.Dataset

Abstract method to get weather data for the specified coordinates and time range.

is_async abstractmethod 

is_async() -> bool

Abstract method to determine if the model is asynchronous.

convert_names_and_units 

convert_names_and_units(weather_data: Dataset, unit: OutputUnit) -> xr.Dataset

Convert the names and units of the weather data to match the requested output unit format.

Parameters:

Name Type Description Default
weather_data Dataset

A Xarray Dataset containing

 required
unit OutputUnit

The requested output unit format

 required

Returns:

Type Description
Dataset

The same dataset, but with values altered to match the requested output unit format

celsius_to_kelvin staticmethod 

celsius_to_kelvin(x: Any) -> Any

Convert a temperature from Celsius to Kelvin.

kelvin_to_celsius staticmethod 

kelvin_to_celsius(x: Any) -> Any

Convert a temperature from Kelvin to Celsius.

tenth_celsius_to_kelvin 

tenth_celsius_to_kelvin(x: Any) -> Any

Convert a temperature from tenths of Celsius to Kelvin.

normalize_tenths staticmethod 

normalize_tenths(x: Any) -> Any

Normalize a value in tenths to its actual value.

no_conversion staticmethod 

no_conversion(x: Any) -> Any

Return the value without any conversion.

percentage_to_frac staticmethod 

percentage_to_frac(x: Any) -> Any

Convert a percentage value to a fraction.

kmh_to_ms staticmethod 

kmh_to_ms(x: Any) -> Any

Convert a speed from kilometers per hour to meters per second.

dutch_wind_direction_to_degrees staticmethod 

dutch_wind_direction_to_degrees(xs: str) -> float | None

Convert a Dutch wind direction string to degrees.

knmi_visibility_class_to_meter_estimate staticmethod 

knmi_visibility_class_to_meter_estimate(xs: int) -> float

Function to transform KNMI visibility class values to an estimate of meters visibility.

Parameters:

Name Type Description Default
xs int

The visibility class value to be interpreted

 required

Returns:

Type Description
float

A numeric value containing an estimate of the meters of visibility matching the given visibility class value

WeatherRepositoryBase

Bases: ABC

Base class for weather repositories.

metadata property 

metadata: str

Get the metadata of the repository.

identifier property 

identifier: str

Get the unique identifier for the repository.

storage_path property 

storage_path: Path

Get the path where the weather data will be stored.

absolute_storage_path property 

absolute_storage_path: Path

Get the absolute path where the weather data will be stored.

source_and_model property 

source_and_model: dict[str, str]

Get the source and model name affiliated with this repository.

oldest_date_available property 

oldest_date_available: date

Get the oldest date for which weather data is available in the repository.

newest_date_available property 

newest_date_available: date

Get the newest date for which weather data is available in the repository.

__init__ 

__init__(config: WeatherRepositoryConfiguration)

Initialize the repository.

update abstractmethod 

update(*, run_in_testmode: bool = False) -> tuple[RepoUpdateResult, str]

Update the repository with new weather data up to the specified date.

Parameters:

Name Type Description Default
run_in_testmode bool

Whether to run the update in test mode. Defaults to False.

 False

Returns:

Name Type Description
RepoUpdateResult RepoUpdateResult 
The result of the update operation.
str str 
An optional message providing additional information about the update result.

cleanup_storage abstractmethod 

cleanup_storage() -> RepoUpdateResult

Clean up the storage by removing outdated or unnecessary data.

Returns:

Name Type Description
RepoUpdateResult RepoUpdateResult 
The result of the cleanup operation.

retrieve_data abstractmethod 

retrieve_data(from_date: date, to_date: date, locations: list[tuple[float, float]], factors: list[str]) -> tuple[xr.Dataset | None, RepoDataFetchResult]

Retrieve weather data for the specified date range.

Parameters:

Name Type Description Default
from_date date 
The start date of the data retrieval range.
required
to_date date 
The end date of the data retrieval range.
required
locations list[tuple[float, float]] 
A list of WGS84 location coordinates (latitude, longitude) for which to retrieve weather data.
required
factors list[str] 
A list of weather factors to retrieve (e.g., temperature, precipitation).
required

Returns:

Name Type Description
Dataset | None

xr.Dataset | None: The retrieved weather data as an xarray Dataset, or None if no data is available.
RepoDataFetchResult RepoDataFetchResult 
The result of the data fetch operation, indicating success, partial success, failure,
or no data available.

purge_repository 

purge_repository(identifier: str) -> RepoUpdateResult

Permanently delete all data from the repository.

Parameters:

Name Type Description Default
identifier str 
The unique identifier of the repository to be purged.
required

Returns:

Name Type Description
RepoUpdateResult RepoUpdateResult 
The result of the purge operation.

safely_delete_file classmethod 

safely_delete_file(file_path: Path) -> bool

Safely delete a file from the repository storage.

Parameters:

Name Type Description Default
file_path Path

The path of the file to be deleted.

 required

Returns:

Name Type Description
bool bool

True if the file was successfully deleted, False otherwise.

return_file_or_text_response 

return_file_or_text_response(unserialized_data: Dataset, response_format: ResponseFormat, source_id: str, model_id: str, request: WeatherContentRequestQuery | WeatherContentRequestMultiLocationQuery, coords: list[tuple[float, float]]) -> tuple[ScientificJSONResponse | FileResponse, str | None]

Return a file or text response based on the provided response format and data.

Parameters:

Name Type Description Default
unserialized_data Dataset

The data to be returned in the response.

 required
response_format ResponseFormat

The format in which the response should be returned.

 required
source_id str

The ID of the source for which the data is being returned.

 required
model_id str

The ID of the model for which the data is being returned.

 required
request WeatherContentRequestQuery | WeatherContentRequestMultiLocationQuery

The original request object containing query parameters.

 required
coords list[tuple[float, float]]

A list of coordinates for which the data is being returned.

 required