copycat-killer edited this page Feb 8, 2017 · 40 revisions


Read here.


Provides current weather status widgets and X-days forecast popup notifications.

Uses OpenWeatherMap API.

By default, it uses current for current weather data and forecast16 for forecasts.

local myweather =

Input table

Variable Meaning Type Default
timeout Refresh timeout seconds for current weather status int 900 (15 min)
timeout_forecast Refresh timeout seconds for forecast notification int 86400 (24 hrs)
current_call Command to fetch weather status data from the API string see default_current_call
forecast_call Command to fetch forecast data from the API string see default_forecast_call
city_id API city code int not set
utc_offset UTC time offset function see here
units Temperature units system string "metric"
lang API data localization string "en"
cnt Forecast days interval int 5
date_cmd Forecast notification format style string "date -u -d @%d +'%%a %%d'"
icons_path Icons path string lain/icons/openweathermap
notification_preset Preset for notifications table empty table
notification_text_fun Function to format forecast notifications function see notification_text_fun
weather_na_markup Markup to be used when weather textbox is not available text " N/A "
followtag Display the notification on currently focused screen boolean false
settings User settings function empty function
  • default_current_call

    "curl -s ''"

    You can rewrite it using any fetcher solution you like, or you can modify it in order to fetch data by city name, instead of ID: just replace id with q:

    "curl -s ''"

    and set city_id with your city name, for instance city_id = "London,UK".

  • default_forecast_call

    "curl -s ''"

    Like above. If you want to use forecast5, use this API call string:

  • city_id

    An integer that defines the OpenWeatherMap ID code of your city. To obtain it go to OpenWeatherMap and query for your city in the top search bar. The link will look like this:

    your city_id is the number at the end.

  • utc_offset

    Since OWM provides data in UTC time, we have to adjust the weather icons in order to respect the local timezone day/night cycle.

    If you need to set this function, you can check here to know your UTC offset. Note that it must return a number.

  • units

    • For temperature in Fahrenheit use units = "imperial"
    • For temperature in Celsius use units = "metric" (Lain default)
    • For temperature in Kelvin use units = "standard" (OpenWeatherMap default)
  • lang

    See Multilingual Support section here.

  • cnt

    Determines how many days to show in the forecast notification. Up to 16 if you use forecast16 (default), and up to 5 if you use forecast5.

  • date_cmd

    OpenWeatherMap time is in UNIX format, so this variable uses date to determine how each line in the forecast notification is formatted. Default looks like this:

    day #daynumber: forecast, temp_min - temp_max

    see man date for your customizations.

  • icons_path

    You can set your own icons path if you don't wish to use lain/icons/openweathermap. Just be sure that your icons are PNGs and named exactly like OpenWeatherMap ones.

  • notification_preset

    Notifications preset table. See here for the details.

  • notification_text_fun

    function (wn)
       local day = string.gsub(read_pipe(string.format(date_cmd, wn["dt"])), "\n", "")
       local tmin = math.floor(wn["temp"]["min"])
       local tmax = math.floor(wn["temp"]["max"])
       local desc = wn["weather"][1]["description"]
       return string.format("<b>%s</b>: %s, %d - %d ", day, desc, tmin, tmax)

    See here for a complete customization example.

  • followtag

    In multiple screen setups, the default behaviour is to show a visual notification pop-up window on the first screen. By setting followtag to true it will be shown on the currently focused tag screen.

  • settings

    In your settings function, you can use widget variable to refer to the textbox, and the dictionary weather_now to refer to data retrieved by current_call. The dictionary is built with dkjson library, and its structure is defined here. For instance, you can retrieve current weather status and temperature in this way:

    descr = weather_now["weather"][1]["description"]:lower()
    units = math.floor(weather_now["main"]["temp"])

Output table

Variable Meaning Type
widget The widget wibox.widget.textbox
icon The icon wibox.widget.imagebox
update Update widget function
timer The widget timer gears.timer
timer_forecast The forecast notification timer gears.timer


You can attach the forecast notification to any widget like this:


Hovering over obj will display the notification.


You can create a keybinding for the weather popup like this:

awful.key( { "Mod1" }, "w", function () end )

where show argument is an integer defining timeout seconds.