Skip to content

Commit ebb0f54

Browse files
florian-h05florian-h05
authored
[openweathermap] Prepare for shutdown of One Call API version 2.5 (openhab#16705)
* [openweathermap] Update README for shutdown of One Call API version 2.5 & Change default API version Closes openhab#16665. Signed-off-by: Florian Hotze <[email protected]>
1 parent 5567d96 commit ebb0f54

File tree

3 files changed

+27
-22
lines changed

3 files changed

+27
-22
lines changed

‎bundles/org.openhab.binding.openweathermap/README.md

+24-19
Original file line numberDiff line numberDiff line change
@@ -30,20 +30,26 @@ You can add as much `air-pollution` things for different locations to your setup
3030

3131
#### One Call API Version
3232

33-
New Subscribers to the One Call API will require setting the API version to 3.0 (The API key will not work with 2.5). Existing subscribers can continue to use their existing API key with version 2.5.
33+
New users of the One Call API will require setting the API version to 3.0 (the API key will not work with 2.5) and **existing users have to switch to API version 3.0 before June 2024**.
34+
One Call API version 2.5 is shutting down in June 2024.
3435

35-
One Call API Version 3.0 [requires payment details](https://openweathermap.org/price) for future forecast information. However, it is possible to set a [daily API call limit to 1000](https://openweathermap.org/faq#onecall), which will avoid charges.
36+
To switch to One Call API version 3.0, [log in](https://home.openweathermap.org/users/sign_in) to your OpenWeatherMap account and provide payment details.
37+
Remember to set the [daily API call limit to 1000](https://openweathermap.org/faq#onecall) to avoid charges.
38+
Finally, configure the [OpenWeatherMap Account](#openweathermap-account) Thing to use API version 3.0.
39+
40+
One Call API Version 3.0 [requires payment details](https://openweathermap.org/price) for future forecast information.
41+
However, it is possible to set a [daily API call limit to 1000](https://openweathermap.org/faq#onecall), which will avoid charges.
3642

3743
### One Call API Weather and Forecast
3844

39-
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.
45+
The thing `onecall` supports the [current and forecast weather data](https://openweathermap.org/api/one-call-3#current) for a specific location using the One Call API.
4046
It requires coordinates of the location of your interest.
4147
You can add as many `onecall` things for different locations to your setup as you like to observe.
4248
It also supports persisting forecast data using time series support, please read [Persisting Time Series](#persisting-time-series).
4349

4450
### One Call API History Data
4551

46-
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.
52+
The thing `onecall-history` supports the [historical weather data](https://openweathermap.org/api/one-call-3#history) for a specific location using the One Call API.
4753
It requires coordinates of the location of your interest.
4854
You can add as many `onecall-history` things for different locations to your setup as you like to observe.
4955
For every day in history you have to create a different thing.
@@ -61,16 +67,16 @@ Once the system location will be changed, the background discovery updates the c
6167
|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
6268
| apikey | API key to access the OpenWeatherMap API. **Mandatory** |
6369
| refreshInterval | Specifies the refresh interval (in minutes). Optional, the default value is 60, the minimum value is 1. |
64-
| apiVersion | Set API version to use, new generated OpenWeather accounts may use 3.0, older can try 2.5. Valid values are: `2.5`, `3.0`. |
70+
| apiVersion | Set API version to use, new OpenWeather accounts have to use 3.0, older have to switch to 3.0 before June 2024. Valid values are: `2.5`, `3.0`. |
6571
| language | Language to be used by the OpenWeatherMap API. Optional, valid values are: `ar`, `bg`, `ca`, `de`, `el`, `en`, `es`, `fa`, `fi`, `fr`, `gl`, `hr`, `hu`, `it`, `ja`, `kr`, `la`, `lt`, `mk`, `nl`, `pl`, `pt`, `ro`, `ru`, `se`, `sk`, `sl`, `tr`, `ua`, `vi`, `zh_cn`, `zh_tw`. |
6672

6773
### Current Weather And Forecast
6874

69-
| Parameter | Description |
70-
|----------------|--------------------------------------------------------------------------------------------------------------------------------|
71-
| location | Location of weather in geographical coordinates (latitude/longitude/altitude). **Mandatory** |
72-
| forecastHours | Number of hours for hourly forecast. Optional, the default value is 12 (min="0", max="120", step="3"). |
73-
| forecastDays | Number of days for daily forecast (including todays forecast). Optional, the default value is 6 (min="0", max="16", step="1"). |
75+
| Parameter | Description |
76+
|---------------|---------------------------------------------------------------------------------------------------------------------------------|
77+
| location | Location of weather in geographical coordinates (latitude/longitude/altitude). **Mandatory** |
78+
| forecastHours | Number of hours for hourly forecast. Optional, the default value is 12 (min="0", max="120", step="3"). |
79+
| forecastDays | Number of days for daily forecast (including today's forecast). Optional, the default value is 6 (min="0", max="16", step="1"). |
7480

7581
Once the parameters `forecastHours` or `forecastDays` will be changed, the available channel groups on the thing will be created or removed accordingly.
7682

@@ -85,13 +91,13 @@ Once the parameter `forecastHours` will be changed, the available channel groups
8591

8692
### One Call API Weather and Forecast
8793

88-
| Parameter | Description |
89-
|-----------------|---------------------------------------------------------------------------------------------------------------------------------------|
90-
| location | Location of weather in geographical coordinates (latitude/longitude/altitude). **Mandatory** |
91-
| forecastMinutes | Number of minutes for minutely precipitation forecast as minutely channels. Optional, the default value is 0 (min="0", max="60"). |
92-
| forecastHours | Number of hours for hourly forecast as hourly channels. Optional, the default value is 12 (min="0", max="48"). |
93-
| forecastDays | Number of days for daily forecast (including todays forecast) as daily channels. Optional, the default value is 6 (min="0", max="8"). |
94-
| numberOfAlerts | Number of alerts to be shown. Optional, the default value is 0 (min="0", max="5"). |
94+
| Parameter | Description |
95+
|-----------------|----------------------------------------------------------------------------------------------------------------------------------------|
96+
| location | Location of weather in geographical coordinates (latitude/longitude/altitude). **Mandatory** |
97+
| forecastMinutes | Number of minutes for minutely precipitation forecast as minutely channels. Optional, the default value is 0 (min="0", max="60"). |
98+
| forecastHours | Number of hours for hourly forecast as hourly channels. Optional, the default value is 12 (min="0", max="48"). |
99+
| forecastDays | Number of days for daily forecast (including today's forecast) as daily channels. Optional, the default value is 6 (min="0", max="8"). |
100+
| numberOfAlerts | Number of alerts to be shown. Optional, the default value is 0 (min="0", max="5"). |
95101

96102
Set `forecastMinutes`, `forecastHours` and `forecastDays` to `0` if you only want to use the channels with time series support.
97103
In a future release, this will become the default setting as usage of the time series channels instead is encouraged.
@@ -288,11 +294,10 @@ Bridge openweathermap:weather-api:api "OpenWeatherMap Account" [apikey="AAA", re
288294
#### One Call API Version
289295

290296
```java
291-
Bridge openweathermap:weather-api:api "OpenWeatherMap Account" [apikey="Add your API key", refreshInterval=60, language="de", apiVersion="2.5"] {
297+
Bridge openweathermap:weather-api:api "OpenWeatherMap Account" [apikey="Add your API key", refreshInterval=60, language="de", apiVersion="3.0"] {
292298
Thing onecall local "Local Weather and Forecast" [location="xxx,yyy"]
293299
Thing onecall-history local-history "Local History" [location="xxx,yyy", historyDay=1]
294300
}
295-
If you create a new OpenWeather account, you maybe need to set the api version to 3.0.
296301
```
297302

298303
### Items

‎bundles/org.openhab.binding.openweathermap/src/main/resources/OH-INF/config/config.xml

+2-2
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,8 @@
1313
</parameter>
1414
<parameter name="apiVersion" type="text">
1515
<label>One Call API Version</label>
16-
<description>One Call API version (defaults to 2.5, version 3.0 is available, but needs different subscription).</description>
17-
<default>2.5</default>
16+
<description>One Call API version (defaults to 3.0, version 2.5 is to be closed in June 2024).</description>
17+
<default>3.0</default>
1818
<options>
1919
<option value="2.5">2.5</option>
2020
<option value="3.0">3.0</option>

‎bundles/org.openhab.binding.openweathermap/src/main/resources/OH-INF/i18n/openweathermap.properties

+1-1
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,7 @@ thing-type.openweathermap.weather-api.description = Provides access to the OpenW
6363
# thing types config
6464

6565
bridge-type.config.openweathermap.weather-api.apiVersion.label = One Call API Version
66-
bridge-type.config.openweathermap.weather-api.apiVersion.description = One Call API version (defaults to 2.5, version 3.0 is available, but needs different subscription).
66+
bridge-type.config.openweathermap.weather-api.apiVersion.description = One Call API version (defaults to 3.0, version 2.5 is to be closed in June 2024).
6767
bridge-type.config.openweathermap.weather-api.apikey.label = API Key
6868
bridge-type.config.openweathermap.weather-api.apikey.description = API key to access the OpenWeatherMap API.
6969
bridge-type.config.openweathermap.weather-api.language.label = Language

0 commit comments

Comments
 (0)