--- title: "OpenWeather" description: "Free OpenWeather (OpenWeatherMap) API in TapHome: current weather plus 3-hour and 24-hour forecasts of temperature, humidity, pressure and wind." url: "https://taphome.com/en/compatibility/openweather/" language: en lastmod: 2026-03-28 generator: hugo ai: topics: ["http","data-service","cloud-api","weather","packet-parser"] questions: ["How to integrate OpenWeather with TapHome?","What does the OpenWeather TapHome template provide?","How to get a free OpenWeather API key for TapHome?","What weather data does TapHome read from OpenWeather?","How does the weather condition multi-value switch work in TapHome?","Is the OpenWeather API free to use with TapHome?"] --- # OpenWeather Communication: Packet Parser → HTTP - [OpenWeather Official Website](https://openweathermap.org/) ## Integration guide OpenWeather is a weather data provider offering global weather information through a REST API. The TapHome template connects to the free OpenWeather API v2.5 via HTTPS and reads current weather conditions, a 3-hour forecast and a 24-hour forecast for a configured location. The template makes two API calls every 5 minutes — one for current weather and one for the 5-day/3-hour forecast. It provides 18 read-only devices covering air temperature, feels-like temperature, humidity, atmospheric pressure, visibility, wind speed and weather conditions. All temperatures are in Celsius (metric units) and no paid subscription is required. ## Configuration ### Obtaining the API key 1. Register a free account at [openweathermap.org](https://home.openweathermap.org/users/sign_up) — no credit card required 2. After registration, the API key (APPID) is sent via confirmation email 3. The key is also available on the account page under the **API key** tab 4. New keys activate automatically, typically within 10 minutes to 2 hours > [!TIP] > The free tier allows 60 calls per minute and 1,000,000 calls per month. The TapHome template makes approximately 576 calls per day (2 calls every 5 minutes), which is well within the free limits. ### Import parameters When importing the template in TapHome, three parameters are required: | Parameter | Description | Example | |-----------|-------------|---------| | `latitude` | Location latitude in decimal degrees | `48.1778` | | `longitude` | Location longitude in decimal degrees | `17.1426` | | `appid` | OpenWeather API key from account dashboard | `a1b2c3d4e5f6...` | To find the coordinates for a location, right-click on [Google Maps](https://maps.google.com) and select the coordinates from the context menu. ### API endpoints The module connects to `api.openweathermap.org` over HTTPS (port 443) and calls two endpoints per poll cycle: ``` GET /data/2.5/weather?units=metric&lat={latitude}&lon={longitude}&appid={AppId} GET /data/2.5/forecast?units=metric&lat={latitude}&lon={longitude}&appid={AppId}&cnt=9 ``` The first request returns current weather conditions. The second returns a forecast list where `list[0]` is the next 3-hour slot and `list[8]` is the +24-hour slot (8 x 3h = 24h). ## Device capabilities The template exposes 18 read-only devices organized into three groups: current weather (6 devices), 3-hour forecast (6 devices) and 24-hour forecast (6 devices). Each group provides the same six measurements. ### Temperature and humidity - **Current Air Temperature** — current temperature in Celsius with humidity as a secondary value (API returns 0--100%, converted to 0--1 ratio for TapHome) - **Current Feels Like Temperature** — apparent temperature accounting for wind chill and humidity. The humidity capability is disabled (returns NaN) — only the temperature value is used - **Forecast (+3h) Air Temperature** — temperature and humidity for the next 3-hour forecast slot. Includes a **Forecast Date** service attribute showing the timestamp of the data point - **Forecast (+3h) Feels Like Temperature** — apparent temperature for the next 3-hour slot - **Forecast (+24h) Air Temperature** — temperature and humidity for the +24h forecast slot. Includes a **Forecast Date** service attribute - **Forecast (+24h) Feels Like Temperature** — apparent temperature for the +24h slot ### Atmospheric pressure and visibility - **Current Air Pressure** — atmospheric pressure in hPa - **Current Visibility** — visibility distance in meters (maximum 10,000 m) - **Forecast (+3h) Air Pressure** — atmospheric pressure for the next 3-hour slot - **Forecast (+3h) Visibility** — visibility for the 3-hour forecast - **Forecast (+24h) Air Pressure** — atmospheric pressure for the +24h slot - **Forecast (+24h) Visibility** — visibility for the 24-hour forecast > [!WARNING] > The Forecast (+3h) Visibility and Forecast (+24h) Visibility devices have their data indices swapped in the current template version. The +3h device reads from list[8] (the 24h position) and the +24h device reads from list[0] (the 3h position). The values are reversed until this is corrected in a future template update. ### Wind speed - **Current Wind Speed** — wind speed in m/s - **Forecast (+3h) Wind Speed** — wind speed for the next 3-hour slot - **Forecast (+24h) Wind Speed** — wind speed for the +24h slot ### Weather conditions Three multi-value switch devices display the weather condition category: - **Current Weather** — current weather condition - **Forecast (+3h) Weather** — weather condition for the next 3-hour slot - **Forecast (+24h) Weather** — weather condition for the +24h slot Each weather device maps the API `weather[0].main` field to one of 7 categories: | Switch Value | Label | API weather groups | |-------------|-------|--------------------| | 0 | Clear | Clear | | 1 | Clouds | Clouds | | 2 | Rain | Rain | | 3 | Drizzle | Drizzle | | 4 | Thunderstorm | Thunderstorm | | 5 | Snow | Snow | | 6 | Atmosphere | Mist, Smoke, Haze, Dust, Fog, Sand, Ash, Squall, Tornado | If the API returns an unrecognized weather group, the switch defaults to 0 (Clear). Switch values 7, 8 and 9 are defined in the template configuration but have no mapping in the script logic — they are unused placeholders. ### Additional capabilities The OpenWeather API also provides wind direction, wind gusts, cloudiness percentage, rain and snow volume (1h), and sunrise/sunset times. Humidity is only exposed as a secondary value on temperature sensors, not as a standalone device. These can be added in a future template update. ## Troubleshooting ### All devices show NaN or no data 1. Verify that the TapHome Core has internet access — the template requires outbound HTTPS connectivity to `api.openweathermap.org` 2. Check that the API key is valid — open `https://api.openweathermap.org/data/2.5/weather?lat=48.18&lon=17.14&appid=YOUR_KEY&units=metric` in a browser to test 3. New API keys may take up to 2 hours to activate after registration 4. Confirm the latitude and longitude values are correct decimal coordinates (not degrees/minutes/seconds) ### Forecast data seems incorrect The forecast API returns data in 3-hour intervals. The +3h devices read the first forecast slot (`list[0]`), which is the next available 3-hour block — not exactly 3 hours from now. Similarly, the +24h devices read `list[8]` (the 9th slot), which represents approximately 24 hours ahead. Note the visibility index swap described in the warning above — if the +3h and +24h visibility values seem exchanged, this is the known template bug. ### Device name typo Device #17 in the template is named "Forecast (+24h)Weather" (missing space before "Weather"). This is a cosmetic issue in the template XML and does not affect functionality. The device is displayed correctly in the TapHome device table using its enriched name. ## Available devices 18 These devices appear in TapHome after import. OpenWeather Module Custom Variables | | | |----------------------|---------------------------------------------------------------------------------------------| | `longitude` (string) | Geographic longitude of the weather station location in decimal degrees (set during import) | | `latitude` (string) | Geographic latitude of the weather station location in decimal degrees (set during import) | | `AppId` (string) | OpenWeather API key (obtain free key at openweathermap.org/api) | Read (module) ```taphome responseJson := "error"; Daily := "error"; VAR path := "data/2.5/weather?units=metric&lat=" + latitude + "&lon=" + longitude + "&appid=" + AppId; VAR response := SENDHTTPREQUEST(path); IF response.IsSuccess responseJson := response.Content; ELSE VAR contentJson := response.Content; VAR errCode := response.StatusCode; VAR message := PARSEJSON(contentJson, "message"); #ADDERROR("Failed to read data - (" + errCode + ") " + message); END path := "data/2.5/forecast?units=metric&lat=" + latitude + "&lon=" + longitude + "&appid=" + AppId + "&cnt=9"; response := SENDHTTPREQUEST(path); IF response.IsSuccess Daily := response.Content; ELSE contentJson := response.Content; errCode := response.StatusCode; message := PARSEJSON(contentJson, "message"); #ADDERROR("Failed to read data - (" + errCode + ") " + message); END ``` Current Air Pressure Variable Read-only numeric Unit: hPa json\_path Read ```taphome IF(ISNULL(responseJson) | responseJson = "error", NaN, PARSEJSON(responseJson,"main.pressure")) ``` Read (module) ```taphome IF(ISNULL(responseJson) | responseJson = "error", ADDERROR("Failed to read data ")); ``` Current Air Temperature Temperature Sensor Read-only Current temperature and humidity — humidity is divided by 100 (API returns 0–100%, TapHome expects 0–1 ratio) numeric Unit: °C json\_path Read humidity ```taphome IF(ISNULL(responseJson) | responseJson = "error", NaN, PARSEJSON(responseJson,"main.humidity") / 100) ``` Read (module) ```taphome IF(ISNULL(responseJson) | responseJson = "error", ADDERROR("Failed to read data ")); ``` Read temperature ```taphome IF(ISNULL(responseJson) | responseJson = "error", NaN, PARSEJSON(responseJson,"main.temp")) ``` Current Feels Like Temperature Temperature Sensor Read-only Apparent temperature accounting for wind chill and humidity — humidity capability is disabled (returns NaN) numeric Unit: °C json\_path Read humidity ```taphome NaN ``` Read (module) ```taphome IF(ISNULL(responseJson) | responseJson = "error", ADDERROR("Failed to read data ")); ``` Read temperature ```taphome IF(ISNULL(responseJson) | responseJson = "error", NaN, PARSEJSON(responseJson,"main.feels_like")) ``` Current Visibility Variable Read-only Visibility distance in meters (maximum 10,000 m) numeric Unit: m json\_path Read ```taphome IF(ISNULL(responseJson) | responseJson = "error", NaN, PARSEJSON(responseJson,"visibility")) ``` Read (module) ```taphome IF(ISNULL(responseJson) | responseJson = "error", ADDERROR("Failed to read data ")); ``` Current Weather Multi-value Switch Read-only Weather condition as multi-value switch — Clear, Clouds, Rain, Drizzle, Thunderstorm, Snow, Atmosphere string multi\_value\_switch Values / States: Clear · Clouds · Rain · Drizzle · Thunderstorm · Snow · Atmosphere Read switch state ```taphome IF(ISNULL(responseJson) | responseJson = "error") return(NaN); END VAR weather := PARSEJSON(responseJson, "weather[0].main"); SWITCH(weather, "Clear", 0, "Clouds", 1, "Rain", 2, "Drizzle", 3, "Thunderstorm", 4, "Snow", 5, "Mist", 6, "Smoke", 6, "Haze", 6, "Dust", 6, "Fog", 6, "Sand", 6, "Ash", 6, "Squall", 6, "Tornado", 6, 0); ``` Read (module) ```taphome IF(ISNULL(responseJson) | responseJson = "error", ADDERROR("Failed to read data ")); ``` Current Wind Speed Variable Read-only numeric Unit: m/s json\_path Read ```taphome IF(ISNULL(responseJson) | responseJson = "error", NaN, PARSEJSON(responseJson,"wind.speed")) ``` Read (module) ```taphome IF(ISNULL(responseJson) | responseJson = "error", ADDERROR("Failed to read data ")); ``` Forecast (+3h) Air Pressure Variable Read-only numeric Unit: hPa json\_path Read ```taphome IF(ISNULL(Daily) | Daily = "error", NaN, PARSEJSON(Daily,"$.list[0].main.pressure")) ``` Read (module) ```taphome IF(ISNULL(responseJson) | responseJson = "error", ADDERROR("Failed to read data ")); ``` Forecast (+3h) Air Temperature Temperature Sensor Read-only Temperature and humidity for the next 3-hour forecast slot — includes Forecast Date service attribute numeric Unit: °C json\_path Service Attributes | | | |---------------|------------------------------------------------------------------| | Forecast Date | Timestamp of the forecast data point (dt\_txt from API response) | Read humidity ```taphome IF(ISNULL(Daily) | Daily = "error", NaN, PARSEJSON(Daily,"$.list[0].main.humidity") / 100) ``` Read (module) ```taphome IF(ISNULL(Daily) | Daily = "error", ADDERROR("Failed to read data ")); ``` Read temperature ```taphome IF(ISNULL(Daily) | Daily = "error", NaN, PARSEJSON(Daily,"$.list[0].main.temp")) ``` Service Attributes Forecast Date ```taphome IF(ISNULL(Daily) | Daily = "error", NaN, PARSEJSON(Daily,"$.list[0].dt_txt")) ``` Forecast (+3h) Feels Like Temperature Temperature Sensor Read-only Apparent temperature for the next 3-hour forecast slot — humidity capability is disabled (returns NaN) numeric Unit: °C json\_path Read humidity ```taphome NaN ``` Read (module) ```taphome IF(ISNULL(responseJson) | responseJson = "error", ADDERROR("Failed to read data ")); ``` Read temperature ```taphome IF(ISNULL(Daily) | Daily = "error", NaN, PARSEJSON(Daily,"$.list[0].main.feels_like")) ``` Forecast (+3h) Visibility Variable Read-only Known issue: reads from list\[8] instead of list\[0] — visibility values are swapped with Forecast (+24h) numeric Unit: m json\_path Read ```taphome IF(ISNULL(Daily) | Daily = "error", NaN, PARSEJSON(Daily,"$.list[8].visibility")) ``` Read (module) ```taphome IF(ISNULL(responseJson) | responseJson = "error", ADDERROR("Failed to read data ")); ``` Forecast (+3h) Weather Multi-value Switch Read-only Weather condition for the next 3-hour forecast slot — same 7-category mapping as Current Weather string multi\_value\_switch Values / States: Clear · Clouds · Rain · Drizzle · Thunderstorm · Snow · Atmosphere Read switch state ```taphome IF(ISNULL(Daily) | Daily = "error") return(NaN); END VAR weather := PARSEJSON(Daily, "$.list[0].weather[0].main"); SWITCH(weather, "Clear", 0, "Clouds", 1, "Rain", 2, "Drizzle", 3, "Thunderstorm", 4, "Snow", 5, "Mist", 6, "Smoke", 6, "Haze", 6, "Dust", 6, "Fog", 6, "Sand", 6, "Ash", 6, "Squall", 6, "Tornado", 6, 0); ``` Read (module) ```taphome IF(ISNULL(Daily) | Daily = "error", ADDERROR("Failed to read data ")); ``` Forecast (+3h) Wind Speed Variable Read-only numeric Unit: m/s json\_path Read ```taphome IF(ISNULL(Daily) | Daily = "error", NaN, PARSEJSON(Daily,"$.list[0].wind.speed")) ``` Read (module) ```taphome IF(ISNULL(responseJson) | responseJson = "error", ADDERROR("Failed to read data ")); ``` Forecast (+24h) Air Pressure Variable Read-only numeric Unit: hPa json\_path Read ```taphome IF(ISNULL(Daily) | Daily = "error", NaN, PARSEJSON(Daily,"$.list[8].main.pressure")) ``` Read (module) ```taphome IF(ISNULL(responseJson) | responseJson = "error", ADDERROR("Failed to read data ")); ``` Forecast (+24h) Air Temperature Temperature Sensor Read-only Temperature and humidity for the +24h forecast slot — includes Forecast Date service attribute numeric Unit: °C json\_path Service Attributes | | | |---------------|------------------------------------------------------------------| | Forecast Date | Timestamp of the forecast data point (dt\_txt from API response) | Read humidity ```taphome IF(ISNULL(Daily) | Daily = "error", NaN, PARSEJSON(Daily,"$.list[8].main.humidity") / 100) ``` Read (module) ```taphome IF(ISNULL(Daily) | Daily = "error", ADDERROR("Failed to read data ")); ``` Read temperature ```taphome IF(ISNULL(Daily) | Daily = "error", NaN, PARSEJSON(Daily,"$.list[8].main.temp")) ``` Service Attributes Forecast Date ```taphome IF(ISNULL(Daily) | Daily = "error", NaN, PARSEJSON(Daily,"$.list[8].dt_txt")) ``` Forecast (+24h) Feels Like Temperature Temperature Sensor Read-only Apparent temperature for the +24h forecast slot — humidity capability is disabled (returns NaN) numeric Unit: °C json\_path Read humidity ```taphome NaN ``` Read (module) ```taphome IF(ISNULL(responseJson) | responseJson = "error", ADDERROR("Failed to read data ")); ``` Read temperature ```taphome IF(ISNULL(Daily) | Daily = "error", NaN, PARSEJSON(Daily,"$.list[8].main.feels_like")) ``` Forecast (+24h) Visibility Variable Read-only Known issue: reads from list\[0] instead of list\[8] — visibility values are swapped with Forecast (+3h) numeric Unit: m json\_path Read ```taphome IF(ISNULL(Daily) | Daily = "error", NaN, PARSEJSON(Daily,"$.list[0].visibility")) ``` Read (module) ```taphome IF(ISNULL(responseJson) | responseJson = "error", ADDERROR("Failed to read data ")); ``` Forecast (+24h) Wind Speed Variable Read-only numeric Unit: m/s json\_path Read ```taphome IF(ISNULL(Daily) | Daily = "error", NaN, PARSEJSON(Daily,"$.list[8].wind.speed")) ``` Forecast (+24h) Weather Multi-value Switch Read-only Weather condition for the +24h forecast slot — same 7-category mapping as Current Weather string multi\_value\_switch Values / States: Clear · Clouds · Rain · Drizzle · Thunderstorm · Snow · Atmosphere Read switch state ```taphome IF(ISNULL(Daily) | Daily = "error") return(NaN); END VAR weather := PARSEJSON(Daily, "$.list[8].weather[0].main"); SWITCH(weather, "Clear", 0, "Clouds", 1, "Rain", 2, "Drizzle", 3, "Thunderstorm", 4, "Snow", 5, "Mist", 6, "Smoke", 6, "Haze", 6, "Dust", 6, "Fog", 6, "Sand", 6, "Ash", 6, "Squall", 6, "Tornado", 6, 0); ``` **Connection:** Packet Parser → HTTP Possible improvements (7) - Current Humidity (standalone) — Humidity is only exposed as secondary value on temperature sensors, not as standalone device - Wind Direction — Wind direction in degrees available in API but not implemented in template - Wind Gust — Wind gust speed available in API but not implemented in template - Cloudiness — Cloudiness percentage available in API but not implemented - Rain Volume (1h) — Rain volume for last 1 hour in mm, available in API - Snow Volume (1h) — Snow volume for last 1 hour in mm, available in API - Sunrise / Sunset — Unix timestamps for sunrise and sunset available in API ## Import parameters Enter these values when you import the XML. | Asked in the app | Default | |----------------------------|-----------| | latitude | `48.1778` | | longitude | `17.1426` | | OpenWeather application id | `appid` | ## Sources - Current Weather Data API 2.5 [openweathermap.org](https://openweathermap.org/current) 2026-03-28 - 5 Day / 3 Hour Forecast API [openweathermap.org](https://openweathermap.org/forecast5) 2026-03-28 - Weather Condition Codes [openweathermap.org](https://openweathermap.org/weather-conditions) 2026-03-28 - API Key Setup Guide [openweathermap.org](https://openweathermap.org/appid) 2026-03-28 ## Related Documentation - [Packet Parser Integration](https://taphome.com/en/compatibility/packet-parser-guide/) - [Packet Parser (HTTP, TCP, UDP, FTP, MQTT)](https://taphome.com/en/docs/integration/packet-parser/) - [Packet parser functions](https://taphome.com/en/docs/script/packet-parser/) - [Parsing functions](https://taphome.com/en/docs/script/parsing-functions/)