view release on metacpan or  search on metacpan

lib/Geo/WeatherNWS.pm  view on Meta::CPAN

=head1 SYNOPSIS

  use Geo::WeatherNWS;

  my $Report=Geo::WeatherNWS::new();

  # Optionally set the server/user/directory of the reports

  $Report->setservername("tgftp.nws.noaa.gov")
  $Report->setusername("anonymous");
  $Report->setpassword('emailaddress@yourdomain.com');
  $Report->setdirectory("/data/observations/metar/stations");

  # Optionally set a template file for generating HTML

  $Report->settemplatefile(/"path/to/template/file.tmpl");

  # Get the report

  $Report->getreport('kcvg');      # kcvg is the station code for
                                   # Cincinnati, OH

  $Report->getreporthttp('kcvg');  # same as before, but use the
                                   # http method to the script at
				   # http://www.aviationweather.gov/adds/metars/
				   # (used to be weather.noaa.gov)

  # Check for errors

  if ($Report->{error})
  {
    print "$Report->{errortext}\n";
  }

  # If you have the report in a string, you can now just decode it

  my $Obs="2002/02/25 12:00 NSFA 251200Z 00000KT 50KM FEW024 SCT150 27/25 Q1010";
  $Report->decodeobs($Obs);

=head1 DESCRIPTION

  New for version 1.03:  the getreporthttp call now calls the script
  on the weather.noaa.gov site for those who can't FTP through
  firewalls.

  This module is an early release of what will hopefully be a robust
  way for Perl Programmers to get current weather data from the
  National Weather Service.  Some new functions have been added since
  the 0.18 release.

  Instead of having to use the built-in server/user/password/directory
  that the module used to use, you can provide your own.  This way if
  you have access to a mirror server of the data, you can specify the
  servername, account information and directory where the files exist.
  If you don't have access to a mirror, then you don't have to specify
  anything.  The old server, etc., are still automagically selected.

  Also new in this release is that the getreport function now returns
  an error code and the FTP error message if anything goes wrong.
  Before this was added, if the server was busy or the stations text
  file was missing you couldn't tell what happened.

  Another new feature is the template system.  You can specify a file
  with the settemplatefile function.  This file is read in and all of
  the places in the file where the code sees %%name%% will be replaced
  with the proper values. An example template has been included.
  The template uses the same names as the hashref returned by the
  getreport function.

  And, same as previous releases, the getreport function retrieves
  the most current METAR formatted station report and decodes it into
  a hash that you can use.

  Some users had reported that they wanted to re-decode the raw
  observations later.  If you store the "obs" value as a string, and
  you want to re-decode it later, you can now use the decodeobs
  function.

  I thought this would be a useful module, considering that a lot of
  sites today seem to get their weather data directly through other
  sites via http. When the site you are getting your weather data
  from changes format, then you end up having to re-code your parsing
  program.  With the weather module, all you need is a four-letter
  station code to get the most recent weather observations.

  If you do not know what the station code is for your area,
  these sites might help your search:

    http://en.wikipedia.org/wiki/List_of_airports_by_ICAO_code

    http://www.aircharterguide.com/Airports 
                 		     
  Since this module uses the NWS METAR Observations, you can get
  weather reports from anywhere in the world that has a four-letter
  station code.

  This module uses the Net::FTP module, so make sure it is available.

  To begin:

  use Geo::WeatherNWS;
  my $Report=Geo::WeatherNWS::new();

  If you want to change the server and user information, do it now.
  This step is not required.  If you don't call these functions, the
  module uses the defaults.

  $Report->setservername("weather.noaa.gov");
  $Report->setusername("anonymous");
  $Report->setpassword('emailaddress@yourdomain.com');
  $Report->setdirectory("/data/observations/metar/stations");
  $Report->settimeout(240);

  If you want to specify a template file, use this:

  $Report->settemplatefile("/path/to/template/file.tmpl");

  After setting the above, you can get the data.

  $Report->getreport('station');