forecast

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

Capabilities include:

Plotting tables with current, hourly and daily weather conditions
Rendering barplots of temperature and precepitation curves for hourly and daily weather forecasts, sunrise and sunset times for daily weather forecasts and many more things
Dumping of the original JSON weather data

Current project status

The last stable release is 0.5.0. Development is active and takes place on the develop branch.

Dependencies

libjson-c is used for retrieving the weather data.
libconfig is used for configuration file management.
libcurl (built with SSL support) is used for interacting with the forecast.io API.
libncursesw5 drives the terminal UI.
libcrypto (part of OpenSSL) is used as a source for hash algorithms. Suggestions for more lightweight alternatives are welcome.
liblz4 is used for compressing the on-disk cache files.
libtalloc is the future of forecast's memory management.

The build system uses GNU autoconf and automake.

Build

Generic Linux/Unix system

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

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

Debian and Ubuntu

forecast is available as forecast through the BunsenLabs project's Debian repository at pkg.bunsenlabs.org.

The program builds cleanly on Debian Jessie and newer and Ubuntu 15.04 and newer, as well as all derived distributions.

If you are using Ubuntu 14.04 or older, you need to manually work around the problem that the liblz4-dev package doesn't yet contain a pkgconfig file. To this end, remove the package check from configure.ac and append -llz4 manually to the LDFLAGS variables in src/Makefile.am.

Arch Linux

forecast is available through the AUR as forecast-git.

OSX

Read the notes here, then proceed with the generic build instructions.

BSD

The program should also build on the BSDs, but that is untested.

Synopsis

Usage:
  forecast [dehL:l:m:rs:u:v] [LONGFORM OPTIONS]
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 forecast.io. 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

$HOME/.forecastrc

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, credit goes to jaseg:

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":

License

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
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
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 <http://www.gnu.org/licenses/>.

IrvinPoe/forecast