Geo::CCF — Perl module for decoding weather forecasts:

Icon  Name                    Last modified      Size  Description
[<] Parent Directory - [>] Geo-CCF-0.04.tar.gz 2004-03-23 16:04 8.5K current source archive

Newsflash (Dec. 4, 2004) — this may be obsolete -- check this out: NDFD XML!

(Also, some hints on using the new format.)


Geo::CCF - decode National Weather Service Coded Cities Forecast data


  use Geo::CCF;
  my $forecast = new Geo::CCF;
  my $station = "BOS";
  die("Can't find info for $station") if !$forecast->{$station};
  for (my $i=0; $i<Geo::CCF::NUM_FORECAST_PERIODS; $i++) {
    print $forecast->{$station}{CONDITION}[$i];
    $forecast->{$station}{HIGH}[$i] and
        print ", high $forecast->{$station}{HIGH}[$i]";
    $forecast->{$station}{LOW}[$i] and
        print ", low $forecast->{$station}{LOW}[$i]";
    $forecast->{$station}{PROBPRECIP}[$i] and
        print ", $forecast->{$station}{PROBPRECIP}[$i]% " .
              "chance of precipitation.";
    print "\n";


Decodes the National Weather Service's CCF data files into a simple Perl object.


There's a lot of U.S. weather information available from the National Weather Service (and the larger National Oceanic and Atmospheric Administration). There are other CPAN modules for parsing some of this data, most notably the METAR reports on current aviation weather. And there's modules for scraping information from various commercial web sites. But, I couldn't find anything that could read the forecast information made available in the form of “CCF” — Coded City Forecast — files. This twice-daily forecast data is designed to be processed by computers, and indeed provides a lot of information in very little space.

Unfortunately, the format is a bit obtuse, so it's handy to have a Perl module to understand it for you. I couldn't find one, so here's mine.

You can download various CCF files for different locations from <>. (Beware — a long and sometimes slow directory listing.) Each ccf file (named something like fpus41.kbox.ccf.bos.txt) contains the entries for several stations. Find the one that has the station you want to find the forecast for, and feed it to this module.

You'll get back a hash of the various stations in the report, with each station containing the forcast data for the next fourteen seven-hour periods. (Or, sometimes, only thirteen.) You'll have the predicted condition — rain, snow, dust, or whatever, high or low temperature, and chance of precipitation for each time slice.



First, create a new Geo::CCF object. Then, feed it CCF data as a single string. Then, simply look at the data you want to know for the station you want.


ccf() is the main thing. Give it a CCF file as a string, and it'll parse it so you can access the forecast data in a sane way.


Unless the CCF file format changes and this module is updated, this will be 14. The forecast is for seven days, in 12-hour periods -- that is, 14 half-days. Conceivably in the future, the NWS could extend the format to cover ten days, or when the orbital weather control satellite network is in place, whole years at a time.


The important thing to realize is that these values are all stored on a per-station basis — the top-level hash is an index of all of the stations decoded from the given CCF data.

Furthermore, much of the data is contained in arrays, with each element corresponding to a future 12-hour period. In order, of course. There's usually 14, but sometimes the last value is missing — nothing to be done about that! You can use the Geo::CCF::NUM_FORECAST_PERIODS constant as a loop index as in the example above, but in actual practice, it may be nicer to just check the arrays to see if the forecast for the desired future period is defined.

Array containing the predicted predominant weather. Possibilities are:

You won't see the parenthetical letter in the results — that's the code in the original file. Some are mnemonic (C or R or S or T) and some are not quite so (J or P or pretty much all the rest). Anyway, you have this module so you don't have to worry about that.

Also of note: the source data is in 24-hour periods, but this array provides entries for each 12-hour block, to match the temperature and precipitation forecasts. There's no extrapolation or any magic — each entry is simply doubled. Don't be fooled.

Arrays containing predicted temperature information in degrees Fahrenheit. Only one of HIGH or LOW will have a defined value for a given time period — generally, LOW at night and HIGH during the day. I realize that this is stupid and annoying, but that's the source data.

Array containing the probability (as an integer 0-100) of precipitation during the 12-hour period.

Each file starts with a six character alphanumeric identifier. Presumably, this means something to the National Weather Service, but it means nothing to me. If you pass this file header info to the ccf() method, it'll put that info here. Otherwise, it'll be undefined.

From the optional file header — the station which generated the CCF report, which probably covers many other stations as well. Not really very generally useful.

Also from the file header, and not as useful as you may hope. Unfortunately, the date is only the day of the month in which the report was generated, so you need to have some greater context to do anything useful. And the time is in GMT, which isn't bad, but again, requires knowledge of context.

Anyway, CCFDATE is a two-digit number, and CCFTIME is four digits for HHMM.

A two-digit number representing the actual forecaster. Maybe this could be used to produce an accuracy scorecard. Otherwise, probably not of general usefulness.


None that I know, but I haven't done widespread testing. It's possible that there's some data-format glitches which I haven't covered. If you find any problems, please e-mail me.


No attempt is made to validate incoming data. If you give ccf() garbage, it will return with nothing, at best. And if you give slightly weird data, you won't get any clue back about what's wrong. That ought to be fixed.

The two-line format is apparently an expansion of the earlier one line. This module won't cope with missing second lines.

There also aren't any test cases. Tests are good to have.


Web site: <>

CCF info: <>

Other modules: Geo::METAR, Geo::WeatherNOAA, Geo::Weather


Matthew Miller, <(get e-mail)>


Copyright © 2004 by Matthew Miller

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.