diff --git a/bundles/org.openhab.binding.openweathermap/README.md b/bundles/org.openhab.binding.openweathermap/README.md index 6af72c0f7..eb8a4b8e7 100644 --- a/bundles/org.openhab.binding.openweathermap/README.md +++ b/bundles/org.openhab.binding.openweathermap/README.md @@ -10,7 +10,7 @@ This binding integrates the [OpenWeatherMap weather API](https://openweathermap. ## Supported Things -There are three supported things. +There are five supported things. ### OpenWeatherMap Account @@ -27,12 +27,25 @@ You can add as many `weather-and-forecast` things for different locations to you The binding tries to request daily forecast data from the OpenWeatherMap API. If the request fails, all daily forecast channel groups will be removed from the thing and further request will be omitted. -### Current UV Index And Forceast +### Current UV Index And Forecast The third thing `uvindex` supports the [current UV Index](https://openweathermap.org/api/uvi#current) and [forecasted UV Index](https://openweathermap.org/api/uvi#forecast) for a specific location. It requires coordinates of the location of your interest. You can add as much `uvindex` things for different locations to your setup as you like to observe. +### One Call API Weather and Forecast + +The thing `onecall` supports the [current and forecast weather data](https://openweathermap.org/api/one-call-api#how) for a specific location using the One Call API. +It requires coordinates of the location of your interest. +You can add as many `onecall` things for different locations to your setup as you like to observe. + +### One Call API History Data + +The thing `onecall-history` supports the [historical weather data](https://openweathermap.org/api/one-call-api#history) for a specific location using the One Call API. +It requires coordinates of the location of your interest. +You can add as many `onecall-history` things for different locations to your setup as you like to observe. +For every day in history you have to create a different thing. + ## Discovery If a system location is set, a "Local Weather And Forecast" (`weather-and-forecast`) thing and "Local UV Index" (`uvindex`) thing will be automatically discovered for this location. @@ -67,6 +80,22 @@ Once the parameters `forecastHours` or `forecastDays` will be changed, the avail Once the parameter `forecastDays` will be changed, the available channel groups on the thing will be created or removed accordingly. +### One Call API Weather and Forecast + +| Parameter | Description | +|----------------|--------------------------------------------------------------------------------------------------------------------------------| +| location | Location of weather in geographical coordinates (latitude/longitude/altitude). **Mandatory** | +| forecastMinutes| Number of minutes for minutely precipitation forecast. Optional, the default value is 0, so by default **no** minutely forecast data is fetched. (min="0", max="60"). | +| forecastHours | Number of hours for hourly forecast. Optional, the default value is 24 (min="0", max="48"). | +| forecastDays | Number of days for daily forecast (including todays forecast). Optional, the default value is 6 (min="0", max="8"). | + +### One Call API History Data + +| Parameter | Description | +|----------------|--------------------------------------------------------------------------------------------------------------------------------| +| location | Location of weather in geographical coordinates (latitude/longitude/altitude). **Mandatory** | +| historyDay | Number of days back in history. The API supports going back up to 5 days at the moment. **Mandatory** | + ## Channels ### Station @@ -77,11 +106,15 @@ Once the parameter `forecastDays` will be changed, the available channel groups | station | name | String | Name of the weather station or the city. | | station | location | Location | Location of the weather station or the city. | +These channels are not supported in the One Call API + ### Current Weather | Channel Group ID | Channel ID | Item Type | Description | |------------------|----------------------|----------------------|-------------------------------------------------------------------------| | current | time-stamp | DateTime | Time of data observation. | +| current | sunrise | DateTime | Sunrise time of current day. Only available in the One Call API | +| current | sunset | DateTime | Sunset time of current day. Only available in the One Call API | | current | condition | String | Current weather condition. | | current | condition-id | String | Id of the current weather condition. **Advanced** | | current | icon | Image | Icon representing the current weather condition. | @@ -90,6 +123,7 @@ Once the parameter `forecastDays` will be changed, the available channel groups | current | apparent-temperature | Number:Temperature | Current apparent temperature. | | current | pressure | Number:Pressure | Current barometric pressure. | | current | humidity | Number:Dimensionless | Current atmospheric humidity. | +| current | dew-point | Number:Temperature | Current dew-point. Only available in the One Call API | | current | wind-speed | Number:Speed | Current wind speed. | | current | wind-direction | Number:Angle | Current wind direction. | | current | gust-speed | Number:Speed | Current gust speed. **Advanced** | @@ -97,6 +131,8 @@ Once the parameter `forecastDays` will be changed, the available channel groups | current | rain | Number:Length | Rain volume of the last hour. | | current | snow | Number:Length | Snow volume of the last hour. | | current | visibility | Number:Length | Current visibility. | +| current | uvindex | Number | Current UV Index. Only available in the One Call API | + **Attention**: Rain item is showing "1h" in the case when data are received from weather stations directly. The fact is that some METAR stations do not have precipitation indicators or do not measure precipitation conditions due to some other technical reasons. @@ -104,6 +140,15 @@ In this case, we use model data. So, rain item is showing "3h" when the API response based on model data. The "3h" value will be divided by three to always have an estimated value for one hour. +### One Call API Minutely Forecast + +Where available, the One Call API provides a minutely precipitation forecast for the next 60 minutes. + +| Channel Group ID | Channel ID | Item Type | Description | +|--------------------------------------------------------|----------------------|----------------------|----------------------------------------------------------------------------| +| forecastMinutes01 ... forecastMinutes60 | time-stamp | DateTime | Time of data forecasted. | +| forecastMinutes01 ... forecastMinutes60 | precipitation | Number:Length | Expected precipitation volume. | + ### 3 Hour Forecast | Channel Group ID | Channel ID | Item Type | Description | @@ -115,8 +160,8 @@ The "3h" value will be divided by three to always have an estimated value for on | forecastHours03, forecastHours06, ... forecastHours120 | icon-id | String | Id of the icon representing the forecasted weather condition. **Advanced** | | forecastHours03, forecastHours06, ... forecastHours120 | temperature | Number:Temperature | Forecasted temperature. | | forecastHours03, forecastHours06, ... forecastHours120 | apparent-temperature | Number:Temperature | Forecasted apparent temperature. | -| forecastHours03, forecastHours06, ... forecastHours120 | min-temperature | Number:Temperature | Minimum forecasted temperature. | -| forecastHours03, forecastHours06, ... forecastHours120 | max-temperature | Number:Temperature | Maximum forecasted temperature. | +| forecastHours03, forecastHours06, ... forecastHours120 | min-temperature | Number:Temperature | Minimum forecasted temperature. Not available in One Call API | +| forecastHours03, forecastHours06, ... forecastHours120 | max-temperature | Number:Temperature | Maximum forecasted temperature. Not available in One Call API | | forecastHours03, forecastHours06, ... forecastHours120 | pressure | Number:Pressure | Forecasted barometric pressure. | | forecastHours03, forecastHours06, ... forecastHours120 | humidity | Number:Dimensionless | Forecasted atmospheric humidity. | | forecastHours03, forecastHours06, ... forecastHours120 | wind-speed | Number:Speed | Forecasted wind speed. | @@ -125,6 +170,14 @@ The "3h" value will be divided by three to always have an estimated value for on | forecastHours03, forecastHours06, ... forecastHours120 | cloudiness | Number:Dimensionless | Forecasted cloudiness. | | forecastHours03, forecastHours06, ... forecastHours120 | rain | Number:Length | Expected rain volume. | | forecastHours03, forecastHours06, ... forecastHours120 | snow | Number:Length | Expected snow volume. | +| forecastHours01 ... forecastHours48 | dew-point | Number:Temperature | Expected dew-point. Only available in the One Call API | +| forecastHours01 ... forecastHours48 | precip-probability | Number:Dimensionles | Precipitation probability. Only available in the One Call API | + +### One Call API Hourly Forecast + +The One Call API provides hourly forecasts for 48 hours. +The Channel Group IDs for those are `forecastHours01` to `forecastHours48`. +See above for a description of the available channels. ### Daily Forecast @@ -135,7 +188,7 @@ The "3h" value will be divided by three to always have an estimated value for on | forecastToday, forecastTomorrow, forecastDay2, ... forecastDay16 | condition-id | String | Id of the forecasted weather condition. **Advanced** | | forecastToday, forecastTomorrow, forecastDay2, ... forecastDay16 | icon | Image | Icon representing the forecasted weather condition. | | forecastToday, forecastTomorrow, forecastDay2, ... forecastDay16 | icon-id | String | Id of the icon representing the forecasted weather condition. **Advanced** | -| forecastToday, forecastTomorrow, forecastDay2, ... forecastDay16 | apparent-temperature | Number:Temperature | Forecasted apparent temperature. | +| forecastToday, forecastTomorrow, forecastDay2, ... forecastDay16 | apparent-temperature | Number:Temperature | Forecasted apparent temperature. Not available in the One Call API | | forecastToday, forecastTomorrow, forecastDay2, ... forecastDay16 | min-temperature | Number:Temperature | Minimum forecasted temperature of a day. | | forecastToday, forecastTomorrow, forecastDay2, ... forecastDay16 | max-temperature | Number:Temperature | Maximum forecasted temperature of a day. | | forecastToday, forecastTomorrow, forecastDay2, ... forecastDay16 | pressure | Number:Pressure | Forecasted barometric pressure. | @@ -146,7 +199,18 @@ The "3h" value will be divided by three to always have an estimated value for on | forecastToday, forecastTomorrow, forecastDay2, ... forecastDay16 | cloudiness | Number:Dimensionless | Forecasted cloudiness. | | forecastToday, forecastTomorrow, forecastDay2, ... forecastDay16 | rain | Number:Length | Expected rain volume of a day. | | forecastToday, forecastTomorrow, forecastDay2, ... forecastDay16 | snow | Number:Length | Expected snow volume of a day. | - +| forecastToday, forecastTomorrow, forecastDay2, ... forecastDay7 | dew-point | Number:Temperature | Expected dew-point. Only available in the One Call API | +| forecastToday, forecastTomorrow, forecastDay2, ... forecastDay7 | uvindex | Number | Forecasted Midday UV Index. Only available in the One Call API | +| forecastToday, forecastTomorrow, forecastDay2, ... forecastDay7 | precip-probability | Number:Dimensionless | Precipitation probability. Only available in the One Call API | +| forecastToday, forecastTomorrow, forecastDay2, ... forecastDay7 | morning-temperature | Number:Temperature | Expected morning temperature. Only available in the One Call API | +| forecastToday, forecastTomorrow, forecastDay2, ... forecastDay7 | day-temperature | Number:Temperature | Expected day-temperature. Only available in the One Call API | +| forecastToday, forecastTomorrow, forecastDay2, ... forecastDay7 | evening-temperature | Number:Temperature | Expected evening-temperature. Only available in the One Call API | +| forecastToday, forecastTomorrow, forecastDay2, ... forecastDay7 | night-temperature | Number:Temperature | Expected night-temperature. Only available in the One Call API | +| forecastToday, forecastTomorrow, forecastDay2, ... forecastDay7 | apparent-morning | Number:Temperature | Expected apparent temperature in the morning. Only available in the One Call API | +| forecastToday, forecastTomorrow, forecastDay2, ... forecastDay7 | apparent-day | Number:Temperature | Expected apparent temperature in the day. Only available in the One Call API | +| forecastToday, forecastTomorrow, forecastDay2, ... forecastDay7 | apparent-evening | Number:Temperature | Expected apparent temperature in the evening. Only available in the One Call API | +| forecastToday, forecastTomorrow, forecastDay2, ... forecastDay7 | apparent-night | Number:Temperature | Expected apparent temperature in the night. Only available in the One Call API | + ### UV Index | Channel Group ID | Channel ID | Item Type | Description | @@ -154,6 +218,8 @@ The "3h" value will be divided by three to always have an estimated value for on | current, forecastTomorrow, forecastDay2, ... forecastDay7 | time-stamp | DateTime | Date of data observation / forecast. | | current, forecastTomorrow, forecastDay2, ... forecastDay7 | uvindex | Number | Current or forecasted UV Index. | +The `uvindex` channel is also available in the current data and the daily forecast of the One Call API. + ## Full Example ### Things @@ -168,6 +234,15 @@ Bridge openweathermap:weather-api:api "OpenWeatherMap Account" [apikey="AAA", re } ``` +#### One Call API version + +```java +Bridge openweathermap:weather-api:api "OpenWeatherMap Account" [apikey="Add your API key", refreshInterval=60, language="de"] { + Thing onecall local "Local Weather and Forecast" [location="xxx,yyy"] + Thing onecall-history local-history "Local History" [location="xxx,yyy", historyDay=1] +} +``` + ### Items demo.items @@ -240,6 +315,205 @@ Number localForecastTomorrowUVIndex "UV Index for tomorrow [%d]" { channel="open ... ``` +#### One Call API version + +```java +DateTime localLastMeasurement "Timestamp of Last Measurement [%1$tY-%1$tm-%1$tdT%1$tH:%1$tM:%1$tS]"