Weather::Com::Base(3pm) 				User Contributed Perl Documentation				   Weather::Com::Base(3pm)

NAME

       Weather::Com::Base - Perl extension for getting weather information from weather.com

SYNOPSIS

	 use Data::Dumper;
	 use Weather::Com::Base;

	 # define parameters for weather search
	 my %params = (
		       'current'    => 1,
		       'forecast'   => 3,
		       'links'	    => 1,
		       'units'	    => 's',
		       'proxy'	    => 'http://proxy.sonstwo.de',
		       'timeout'    => 250,
		       'debug'	    => 1,
		       'partner_id' => 'somepartnerid',
		       'license'    => '12345678',
	 );

	 # instantiate a new weather.com object
	 my $weather_com = Weather::Com::Base->new(%params);

	 # search for locations called 'Heidelberg'
	 my $locations = $weather_com->search('Heidelberg')
	       or die "No location found!
";

	 # and then get the weather for each location found
	 foreach (keys %{$locations}) {
	       my $weather = $weather_com->get_weather($_);
	       print Dumper($weather);
	 }

DESCRIPTION

       Weather::Com::Base is a Perl module that provides low level OO interface to gather all weather information that is provided by weather.com.

       This module should not be used directly because of the business rules applying if one want's to use the weather.com's xoap interface.
       These business rules enforce you to implement several caching rules.

       Therefore, if you want to use a low level interface, please use Weather::Com::Cached instead. It has the same interface as this module but
       it implements all caching rules of weather.com.

       EXPORT

       None by default. But there are a few static methods for conversion purposes you may wanna use:

       * celsius2fahrenheit(celsius)
	   Takes the temperature in celsius and returns the temperature in fahrenheit (as an integer value).

       * fahrenheit2celsius(fahrenheit)
	   Takes the temperature in fahrenheit	and returns the temperature in celius (as an integer value).

       * convert_winddirection(direction)
	   Takes a wind mnemonic ("N", "WNW", etc.) or a long name of a wind direction ("North Northeast") and returns the other format.

	   The long names are only understood if used as follows:

					   "North"
					   "North Northwest"
					   "Northwest"
					   "West Northwest"
					   "West"
					   "West Southwest"
					   "Southwest"
					   "South Southwest"
					   "South"
					   "South Southeast"
					   "Southeast"
					   "East Southeast"
					   "East"
					   "East Northeast"
					   "Northeast"
					   "North Northeast"
					   "Variable"

CONSTRUCTOR

       new(hash or hashref)

       The constructor takes a hash or a hashref containing a bunch of parameters used to configure your weather search. None of these paramters
       is mandatory.  As there are reasonable defaults for any of them, you need only to provide those parameters where you whish to go with non-
       default values.

       The parameters in detail:

       current =>  0 | 1
	   This parameter defines whether to fetch the current conditions of a location or not.

	   Defaults to 0 (false).

       forecast => 0 | 1 .. 10
	   This parameter defines whether to fetch a weather forecast or not.

	   If set to 0 (false) no forecast is read, if set to a value between 1 and 10 a forecast for the number of days is requested. If set to
	   any other value, this is interpreted as 0!

	   Defaults to 0 (false).

       links => 0 | 1
	   This parameter specifies whether to load some http links from weather.com also or not.

       units => s | m
	   This parameter defines whether to fetch information in metric (m) or US (s) format.

	   Defaults to 'm'.

       proxy => 'none' | 'http://some.proxy.de:8080'
	   Usually no proxy is used by the LWP::UserAgent module used to communicate with weather.com. If you want to use an HTTP proxy you can
	   specify one here.

       proxy_user => undef | 'myuser'
	   If specified, this parameter is provided to the proxy for authentication purposes.

	   Defaults to undef.

       proxy_pass => undef | 'mypassword'
	   If specified, this parameter is provided to the proxy for authentication purposes.

	   Defaults to undef.

       timeout => some integer (in seconds)
	   The timeout for LWP::UserAgent to get an HTTP request done usually is set to 180s. If you need a longer timeout or for some reasons a
	   shorter one you can set this here.

	   Defaults to 180 seconds.

       debug => 0 | 1
	   Set debugging on/off.

	   Defaults to 0 (off).

       partner_id => 'somepartnerid'
	   To be allowed to fetch weather information from weather.com you need to register (free of charge) to get a so called Partner Id and a
	   License Key.

       license => 'somelicensekey'
	   See partner_id.

METHODS

       search(place to search)

       Searches for all known locations matching the provided search string.

       At weather.com you have to request weather data for a specific location.  Therefor you first have to find the location id for the location
       you are looking for. weather.com provides two possibilities to search:

       1. by name
	   You may search for a location by name, e.g. "Heidelberg", "Heidelberg, Germany", "New York, NY", etc.

       2. by postal code
	   You may search for a location by the postal code.

       If the search causes an error, this methods dies with a (hopefully) helpful error message.

       If the search returns no matches, 0 is returned.

       Else, the method returns a hashref containing all locations found.  The hashref looks as follows if you search for Heidelberg:

	 $HASHREF = {
	       'GMXX0053' => 'Heidelberg, Germany',
	       'USKY0990' => 'Heidelberg, KY',
	       'USMS0154' => 'Heidelberg, MS'
	 };

       The keys of the hash are the location ids as used within weather.com.  This keys have to be used for fetching the weather information of
       one location.

       get_weather(location id)

       This method fetches all weather information as defined by the object attributes you may have modified while instantiating the weather
       object.

       If an error occurs while fetching weather information, this method dies setting $@ to a meaningfull error message.

       The following hashref shows the maximum of data that can be fetched from weather.com. The parts of the hashref are explained afterwards.

	 $HASHREF = {
	       'head' => {
		       'ur'	=> 'mm',
		       'ud'	=> 'km',
		       'us'	=> 'km/h',
		       'form'	=> 'MEDIUM',
		       'up'	=> 'mb',
		       'locale' => 'en_US',
		       'ut'	=> 'C'
	       },
	       'loc' => {
		       'suns'	=> '8:40 PM',
		       'zone'	=> '2',
		       'lat'	=> '49.41',
		       'tm'	=> '3:48 PM',
		       'sunr'	=> '6:18 AM',
		       'dnam'	=> 'Heidelberg, Germany',
		       'id'	=> 'GMXX0053',
		       'lon'	=> '8.68'
	       },
	       'cc' => {
		       'icon' => '28',
		       'flik' => '21',
		       'obst' => 'Mannhein, Germany',
		       'lsup' => '8/16/04 3:20 PM Local Time',
		       'tmp'  => '21',
		       'hmid' => '78',
		       'wind' => {
			       'gust' => 'N/A',
			       'd'    => '170',
			       's'    => '11',
			       't'    => 'S'
		       },
		       'bar'  => {
			       'r' => '1,010.8',
			       'd' => 'steady'
	       },
		       'dewp' => '17',
		       'uv'   => {
			       't' => 'Moderate',
			       'i' => '3'
		       },
		       'vis'  => '10.0',
		       't'    => 'Mostly Cloudy'
	       },
	       'dayf' => {
		       'lsup' => '8/16/04 12:17 PM Local Time',
		       'day'  => [
			       {
				       'hi'   => '27',
				       'suns' => '8:40 PM',
				       'dt'   => 'Aug 16',
				       'part' => [
					       {
						       'hmid' => '57',
						       'wind' => {
							       'gust' => 'N/A',
							       'd'    => '204',
							       's'    => '16',
							       't'    => 'SSW'
						       },
						       'icon' => '28',
						       'p'    => 'd',
						       'ppcp' => '20',
						       't'    => 'Mostly Cloudy'
					       },
					       {
						       'hmid' => '87',
						       'wind' => {
							       'gust' => 'N/A',
							       'd'    => '215',
							       's'    => '13',
							       't'    => 'SW'
						       },
						       'icon' => '11',
						       'p'    => 'n',
						       'ppcp' => '60',
						       't'    => 'Showers'
					       }
				       ],
				       'd'    => '0',
				       'sunr' => '6:18 AM',
				       'low'  => '16',
				       't'    => 'Monday'
			       },

			       ... next day ...,

			       ... and so on ...,

		       ]
	       },
	       'lnks' => {
		       'link' => [
			       {
				       'l'   => 'http://www.weather.com/outlook/health/allergies/USMS0154?par=xoap',
				       'pos' => '1',
				       't'   => 'Pollen Reports'
			       },
			       {
				       'l'   => 'http://www.weather.com/outlook/travel/flights/citywx/USMS0154?par=xoap',
				       'pos' => '2',
				       't'   => 'Airport Delays'
			       },
			       {
				       'l'   => 'http://www.weather.com/outlook/events/special/result/USMS0154?when=thisweek&par=xoap',
				       'pos' => '3',
				       't'   => 'Special Events'
			       },
			       {
				       'l'   => 'http://www.weather.com/services/desktop.html?par=xoap',
				       'pos' => '4',
				       't'   => 'Download Desktop Weather'
			       }
		       ],
		       'type' => 'prmo'
	       },
	       'ver' => '2.0'
	 };

       Header Information Block

       The hashref head contains unit of measure definitions for the whole dataset. Usually they are either all metric or all us.

       locale
	   Should always be en_US. Up to now I have not found any possiblity to get other locales.

       ut (unit of temperature)
	   Could be C for Celsius or F for Fahrenheit.

       us (unit of speed)
	   Could be km/h or mph.

       ud (unit of distance)
	   Could be km or mi.

       ur (unit of precipitation)
	   Could be mb (millibar) or in.

       up (unit of pressure)
	   Could be mb or in for in Hg.

       format (textformat)
	   Could be SHORT, MEDIUM or LONG.

       Location Information Block

       The hashref loc contains some information about the location that does not change very much each hour or day.

       id (location id)
	   This is the location id as used to get the weather for the location.

       dnam (descriptive name)
	   This is a name describing the location, e.g. Heidelberg, Germany.

       tm (time)
	   This is the current local time of the location (if not using cached data).

	   Time is always presented like 8:45 AM or 11:33 PM.

       zone (timezone)
	   This is the timezone. It is presented as time offset from GMT.

       suns (time of sunset)
       sunr (time of sunrise)
       lat (latitude)
	   The latitude is presented as 2 digit decimal.

       lon (longitude)
	   The longitude is presented as 2 digit decimal.

       Current Conditions Block

       The hashref cc contains information about the current conditions.

       icon
	   The SDK from weather.com contains a set of weather icons. These icons have filenames like 28.png. This element is this icon number.

       flik (windchill)
	   This is the temperature considering the windchill factor.

       obst (observatory)
	   The observatory that reported the weather data.

       lsup (last updated)
	   Date and time when the weather data has been reported. Format is 8/16/04 6:10 AM EDT. In some cases (e.g. for Heidelberg in Germany)
	   there may be no official timezone identifier but the keyword Local or Local Time.

       tmp (temperature)
       hmid (humidity)
       wind
	   gust    Maximum gust speed.

	   d	   Wind direction in degrees.

	   t	   Text description of direction.

	   s	   Wind speed

       bar (air pressure)
	   r (pressure)
		   Decimal current pressure.

	   d (description)
		   Text description of raise or fall of pressure.

       dewp
	   Integer dew point.

       uv (uv index data)
	   i	   Integer index value.

	   t	   Text description of value.

       vis (decimal visibility)
       t   Text description of condition.

       Forecasts

       Up to 10 days of forecasts can be found in the hashref dayf.

       lsup (last updated)
	   self explanatory

       day day contains either a hash containing the forecast for one day or it contains an an array of hashes, one for each day.

	   dt (date)
		   The date of the forecasted day. Only name of month and day, e.g. Aug 16.

	   d (number of the day)
	   t (name of the day)
		   e.g. Monday

	   hi (highest temperature)
	   low (lowest temperature)
	   suns (time of sunset)
	   sunr (time of sunrise)
	   part (block of day part data)
		   There are always to blocks of day part data. One for the the night and one for the day.

		   hmid (humidity)
		   wind (see current conditions block)
		   icon (see current conditions block)
		   p (part of day)
			       Maybe d for day or n for night.

		   ppcp (percent chance of precipitation)
		   t (description of conditions)

       Links

       The hashref lnks contains some links to other weather information that may be interesting for the chosen location. This will not be
       explained in further detail here. Just play around with the sample...

SEE ALSO

       See also Weather::Com::Cached for the cached version of the low level API.

AUTHOR

       Thomas Schnuecker, <thomas@schnuecker.de>

COPYRIGHT AND LICENSE

       Copyright (C) 2004-2007 by Thomas Schnuecker

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

       The data provided by weather.com and made accessible by this OO interface can be used for free under special terms.  Please have a look at
       the application programming guide of weather.com (http://www.weather.com/services/xmloap.html)!

perl v5.8.8							    2007-07-09						   Weather::Com::Base(3pm)