1Ham::Reference::QRZ(3)User Contributed Perl DocumentationHam::Reference::QRZ(3)
2
6 Ham::Reference::QRZ - An object oriented front end for the QRZ.COM
7 Amateur Radio callsign database
8
10 Version 0.02
11
13 use Ham::Reference::QRZ;
14 use Data::Dumper;
15 my $qrz = Ham::Reference::QRZ->new(
17 callsign => 'N8QQ',
18 username => 'your_username',
19 password => 'your_password'
20 );
21 # get the listing and bio
23 my $listing = $qrz->get_listing;
24 my $bio = $qrz->get_bio;
25 # dump the data to see how it's structured
27 print Dumper($listing);
28 print Dumper($bio);
29 # set a different callsign to look up
31 $qrz->set_callsign('W8IRC');
32 # get the listing and print some specific info
34 $listing = $qrz->get_listing;
35 print "Name: $listing->{name}\n";
36
38 The "Ham::Reference::QRZ" module provides an easy object oriented front
39 end to access Amateur Radio callsign data from the QRZ.COM online
40 database.
41 This module uses the QRZ XML Database Service, which requires a
43 subscription from QRZ.COM.
44 The QRZ XML Database Service specification states "The data supplied by
46 the XML port may be extended in a forwardly compatible manner. New XML
47 elements and database objects (with their associated elements) may be
48 transmitted at any time. It is the developers responsibility to have
49 their program ignore any unrecognized objects and/or elements without
50 raising an error, so long as the information received consists of
51 properly formatted XML."
52 Therefore, this module will not attempt to list or manage individual
54 elements of a callsign. You will need to inspect the hash reference
55 keys to see which elements are available for any given callsign.
56 This module does not handle any management of reusing session keys at
58 this time.
59
61 new()
62 Usage : my $qrz = Ham::Reference::QRZ->new;
63 Function : creates a new Ham::Reference::QRZ object
64 Returns : a Ham::Reference::QRZ object
65 Args : a hash:
66 key required? value
68 ------- --------- -----
69 timeout no an integer of seconds to wait for
70 the timeout of the xml site
71 default = 10
72 callsign no you may specify a callsign to look up
73 here, or you may do it later with the
74 set_callsign() method
75 username no you may specify a username to log in with
76 here, or you may do it later with the
77 set_username() method
78 password no you may specify a password to log in with
79 here, or you may do it later with the
80 set_password() method
81 key no set a session key here if you have a valid key so
82 that no time is wasted doing another login. only
83 useful if you are managing the reuse of your own keys
84
86 set_callsign()
87 Usage : $qrz->set_callsign( $callsign );
88 Function : set the callsign to look up at QRZ
89 Returns : n/a
90 Args : a case-insensitive string containing an Amateur Radio callsign.
91 Notes : calling this will reset the listing and bio data to null until
92 you do another get_listing() or get_bio(), respectively.
93 set_username()
95 Usage : $qrz->set_username( $username );
96 Function : set the username for your QRZ subscriber login
97 Returns : n/a
98 Args : a string
99 set_password()
101 Usage : $qrz->set_password( $password );
102 Function : set the password for your QRZ subscriber login
103 Returns : n/a
104 Args : a string
105 set_key()
107 Usage : $qrz->set_key( $session_key );
108 Function : set a session key for retrieving data at QRZ
109 Returns : n/a
110 Args : a string
111 Notes : this is useful only if you already have a valid key before the first login
112 during a particular instance of the module.
113 set_timeout()
115 Usage : $qrz->set_timeout( $seconds );
116 Function : sets the number of seconds to wait on the xml server before timing out
117 Returns : n/a
118 Args : an integer
119 get_listing()
121 Usage : $hashref = $qrz->get_listing;
122 Function : retrieves data for the standard listing of a callsign from QRZ
123 Returns : a hash reference
124 Args : n/a
125 Notes : if a session key has not already been set, this method will automatically login.
126 if a there is already listing information set from a previous lookup,
127 this will just return that data. do a new set_callsign() if you need to refresh
128 the data with a new call to the qrz database.
129 get_bio()
131 Usage : $hashref = $qrz->get_bio;
132 Function : retrieves data for the biography of a callsign from QRZ
133 Returns : a hash reference
134 Args : n/a
135 Notes : if a session key has not already been set, this method will automatically login.
136 if a there is already biographical information set from a previous lookup,
137 this will just return that data. do a new set_callsign() if you need to refresh
138 the data with a new call to the qrz database.
139 login()
141 Usage : $session = $qrz->login;
142 Function : initiates a login to the QRZ xml server
143 Returns : a hash reference of the session data
144 Args : n/a
145 Notes : this generally shouldn't need to be used since the get_listing() and get_bio()
146 methods will automatically initiate a login to the server if it hasn't already
147 been done.
148 get_session()
150 Usage : $session = $qrz->get_session;
151 Function : retrieves the session information from the most recent call to the XML site
152 Returns : a hash reference of the session data
153 Args : n/a
154 is_error()
156 Usage : if ( $qrz->is_error )
157 Function : test for an error if one was returned from the call to the XML site
158 Returns : a true value if there has been an error
159 Args : n/a
160 error_message()
162 Usage : my $err_msg = $qrz->error_message;
163 Function : if there was an error message when trying to call the XML site, this is it
164 Returns : a string (the error message)
165 Args : n/a
166
168 · XML::Simple
169 · LWP::UserAgent
171 · An Internet connection
173 · A QRZ.COM subscription that includes access to the QRZ XML Database
175 Service
176
178 · Improve error checking and handling.
179 · Session key reuse between instances (maybe).
181 · Look into any possible needed escaping, filtering, etc.
183
185 This module accesses data from the widely popular QRZ.COM Database.
186 See http://www.qrz.com
187
189 · In order to use this module you need to have a subscription for the
190 QRZ XML Database Service. See http://online.qrz.com
191 · The technical reference for the QRZ XML Database Service is at
193 http://online.qrz.com/specifications.html
194
196 Brad McConahay N8QQ, "<brad at n8qq.com>"
197
199 Copyright 2008-2009 Brad McConahay N8QQ, all rights reserved.
200 This program is free software; you can redistribute it and/or modify it
202 under the same terms as Perl itself.
203perl v5.12.0 2009-11-02 Ham::Reference::QRZ(3)