Ham-APRS-LastPacket 0.02

NAME
    Ham::APRS::LastPacket - A simple interface to retrieve the most recent
    packet data for a station from APRS-IS.

VERSION
    Version 0.02

INSTALLATION
    To install this module, run the following commands:

	perl Makefile.PL
	make
	make test
	make install

SYNOPSIS
     use Ham::APRS::LastPacket;

     my $aprs = Ham::APRS::LastPacket->new; 
     $aprs->set_callsign('n8qq');
     my $packet = $aprs->get_data;

     die $aprs->error_message if $aprs->is_error;

     # show the entire structure of data
     use Data::Dumper;
     print Dumper($packet);

     # get a single item
     print $aprs->get_callsign;
     print " is at $packet->{position}->{longitude}->{degrees} degrees longitude.\n";

DESCRIPTION
    The "Ham::APRS::LastPacket" module retrieves the latest packet from
    APRS-IS for a given station's callsign by referencing the
    aprsworld-to-XML interface. You provide the callsign for a station that
    exists in APRSWorld, and you will get back a hashref of hashrefs
    containing all data available for that station's latest packet. Use
    "Data::Dumper" to inspect the data to see all items that are available
    (as shown in the synopsis). The data set returned can differ based on
    what type of station is being referenced. For instance, a weather
    station will contain weather data that another type of station won't.

CONSTRUCTOR
  new()
     Usage    : my $aprs = Ham::APRS::LastPacket->new;
     Function : creates a new Ham::APRS::LastPacket object
     Returns  : a Ham::APRS::LastPacket object
     Args     : a hash:
                key             required?   value
                -------         ---------   -----
                timeout         no          an integer of seconds to wait for
                                            the timeout of the web site
                                            default = 10
                suppress_empty  no          set the handling for empty elements
                                            suppress_empty => 1 will exclude empty elements
                                            suppress_empty => '' will set them to an empty hash
                                            suppress_empty => undef will set the hashes to undef
                                            default is empty string

METHODS
  set_callsign()
     Usage    : $aprs->set_callsign( $callsign );
     Function : set the callsign of the station whose data will be retrieved with get_data()
     Returns  : n/a
     Args     : a case-insensitive string containing the callsign of the station in APRS-IS.
                you can use CWOP callsigns and callsigns with SSIDs.

  get_callsign()
     Usage    : $callsign = $aprs->get_callsign;
     Function : get the callsign that was set with the most recent call to set_callsign().
     Returns  : a string.  (the callsign will have been converted to upper case)
     Args     : n/a

  get_data()
     Usage    : $data = $aprs->get_data;
     Function : get a hashref of hashrefs of the data contained in APRS-IS for the station set in set_callsign()
     Returns  : a hashref of hashrefs
     Args     : n/a

  is_error()
     Usage    : if ( $aprs->is_error )
     Function : test for an error if one was returned from the call to the aprsworld-to-XML site
     Returns  : a true value if there has been an error
     Args     : n/a

  error_message()
     Usage    : my $err_msg = $aprs->error_message;
     Function : if there was an error message when trying to call the site, this is it
     Returns  : a string (the error message)
     Args     : n/a

DEPENDENCIES
    * XML::Simple
    * LWP::UserAgent
    * An Internet connection

TODO
    * Maybe provide a list of data items and the hashref hierarchy.
    * Improve the module description.
    * Improve error checking.

ACKNOWLEDGEMENTS
    *   This module gets its data from the aprsworld-to-XML interface, by
        Brad McConahay N8QQ (me). See http://aprsearch.net/xml

    *   The aprsworld-to-XML interface gets its data from APRSWorld, by Jim
        Jarvis KB0THN. See http://aprsworld.net

    *   APRS-IS is the Internet-based network which inter-connects various
        APRS radio networks throughout the world (and space). See
        http://aprs-is.net

    *   APRS was created by, and is a trademark of, Bob Bruninga WB4APR. See
        http://aprs.org

AUTHOR
        Brad McConahay N8QQ, "<brad at n8qq.com>"

COPYRIGHT AND LICENSE
        Copyright 2008 Brad McConahay N8QQ, all rights reserved.

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