--- title: "Meteosource Weather API" description: "Meteosource free tier API over HTTPS with your API key: current temperature, wind, precipitation and today's min/max forecast as 8 sensors in TapHome." url: "https://taphome.com/en/compatibility/meteosource/" language: en lastmod: 2026-03-28 generator: hugo ai: topics: ["http","data-service","cloud-api","weather","packet-parser"] questions: ["How to integrate Meteosource weather data with TapHome?","What weather data does the Meteosource TapHome template provide?","How to get a free Meteosource API key for TapHome?","How does the weather type multi-value switch work in TapHome?","Is the Meteosource free tier sufficient for TapHome polling?","How to change the timezone in the Meteosource template?"] --- # Meteosource Weather API Communication: Packet Parser → HTTP - [Meteosource Official Website](https://www.meteosource.com) ## Integration guide Meteosource is a global weather data provider offering current conditions, forecasts and historical data through a REST API. The TapHome template connects to the Meteosource free tier API via HTTPS and reads current weather conditions and today's daily forecast for a configured GPS location. The template provides 8 read-only devices covering weather type, wind speed and direction, current temperature, daily min/max temperatures and precipitation (current and daily). The module polls the API every 5 minutes and caches the full JSON response — individual sensors then read from the cache at faster intervals. The free tier allows 400 calls per day and the template uses approximately 288 calls per day, which is well within the limit. ## Configuration ### Obtaining the API key 1. Register a free account at [meteosource.com/client/sign-up](https://www.meteosource.com/client/sign-up) 2. After registration, the API key is available in the account dashboard 3. Copy the key — it will be needed when importing the template in TapHome > [!TIP] > The free tier provides 400 API calls per day with a rate limit of 10 requests per minute. The TapHome template polls every 5 minutes (288 calls/day), which leaves a comfortable margin. The free tier requires a mention and backlink to Meteosource for commercial use. ### 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` | | `apiKey` | Meteosource API key from account dashboard | `abc123def456...` | To find the coordinates for a location, right-click on [Google Maps](https://maps.google.com) and select the coordinates from the context menu. ### Module variables After importing the template, one variable can be adjusted in the module settings: | Variable | Description | Default | |----------|-------------|---------| | `tz` | Timezone in tzinfo format | `Europe/Prague` | The timezone determines how timestamps in the API response are interpreted. Users outside the CET/CEST timezone should change this value to match their location (e.g. `America/New_York`, `Asia/Tokyo`, `UTC`). ### API endpoint The module connects to `www.meteosource.com` over HTTPS (port 443) and calls: ``` GET /api/v1/free/point?lat={lat}&lon={lon}§ions=current,daily&timezone={tz}&language=en&units=ca&key={apiKey} ``` The template uses the `ca` (Canadian) unit system: Celsius for temperature, km/h for wind speed, mm for precipitation and hPa for pressure. ## Device capabilities ### Weather type The **Weather Type** device is a multi-value switch that maps the Meteosource `icon_num` field (values 1--36) to 7 TapHome weather categories: | Switch Value | Category | Meteosource icons (day) | Meteosource icons (night) | |-------------|----------|-------------------------|---------------------------| | 0 | Clear / Sunny | 2, 3, 4, 5 | 26, 27, 28 | | 1 | Clouds / Overcast | 6, 7, 8 | 29, 30, 31 | | 2 | Rain | 11, 12, 13, 25 | 32, 34, 35, 36 | | 3 | Drizzle / Light rain | 10 | -- | | 4 | Thunderstorm | 14, 15 | 33 | | 5 | Snow / Freezing | 16--24 | -- | | 6 | Fog | 9 | -- | If the icon number is 1 or unrecognized, the switch defaults to 1 (Clouds). The weather type is polled every 30 minutes. ### Temperature Three temperature devices provide current and forecast data: - **Temperature** -- current air temperature at 2m height in Celsius. Uses a dedicated temperature sensor device type with error reporting if the API response is unavailable - **Temperature Max** -- today's forecast maximum temperature in Celsius, read from the daily forecast section (`daily.data[0]`) - **Temperature Min** -- today's forecast minimum temperature in Celsius, read from the daily forecast section (`daily.data[0]`) ### Wind - **Wind Speed** -- current wind speed at 10m height in km/h (using the `ca` unit system). Reports an error if the cached response is unavailable - **Wind Direction** -- wind direction in degrees (0--360, where 0/360 = North, 90 = East, 180 = South, 270 = West). This is the fastest-polled device at 15-second intervals, reading from the cached response ### Precipitation - **Precipitation (1-hour)** -- current precipitation amount in mm. Reports an error if the cached response is unavailable - **Precipitation (Daily)** -- today's total daily forecast precipitation in mm, read from the daily forecast section ### Additional capabilities The Meteosource API also exposes feels-like temperature, wind gusts, cloud cover, atmospheric pressure, humidity, visibility, UV index, dew point, wind chill, precipitation type and a text weather summary for current conditions. An air quality endpoint with PM10, PM2.5, NO2, CO, O3 and AQI is available separately. 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 `www.meteosource.com` 2. Check that the API key is valid and has not been regenerated 3. Confirm the latitude and longitude values are correct decimal coordinates 4. New API keys may require a few minutes to activate after registration ### Stale or delayed readings The module polls the Meteosource API every 5 minutes and stores the response in a cache variable. Individual sensors read from this cache at faster intervals (15 seconds to 1 minute). If the API call fails, all sensors continue returning their last cached values until the next successful poll. > [!WARNING] > The Meteosource API is a cloud service that requires an active internet connection on the TapHome Core. During internet outages or API downtime, the template will not receive updated weather data. The default timezone is `Europe/Prague` -- users in other regions must change the `tz` module variable for correct local timestamps. ## Available devices 8 These devices appear in TapHome after import. Meteosource Module Custom Variables | | | |-------------------------------|-------------------------------------------------------------------------------------------| | `apiKey` (string) | Meteosource API key for authentication (obtain from meteosource.com dashboard) | | `lat` (string) | Geographic latitude of the weather location in decimal degrees (set during import) | | `lon` (string) | Geographic longitude of the weather location in decimal degrees (set during import) | | `tz` (string) = Europe/Prague | IANA timezone identifier for timestamp conversion (e.g. Europe/Prague, America/New\_York) | Read (module) ```taphome VAR request := HTTPREQUEST( "/api/v1/free/point?lat=" + lat + "&lon=" + lon + "§ions=current,daily&timezone=" + tz + "&language=en&units=ca&key=" + apiKey, "GET" ); VAR response := SENDHTTPREQUEST(request); VAR responseHeaders := response.Headers; IF response.IsSuccess responseJson := response.Content; END ``` Weather Type Multi-value Switch Read-only Weather condition as multi-value switch — Clear, Clouds, Rain, Drizzle, Thunderstorm, Snow, Fog integer → mapped Unit: category JSON parsejson() Values / States: ${weather\_clear} · ${weather\_clouds} · ${weather\_rain} · ${weather\_drizzle} · ${weather\_thunderstorm} · ${weather\_snow} · ${weather\_fog} Read switch state ```taphome IF(ISNULL(responseJson) | responseJson = "error") return(NaN); END VAR weather := PARSEJSON(responseJson, "current.icon_num"); SWITCH(weather, 2, 0, 3, 0, 4, 0,26,0, 27,0,28,0, 5, 0, 6, 1, 7, 1, 8,1,29,1,30,1,31,1, 11,2,12,2,13,2,25,2,32,2,34,2,35,2,36,2, 10,3, 16,5,17,5,18,5,19,5,20,5,21,5,22,5,23,5,24,5, 14,4,15,4,33,4, 9,6, 1); ``` Wind Speed Variable Read-only numeric Unit: km/h JSON parsejson() Read ```taphome IF( ISNULL(responseJson) | responseJson = "error", NaN, TODOUBLE(PARSEJSON(responseJson, "current.wind.speed")) ); ``` Read (module) ```taphome IF(ISNULL(responseJson) | responseJson = "error", ADDERROR("Failed to read data ")); ``` Wind Direction Variable Read-only Wind direction in degrees — 0/360 = North, 90 = East, 180 = South, 270 = West numeric Unit: ° JSON parsejson() Read ```taphome IF( ISNULL(responseJson) | responseJson = "error", NaN, TODOUBLE(PARSEJSON(responseJson, "current.wind.angle")) ) ``` Temperature Temperature Sensor Read-only numeric Unit: °C JSON parsejson() Read (module) ```taphome IF(ISNULL(responseJson) | responseJson = "error", ADDERROR("Failed to read data ")); ``` Read temperature ```taphome IF(ISNULL(responseJson) | responseJson = "error", NaN, TODOUBLE(PARSEJSON(responseJson,"current.temperature"))) ``` Temperature Max Variable Read-only Today's forecast maximum temperature from the daily forecast section numeric Unit: °C JSON parsejson() Read ```taphome IF(ISNULL(responseJson) | responseJson = "error", NaN, TODOUBLE(PARSEJSON(responseJson,"daily.data[0].all_day.temperature_max"))) ``` Temperature Min Variable Read-only Today's forecast minimum temperature from the daily forecast section numeric Unit: °C JSON parsejson() Read ```taphome IF(ISNULL(responseJson) | responseJson = "error", NaN, TODOUBLE(PARSEJSON(responseJson,"daily.data[0].all_day.temperature_min"))) ``` Precipitation (1-hour) Variable Read-only numeric Unit: mm JSON parsejson() Read ```taphome IF(ISNULL(responseJson) | responseJson = "error", NaN, TODOUBLE(PARSEJSON(responseJson,"current.precipitation.total"))) ``` Read (module) ```taphome IF(ISNULL(responseJson) | responseJson = "error", ADDERROR("Failed to read data ")); ``` Precipitation (Daily) Variable Read-only Today's total daily forecast precipitation from the daily forecast section numeric Unit: mm JSON parsejson() Read ```taphome IF(ISNULL(responseJson) | responseJson = "error", NaN, TODOUBLE(PARSEJSON(responseJson,"daily.data[0].all_day.precipitation.total"))) ``` **Connection:** Packet Parser → HTTP Possible improvements (12) - Feels Like Temperature — Perceived temperature accounting for wind chill and humidity. Float, Celsius with ca units - Wind Gusts — Peak wind gust speed at 10m. Float, km/h with ca units - Cloud Cover — Total cloud cover percentage. Integer, 0–100% - Atmospheric Pressure — Sea level atmospheric pressure. Float, hPa with ca units - Relative Humidity — Relative humidity. Integer, 0–100% - Visibility — Visibility distance. Float, km with ca units - UV Index — UV radiation index. Float, 0–11+ scale - Dew Point — Dew point temperature. Float, Celsius with ca units - Wind Chill — Wind chill temperature. Float, Celsius with ca units - Precipitation Type — Type of precipitation — none, rain, snow, rain\_snow, ice\_pellets, frozen\_rain. String value - Weather Summary — Human-readable text description of current weather. Translated per language parameter - Air Quality Index — Requires separate /air\_quality endpoint. Includes PM10, PM2.5, NO2, CO, O3, AQI (1–6 scale). Not available via Point endpoint ## Import parameters Enter these values when you import the XML. | Asked in the app | Default | |---------------------|-----------| | latitude | `48.1778` | | longitude | `17.1426` | | Meteosource API key | `apiKey` | ## Sources - Meteosource — Main Website & Pricing [www.meteosource.com](https://www.meteosource.com/pricing) 2026-03-28 - Meteosource — API Documentation [www.meteosource.com](https://www.meteosource.com/documentation) 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/)