forecast is a query program for the API. It provides a command line interface which makes weather data for a configurable location available in the terminal.

Capabilities include:

Current project status

The last stable release is 0.5.0. Development is active. Currently, a partial rewrite is underway which will use a tree data structure (see tree.c) as the central data store.

This rewrite will simplify much of the messy code in render.c and enable the implementation of several new and improved features. One of these will be forecastfs, a FUSE-based virtual file system for presenting weather data to any file-aware program. After finishing forecastfs, the ncurses UI will receive more love and features.


The build system uses GNU autoconf and automake.


Generic Linux/Unix system

After installing all dependencies, this will configure and build the program:

./configure --prefix=/your/prefix
make install

Debian and Ubuntu

forecast is available as forecast through the BunsenLabs project's Debian repository at

Arch Linux

forecast is available through the AUR as forecast-git.


  forecast [dehL:l:m:rs:u:v] [LONGFORM OPTIONS]
  -d|--dump                      Dump the JSON data and a newline to stdout
  -e|--extend-hourly             Request data for one week instead of two days
                                 for hourly forecasts.
  -h|--help                      Print this message and exit
  -L|--location-by-name   NAME   Select a location predefined in the configuration file
  -l|--location           CHOORD Query the weather at this location; CHOORD is a string in the format
                                 <latitude>:<longitude> where the choordinates are given as floating
                                 point numbers
  --language              NAME   Set the language for verbal descriptions.
  -m|--mode               MODE   One of print, print-hourly, plot-hourly, plot-daily, plot-precip-daily,
                                 plot-precip-hourly, plot-daylight. Defaults to 'print'
  -r|--request                   By pass the cache if a cache file exists
  -s|--step               N      In hourly plots, use only every Nth datapoint.
  -u|--units              UNITS  Location-specific unit table to be used. One of si, us, uk, ca, auto.
                                 When specifying 'auto', the unit will be set depending on location
  -v|--version                   Print program version and exit

When using --location, the cache will be bypassed in any case. In plotting mode, the plot will be shown until you press a key.

API key

In order to use the API, you need to obtain an API key from You are able to make 1000 API calls per day free of charge. The registration interface is here.

Configuration file

forecast uses a configuration file in libconfig format. The file is by default located at


but you may override the location by setting the FORECAST_CONFIG_PATH environment variable. If available, command line parameters take precedence over the config file settings.

The best way to create the config file is to copy and edit the provided forecastrc.example.

As for the meaning of the keys, read the comments in forecastrc.example file which is part of the forecast distribution. When forecast is already installed on your system, the documentation files are located in /usr/share/doc/forecast.

How it looks (or can look) like

IRL demo pic with a sweet orange glow:

Daily overlay forecast plot (-m plot-daily), with the label format "%d%b", showing the min/max temperatures on each day:

Hourly forecast plot (-m plot-hourly), with the label format "%H:%M":


This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <>.