module routers

Routers for the API endpoints.

app.routers.general.index() → RedirectResponse[source]

redirect requests to the index to the docs

Return type:

RedirectResponse

app.routers.general.robots() → str[source]
Return type:

str

class app.routers.v1.DataMappingDaily[source]
allowed_params: type[PublicParamsAggBiomet | PublicParamsAggTempRH]
table: type[BiometDataDaily | TempRHDataDaily]
class app.routers.v1.DataMappingHourly[source]
allowed_params: type[PublicParamsAggBiomet | PublicParamsAggTempRH]
table: type[BiometDataHourly | TempRHDataHourly]
class app.routers.v1.DataMappingMax[source]
allowed_params: type[PublicParamsBiomet | PublicParamsTempRH]
table: type[BiometData | TempRHData]
class app.routers.v1.TableMapping[source]
daily: DataMappingDaily
hourly: DataMappingHourly
max: DataMappingMax
app.routers.v1.compute_colormap_range(*, data_min, data_max, param_setting) → tuple[float, float] | tuple[None, None][source]

calculate a colormap range based on the data and the expected range of a parameter.

Parameters:
Return type:

tuple[float, float] | tuple[None, None]

Returns:

the minimum and maximum value for the colormap

async app.routers.v1.download_station_data(station_id=Path(PydanticUndefined), start_date=Query(None), end_date=Query(None), scale=Query(max), fill_gaps=Query(False), db=Depends(get_db_session)) → StreamingResponse[source]

This endpoint allows for downloading large amounts of data on a per-station basis. The data is provided as a CSV-file and always includes all publicly available columns. The set of columns may vary depending on the type of station (temprh has a different set of columns than biomet) and the temporal scale (max, hourly, daily), where the last two will also provide extreme values (_min and _max).

Return type:

StreamingResponse

async app.routers.v1.get_data(station_id=Path(PydanticUndefined), start_date=Query(PydanticUndefined), end_date=Query(PydanticUndefined), param=Query(PydanticUndefined), scale=Query(max), fill_gaps=Query(True), db=Depends(get_db_session)) → Any[source]

API-endpoint for getting the data from any station for any time-span. A maximum of 31 days at 5-minute resolution, 365 days at hourly resolution and 3650 days at daily resolution can be requested at once. If you need more data, please paginate your requests.

Note: When requesting, you have to take the station type into account, not every StationType supports all parameters. So the combination of scale and StationType determines the values you are able to request. It is important to check the Error responses (422) for the correct subset. Generally _min and _max parameters are available when using scale as daily or hourly. Stations of type StationType.biomet will support the full set of parameters. Stations of type StationType.temprh only have parameters that can be derived from air-temperature and relative humidity measurements, which are: :rtype: Any

  • air_temperature

  • relative_humidity

  • dew_point

  • absolute_humidity

  • heat_index

  • wet_bulb_temperature

Temporal Aggregation (scale parameter): _Hourly_ values are right-labeled aggregates. Values from 2024-01-01 10:00:00+00:00 until 2024-01-01 10:59:59.999999+00:00 are labelled as 2024-01-01 11:00:00+00:00 and hence start_date and end_date have to take that into account when being used with scale=hourly.

_Daily_ values are aggregated _internally_ based on the UTC+1 timezone, meaning a daily average covers the period from 2024-01-10 23:00:00+00:00 to 2024-01-11 22:59:59.999999+00:00. This approach was chosen for (annual) consistency, rather than aligning with true solar time.

There is no daylight savings time in UTC!

_min and _max parameters are calculated upon aggregation, deriving the minimum and maximum of each parameter from the raw data. This is done on a per-hour basis as well as a on daily basis, always deriving extremes from the raw values. Discrete values such as heat stress categories are aggregated using the mode (most common category in the time period).

For the daily scale, aggregations for a station are set to null if less than 70 % of the expected values are present.

async app.routers.v1.get_network_snapshot(param=Query(PydanticUndefined), scale=Query(PydanticUndefined), date=Query(PydanticUndefined), suggest_viz=Query(False), db=Depends(get_db_session)) → Any[source]

API endpoint for retrieving data from all network stations at a specific time.

You may specify multiple params. The availability of the param depends on the StationType. Stations of type StationType.biomet support all parameters, stations of type StationType.temprh only support a subset of parameters, that can be derived from air_temperature and relative_humidity which are: :rtype: Any

  • air_temperature

  • relative_humidity

  • dew_point

  • absolute_humidity

  • heat_index

  • wet_bulb_temperature

Since StationType.temprh only supports a subset, the unsupported parameters are set to null when multiple params are requested. If StationType.temprh does not support any of the requested parameters, these stations are completely omitted from the result.

async app.routers.v1.get_stations_latest_data(param=Query(PydanticUndefined), max_age=Query(1:00:00), db=Depends(get_db_session)) → Any[source]

API-endpoint for getting the latest data from all available stations. Only stations that can provide all requested parameters are returned. The availability depends on the StationType. Stations of type StationType.biomet support all parameters, stations of type StationType.temprh only support a subset of parameters, that can be derived from air_temperature and relative_humidity which are: :rtype: Any

  • air_temperature

  • relative_humidity

  • dew_point

  • absolute_humidity

  • heat_index

  • wet_bulb_temperature

async app.routers.v1.get_stations_metadata(param=Query(None), include_inactive=Query(False), db=Depends(get_db_session)) → Any[source]

API-endpoint for retrieving metadata from all available stations. This does not take into account whether or not they currently have any up-to-date data.

Return type:

Any

Retrieve hourly data for a specific parameter across a time period, choosing either districts or stations. Data is based on hourly aggregates and refer to a specific hour of the day.

Return type:

Any

async app.routers.v1.is_healthy(db=Depends(get_db_session)) → dict[str, str][source]

API-endpoint to check whether the system is healthy. This is used by docker to check the container health. A HEAD request will not trigger a db-query, only a GET request will do that.

Return type:

dict[str, str]

async app.routers.v1.stream_results(stm) → AsyncGenerator[str][source]

Stream the results of a query in batches of 250 rows as CSV. This is used to stream large amounts of data to the client without having to load everything into memory.

Parameters:

  • stm (Select) – the database query to execute

  • db – the database session to pass from the route

Return type:

AsyncGenerator[str]

Returns:

an (async) generator that yields CSV-formatted strings in batches of 250 rows.