# FMI Weather Binding This binding integrates to [the Finnish Meteorological Institute (FMI) Open Data API](https://en.ilmatieteenlaitos.fi/open-data). The binding provides access to weather observations from FMI weather stations and FMI weather forecasts. Forecast covers "northern Europe" (Finland, Baltics, Scandinavia, some parts of surrounding countries), see [coverage map in the documentation](https://en.ilmatieteenlaitos.fi/weather-forecast-models). The binding supports two different forecast queries: - [HARMONIE weather forecast model](https://en.ilmatieteenlaitos.fi/weather-forecast-models), which is one of the weather models that meteorologists use in their work. - An edited query providing the official FMI forecast, which is often more accurate since it's edited by meteorologists who combine several different weather models and their experience to produce the official forecast. ![example of things](doc/images/fmi-example-things.png) ## License Finnish Meteorological Institute's open data service uses the Creative Commons Attribution 4.0 International license (CC BY 4.0). By using the binding, you agree to license terms as explained in [FMI website](https://en.ilmatieteenlaitos.fi/open-data-licence). ## Supported Things There are two supported things: - `observation` thing shows current weather observation for a given station. Data is updated automatically every 10 minutes. - `forecast` thing shows forecasted weather conditions for a location. Data is updated automatically every 20 minutes. ## Discovery The binding automatically discovers weather stations and forecasts for nearby places: - `observation` things for nearby weather stations - `forecast` things for nearby Finnish cities and for the current location ## Thing Configuration ### `observation` Thing Configuration | Parameter | Type | Required | Description | Example | | --------- | ---- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | | `fmisid` | text | ✓ | FMI Station ID. You can FMISID of see all weathers stations at [FMI web site](https://en.ilmatieteenlaitos.fi/observation-stations?p_p_id=stationlistingportlet_WAR_fmiwwwweatherportlets&p_p_lifecycle=0&p_p_state=normal&p_p_mode=view&p_p_col_id=column-4&p_p_col_count=1&_stationlistingportlet_WAR_fmiwwwweatherportlets_stationGroup=WEATHER#station-listing) | `"852678"` for Espoo Nuuksio station | ### `forecast` Thing Configuration | Parameter | Type | Required | Description | Example | | ---------- | ---- | -------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------- | | `location` | text | ✓ | Latitude longitude location for the forecast. The parameter is given in format `LATITUDE,LONGITUDE`. | `"60.192059, 24.945831"` for Helsinki | | `query` | text | | Stored query for official FMI forecast, either `harmonie` or `edited`. | | ## Channels Observation and forecast things provide slightly different details on weather. ### `observation` Thing Channels Observation channels are grouped in single group, `current`. | Channel ID | Item Type | Description | | ----------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `time` | `DateTime` | Observation time | | `temperature` | `Number:Temperature` | Air temperature | | `humidity` | `Number:Dimensionless` | Relative Humidity | | `wind-direction` | `Number:Angle` | Wind Direction | | `wind-speed` | `Number:Speed` | Wind Speed | | `wind-gust` | `Number:Speed` | Wind Gust Speed | | `pressure` | `Number:Pressure` | Air pressure | | `precipitation` | `Number:Length` | Precipitation in one hour | | `snow-depth` | `Number:Length` | Snow depth | | `visibility` | `Number:Length` | Visibility | | `clouds` | `Number:Dimensionless` | Cloudiness. Given as percentage, 0 % being clear skies, and 100 % being overcast. `UNDEF` when cloud coverage could not be determined. | | `present-weather` | `Number` | Prevailing weather as WMO code 4680. For details, see e.g. [description at Centre for Environmental Data Analysis](https://artefacts.ceda.ac.uk/badc_datadocs/surface/code.html). | You can check the exact observation time by using the `time` channel. To refer to certain channel, use the normal convention `THING_ID:GROUP_ID#CHANNEL_ID`, e.g. `fmiweather:observation:station_874863_Espoo_Tapiola:current#temperature`. ### `forecast` Thing Channels Forecast has multiple channel groups, one for each forecasted time. The groups are named as follows: - `forecast`: Forecasted weather (with time series support) - `forecastNow`: Forecasted weather for the current time (deprecated, please use `forecast` instead) - `forecastHours01`: Forecasted weather for 1 hours from now - `forecastHours02`: Forecasted weather for 2 hours from now - etc. - `forecastHours50`: Forecasted weather for 50 hours from now You can check the exact forecast time by using the `time` channel. Since forecasts are updated at certain times of the day, the last forecast values might be unavailable (`UNDEF`). Typically forecasts between now and 44 hours should be available at all times. | Channel ID | Item Type | Description | | ------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `time` | `DateTime` | Date of data forecasted | | `temperature` | `Number:Temperature` | Forecasted air temperature | | `humidity` | `Number:Dimensionless` | Forecasted relative Humidity | | `wind-direction` | `Number:Angle` | Forecasted wind Direction | | `wind-speed` | `Number:Speed` | Forecasted wind Speed | | `wind-gust` | `Number:Speed` | Forecasted wind Gust Speed | | `pressure` | `Number:Pressure` | Forecasted air pressure | | `precipitation-intensity` | `Number:Speed` | Forecasted precipitation intensity at the forecast time in mm/h | | `total-cloud-cover` | `Number:Dimensionless` | Forecasted total cloud cover as percentage | | `weather-id` | `Number` | Number indicating forecasted weather condition. Corresponds to `WeatherSymbol3` parameter. For descriptions in Finnish, see [FMI web site](https://ilmatieteenlaitos.fi/latauspalvelun-pikaohje). | To refer to certain channel, use the normal convention `THING_ID:GROUP_ID#CHANNEL_ID`, e.g. `fmiweather:forecast:HelsinkiForecast:forecastHours06#wind-speed`. ## Unit Conversion Please use the [Units Of Measurement](https://www.openhab.org/docs/concepts/units-of-measurement.html) concept of openHAB for unit conversion which is fully supported by this binding. ## Full Example ### Things `fmi.things`: ```java Thing fmiweather:observation:station_Helsinki_Kumpula "Helsinki Kumpula Observation" [fmisid="101004"] Thing fmiweather:forecast:forecast_Helsinki "Helsinki Forecast" [location="60.192059, 24.945831"] ``` ### Items `observation.items`: ```java DateTime HelsinkiObservationTime "Observation Time [%1$tY-%1$tm-%1$tdT%1$tH:%1$tM:%1$tS]"