Gem Build Status Code Climate Code Coverage

Forecaster is a gem wrapping wgrib2 to fetch and read weather data directly from the Global Forecast System.

It comes with a library and a CLI allowing you to type commands like forecast for this afternoon in paris in your terminal to get the latest weather forecast.



gem install forecaster

Alternatively you can build the gem from its repository:

git clone git://
cd forecaster
gem build forecaster.gemspec
gem install forecaster-1.0.0.gem

In both cases you need to make sure that you have wgrib2 present in your system.

To install the wgrib2 from source:

tar -xzvf wgrib2.tgz
cd grib2
export CC=gcc
export FC=gfortran
sudo cp wgrib2/wgrib2 /usr/local/bin/


require "forecaster"

To configure the gem:

Forecaster.configure do |config|
  config.wgrib2_path = "/usr/local/bin/wgrib2"
  config.cache_dir = "/tmp/forecaster"
  config.records = {
    :temperature => ":TMP:2 m above ground:",
    :humidity    => ":RH:2 m above ground:",
    :pressure    => ":PRES:surface:"

Forecaster saves large files containing the data of GFS runs from the NOAA servers in the cache directory, but only the parts of the files containing the records defined in the configuration will be downloaded.

You can find the list of available records online or by reading any .idx files distributed along with the GFS files.

A record is identified by a variable and a layer separated by colon characters. In the case of the temperature for example, those attributes are TMP and 2 m above ground. See the documentation of wgrib2 for more information.

To fetch a forecast:

t = # All the dates should be expressed in UTC
y = t.year       # year of GFS run
m = t.month      # month of GFS run
d =        # day of GFS run
c = 0            # hour of GFS run (must be a multiple of 6)
h = 12           # hour of forecast (must be a multiple of 3)
forecast = Forecaster.fetch(y, m, d, c, h) # Forecaster::Forecast

To read the record of a forecast:

res =, longitude: 48.1147, latitude: -1.6794) # String in Kelvin
val = res.to_f - 273.15 # Float in degree Celsius

Command line

Forecaster has a command line tool that try to be smart:

$ forecast for tomorrow afternoon in auckland
GFS Weather Forecast

  Date:        2016-05-13
  Time:          12:00:00
  Zone:             +1200
  Latitude:         -36.8 °
  Longitude:        174.8 °

  Pressure:        1013.8 hPa
  Temperature:       21.7 °C
  Nebulosity:         0.0 %
  Humidity:          65.1 %
  Precipitation:      0.0 mm
  Wind:               8.0 m/s (NE)

But you can use it in a more verbose way:

$ TZ=America/Los_Angeles forecast --time "2016-05-12 09:00:00" \
                                  --latitude "37.7749295" \
                                  --longitude "-122.4194155" \
Requested time:  2016-05-12 09:00:00 -0700
GFS Run time:    2016-05-11 23:00:00 -0700
Forecast time:   2016-05-12 08:00:00 -0700

Downloading: '
Reading index file...
Length: 4992281 (4.76M)

100% [===========================================>] 696 KB/s Time: 00:00:07

GFS Weather Forecast

  Date:        2016-05-12
  Time:          08:00:00
  Zone:             -0700
  Latitude:          37.8 °
  Longitude:       -122.4 °

  Pressure:        1013.5 hPa
  Temperature:       13.4 °C
  Nebulosity:         0.0 %
  Humidity:          89.7 %
  Precipitation:      0.0 mm
  Wind:               1.0 m/s (NE)

To use automatically the timezone of a location you will need to create a free GeoNames account and export your username in an environment variable:

export GEONAMES_USERNAME=<username>

And while you're doing that, you can also export your favorite location to avoid typing it every time:

export FORECAST_LATITUDE=<latitude>
export FORECAST_LONGITUDE=<longitude>


Copyright (c) 2015-2018 Vincent Ollivier. Released under MIT.