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.04
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, bio and other information
23 my $listing = $qrz->get_listing;
24 my $bio = $qrz->get_bio;
25 my $dxcc = $qrz->get_dxcc;
26 my $session = $qrz->get_session;
27 # dump the data to see how it's structured
29 print Dumper($listing);
30 print Dumper($bio);
31 print Dumper($dxcc);
32 print Dumper($session);
33 # set a different callsign to look up
35 $qrz->set_callsign('W8IRC');
36 # get the listing and print some specific info
38 $listing = $qrz->get_listing;
39 print "Name: $listing->{name}\n";
40 # show some dxcc info
42 print "DXCC Continent: $dxcc->{continent}\n";
43 print "DXCC Name: $dxcc->{name}\n";
44 print "CQ Zone: $dxcc->{cqzone}\n";
45 # show some session info
47 print "Lookups in current 24 hour period: $session->{Count}\n";
48 print "QRZ subscription expiration: $session->{SubExp}\n";
49 # show the ARRL section
51 my $arrl_section = $qrz->get_arrl_section;
52 print "ARRL Section: $arrl_section\n";
53 # show biography details, if any
55 my $bio = $qrz->get_bio_file;
56 print "Biography: $bio\n";
57
59 The "Ham::Reference::QRZ" module provides an easy object oriented front
60 end to access Amateur Radio callsign data from the QRZ.COM online
61 database.
62 This module uses the QRZ XML Database Service, which requires a
64 subscription from QRZ.COM.
65 The QRZ XML Database Service specification states "The data supplied by
67 the XML port may be extended in a forwardly compatible manner. New XML
68 elements and database objects (with their associated elements) may be
69 transmitted at any time. It is the developers responsibility to have
70 their program ignore any unrecognized objects and/or elements without
71 raising an error, so long as the information received consists of
72 properly formatted XML."
73 Therefore, this module will not attempt to list or manage individual
75 elements of a callsign. You will need to inspect the hash reference
76 keys to see which elements are available for any given callsign, as
77 demonstrated in the synopsis.
78 This module does not handle any management of reusing session keys at
80 this time.
81
83 new()
84 Usage : my $qrz = Ham::Reference::QRZ->new;
85 Function : creates a new Ham::Reference::QRZ object
86 Returns : a Ham::Reference::QRZ object
87 Args : a hash:
88 key required? value
90 ------- --------- -----
91 timeout no an integer of seconds to wait for
92 the timeout of the xml site
93 default = 10
94 api_url no a string to override the default
95 base api url
96 default = http://xmldata.qrz.com/xml
97 callsign no you may specify a callsign to look up
98 here, or you may do it later with the
99 set_callsign() method
100 username no you may specify a username to log in with
101 here, or you may do it later with the
102 set_username() method
103 password no you may specify a password to log in with
104 here, or you may do it later with the
105 set_password() method
106 key no set a session key here if you have a valid key so
107 that no time is wasted doing another login. only
108 useful if you are managing the reuse of your own keys
109
111 set_callsign()
112 Usage : $qrz->set_callsign( $callsign );
113 Function : set the callsign to look up at QRZ
114 Returns : n/a
115 Args : a case-insensitive string containing an Amateur Radio callsign.
116 Notes : calling this will reset the listing and bio data to null until
117 you do another get_listing() or get_bio(), respectively.
118 set_username()
120 Usage : $qrz->set_username( $username );
121 Function : set the username for your QRZ subscriber login
122 Returns : n/a
123 Args : a string
124 set_password()
126 Usage : $qrz->set_password( $password );
127 Function : set the password for your QRZ subscriber login
128 Returns : n/a
129 Args : a string
130 set_key()
132 Usage : $qrz->set_key( $session_key );
133 Function : set a session key for retrieving data at QRZ
134 Returns : n/a
135 Args : a string
136 Notes : this is useful only if you already have a valid key before the first login
137 during a particular instance of the module.
138 set_timeout()
140 Usage : $qrz->set_timeout( $seconds );
141 Function : sets the number of seconds to wait on the xml server before timing out
142 Returns : n/a
143 Args : an integer
144 set_api_url()
146 Usage : $qrz->set_api_url( $url );
147 Function : overrides the base url path of the QRZ API URL. Example: http://xmldata.qrz.com/xml
148 Returns : n/a
149 Args : a string
150 get_listing()
152 Usage : $hashref = $qrz->get_listing;
153 Function : retrieves data for the standard listing of a callsign from QRZ
154 Returns : a hash reference
155 Args : n/a
156 Notes : if a session key has not already been set, this method will automatically login.
157 if a there is already listing information set from a previous lookup,
158 this will just return that data. call a new set_callsign() if you need to refresh
159 the data with a new call to the qrz database.
160 get_bio()
162 Usage : $hashref = $qrz->get_bio;
163 Function : retrieves data for the biography of a callsign from QRZ
164 Returns : a hash reference
165 Args : n/a
166 Notes : if a session key has not already been set, this method will automatically login.
167 if a there is already biographical information set from a previous lookup,
168 this will just return that data. call a new set_callsign() if you need to refresh
169 the data with a new call to the qrz database. this method only retrieves the meta
170 information about the bio. call get_bio_file to get the actual contents of the bio.
171 get_bio_file()
173 Usage : $scalar = $qrz->get_bio_file;
174 Function : retrieves the full biography of a callsign from QRZ, if any is available
175 Returns : a scalar
176 Args : n/a
177 Notes : if the get_bio method has not been called yet, it will be called first to get
178 the url for the bio file. any html entities in the contents of the bio will be
179 converted to plain text, and all html will be stripped. hard line breaks will be
180 left in place. suggestions are welcome on how this data might better be filtered.
181 get_dxcc()
183 Usage : $hashref = $qrz->get_dxcc;
184 Function : retrieves DXCC information for a callsign from QRZ
185 Returns : a hash reference
186 Args : n/a
187 Notes : if a session key has not already been set, this method will automatically login.
188 if a there is already dxcc information set from a previous lookup,
189 this will just return that data. call a new set_callsign() if you need to refresh
190 the data with a new call to the qrz database.
191 get_arrl_section()
193 Usage : $scalar = $qrz->get_arrl_section;
194 Function : returns ARRL Section information for a callsign
195 Returns : a scalar
196 Args : n/a
197 Notes : if get listing has not yet been called, it will call get_listing to get state and county.
198 this method gets its data internally, and does not query the qrz xml server.
199 login()
201 Usage : $session = $qrz->login;
202 Function : initiates a login to the QRZ xml server
203 Returns : a hash reference of the session data
204 Args : n/a
205 Notes : this generally shouldn't need to be used since the get_listing() and get_bio()
206 methods will automatically initiate a login to the server if it hasn't already
207 been done.
208 get_session()
210 Usage : $session = $qrz->get_session;
211 Function : retrieves the session information from the most recent call to the XML site
212 Returns : a hash reference of the session data
213 Args : n/a
214 is_error()
216 Usage : if ( $qrz->is_error )
217 Function : test for an error if one was returned from the call to the XML site
218 Returns : a true value if there has been an error
219 Args : n/a
220 error_message()
222 Usage : my $err_msg = $qrz->error_message;
223 Function : if there was an error message when trying to call the XML site, this is it
224 Returns : a string (the error message)
225 Args : n/a
226
228 • XML::Simple
229 • LWP::UserAgent
231 • HTML::Entities
233 • An Internet connection
235 • A QRZ.COM subscription that includes access to the QRZ XML Database
237 Service
238
240 • Session key reuse between instances (maybe).
241 • Look into any escaping or filtering of data that would be helpful,
243 particularly with regard to get_bio_file().
244
246 Thanks to Thomas Schaefer NY4I for the idea, original code, and data
247 for the ARRL Section additions!
248 This module accesses data from the widely popular QRZ.COM Database.
250 See http://www.qrz.com
251
253 • In order to use this module you need to have a subscription for the
254 QRZ XML Database Service. See http://www.qrz.com/XML/index.html
255 • The technical reference for the QRZ XML Database Service is at
257 http://www.qrz.com/XML/current_spec.html
258
260 Brad McConahay N8QQ, "<brad at n8qq.com>"
261
263 "Ham::Reference::QRZ" is Copyright (C) 2008-2016 Brad McConahay N8QQ.
264 This module is free software; you can redistribute it and/or modify it
266 under the terms of the Artistic License 2.0. For details, see the full
267 text of the license in the file LICENSE.
268 This program is distributed in the hope that it will be useful, but it
270 is provided "as is" and without any express or implied warranties. For
271 details, see the full text of the license in the file LICENSE.
272perl v5.36.0 2023-01-20 Ham::Reference::QRZ(3)