Expand description
Current weather
This block displays local weather and temperature information. In order to use this block, you will need access to a supported weather API service. At the time of writing, OpenWeatherMap, met.no, and the US National Weather Service are supported.
Configuring this block requires configuring a weather service, which may require API keys and other parameters.
If using the autolocate feature, set the autolocate update interval such that you do not exceed ipapi.co’s free daily limit of 1000 hits. Or use autolocate_interval = "once" to only run on initialization.
§Configuration
| Key | Values | Default |
|---|---|---|
service | The configuration of a weather service (see below). | Required |
format | A string to customise the output of this block. See below for available placeholders. Text may need to be escaped, refer to Escaping Text. | " $icon $weather $temp " |
format_alt | If set, block will switch between format and format_alt on every click | None |
interval | Update interval, in seconds. | 600 |
autolocate | Gets your location using the ipapi.co IP location service (no API key required). If the API call fails then the block will fallback to service specific location config. | false |
autolocate_interval | Update interval for autolocate in seconds or “once” | interval |
§OpenWeatherMap Options
To use the service you will need a (free) API key.
| Key | Values | Required | Default |
|---|---|---|---|
name | openweathermap. | Yes | None |
api_key | Your OpenWeatherMap API key. | Yes | None |
coordinates | GPS latitude longitude coordinates as a tuple, example: ["39.2362","9.3317"] | Yes* | None |
city_id | OpenWeatherMap’s ID for the city. (Deprecated) | Yes* | None |
place | OpenWeatherMap ‘By {city name},{state code},{country code}’ search query. See here. Consumes an additional API call | Yes* | None |
zip | OpenWeatherMap ‘By {zip code},{country code}’ search query. See here. Consumes an additional API call | Yes* | None |
units | Either "metric" or "imperial". | No | "metric" |
lang | Language code. See here. Currently only affects weather_verbose key. | No | "en" |
forecast_hours | How many hours should be forecast (must be increments of 3 hours, max 120 hours) | No | 12 |
One of coordinates, city_id, place, or zip is required. If more than one are supplied, coordinates takes precedence over city_id which takes precedence over place which takes precedence over zip.
The options api_key, city_id, place, zip, can be omitted from configuration,
in which case they must be provided in the environment variables
OPENWEATHERMAP_API_KEY, OPENWEATHERMAP_CITY_ID, OPENWEATHERMAP_PLACE, OPENWEATHERMAP_ZIP.
Forecasts are only fetched if forecast_hours > 0 and the format has keys related to forecast.
§met.no Options
| Key | Values | Required | Default |
|---|---|---|---|
name | metno. | Yes | None |
coordinates | GPS latitude longitude coordinates as a tuple, example: ["39.2362","9.3317"] | Required if autolocate = false | None |
lang | Language code: en, nn or nb | No | en |
altitude | Meters above sea level of the ground | No | Approximated by server |
forecast_hours | How many hours should be forecast | No | 12 |
Met.no does not support location name, but if autolocate is enabled then autolocate’s city value is used.
§US National Weather Service Options
| Key | Values | Required | Default |
|---|---|---|---|
name | nws. | Yes | None |
coordinates | GPS latitude longitude coordinates as a tuple, example: ["39.2362","9.3317"] | Required if autolocate = false | None |
forecast_hours | How many hours should be forecast | No | 12 |
units | Either "metric" or "imperial". | No | "metric" |
Forecasts gather statistics from each hour between now and the forecast_hours value, and
provide predicted weather at the set number of hours into the future.
§Available Format Keys
| Key | Value | Type | Unit |
|---|---|---|---|
location | Location name (exact format depends on the service) | Text | - |
icon{,_ffin} | Icon representing the weather | Icon | - |
weather{,_ffin} | Textual brief description of the weather, e.g. “Raining” | Text | - |
weather_verbose{,_ffin} | Textual verbose description of the weather, e.g. “overcast clouds” | Text | - |
temp{,_{favg,fmin,fmax,ffin}} | Temperature | Number | degrees |
apparent{,_{favg,fmin,fmax,ffin}} | Australian Apparent Temperature | Number | degrees |
humidity{,_{favg,fmin,fmax,ffin}} | Humidity | Number | % |
wind{,_{favg,fmin,fmax,ffin}} | Wind speed | Number | - |
wind_kmh{,_{favg,fmin,fmax,ffin}} | Wind speed. The wind speed in km/h | Number | - |
direction{,_{favg,fmin,fmax,ffin}} | Wind direction, e.g. “NE” | Text | - |
sunrise | Time of sunrise | DateTime | - |
sunset | Time of sunset | DateTime | - |
You can use the suffixes noted above to get the following:
| Suffix | Description |
|---|---|
| None | Current weather |
_favg | Average forecast value |
_fmin | Minimum forecast value |
_fmax | Maximum forecast value |
_ffin | Final forecast value |
| Action | Description | Default button |
|---|---|---|
toggle_format | Toggles between format and format_alt | Left |
§Examples
Show detailed weather in San Francisco through the OpenWeatherMap service:
[[block]]
block = "weather"
format = " $icon $weather ($location) $temp, $wind m/s $direction "
format_alt = " $icon_ffin Forecast (9 hour avg) {$temp_favg ({$temp_fmin}-{$temp_fmax})|Unavailable} "
[block.service]
name = "openweathermap"
api_key = "XXX"
city_id = "5398563"
units = "metric"
forecast_hours = 9Show sunrise and sunset times in null island
[[block]]
block = "weather"
format = "up $sunrise.datetime(f:'%R') down $sunset.datetime(f:'%R')"
[block.service]
name = "metno"
coordinates = ["0", "0"]§Used Icons
weather_sun(when weather is reported as “Clear” during the day)weather_moon(when weather is reported as “Clear” at night)weather_clouds(when weather is reported as “Clouds” during the day)weather_clouds_night(when weather is reported as “Clouds” at night)weather_fog(when weather is reported as “Fog” or “Mist” during the day)weather_fog_night(when weather is reported as “Fog” or “Mist” at night)weather_rain(when weather is reported as “Rain” or “Drizzle” during the day)weather_rain_night(when weather is reported as “Rain” or “Drizzle” at night)weather_snow(when weather is reported as “Snow”)weather_thunder(when weather is reported as “Thunderstorm” during the day)weather_thunder_night(when weather is reported as “Thunderstorm” at night)
Modules§
- Support for using the US National Weather Service API.