1Ham::Reference::QRZ(3)User Contributed Perl DocumentationHam::Reference::QRZ(3)
2
3
4

NAME

6       Ham::Reference::QRZ - An object oriented front end for the QRZ.COM
7       Amateur Radio callsign database
8

VERSION

10       Version 0.04
11

SYNOPSIS

13        use Ham::Reference::QRZ;
14        use Data::Dumper;
15
16        my $qrz = Ham::Reference::QRZ->new(
17          callsign => 'N8QQ',
18          username => 'your_username',
19          password => 'your_password'
20        );
21
22        # 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
28        # 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
34        # set a different callsign to look up
35        $qrz->set_callsign('W8IRC');
36
37        # get the listing and print some specific info
38        $listing = $qrz->get_listing;
39        print "Name: $listing->{name}\n";
40
41        # 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
46        # show some session info
47        print "Lookups in current 24 hour period: $session->{Count}\n";
48        print "QRZ subscription expiration: $session->{SubExp}\n";
49
50        # show the ARRL section
51        my $arrl_section = $qrz->get_arrl_section;
52        print "ARRL Section: $arrl_section\n";
53
54        # show biography details, if any
55        my $bio = $qrz->get_bio_file;
56        print "Biography: $bio\n";
57

DESCRIPTION

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
63       This module uses the QRZ XML Database Service, which requires a
64       subscription from QRZ.COM.
65
66       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
74       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
79       This module does not handle any management of reusing session keys at
80       this time.
81

CONSTRUCTOR

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
89                   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

METHODS

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
119   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
125   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
131   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
139   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
145   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
151   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
161   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
172   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
182   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
192   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
200   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
209   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
215   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
221   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

DEPENDENCIES

228       •   XML::Simple
229
230       •   LWP::UserAgent
231
232       •   HTML::Entities
233
234       •   An Internet connection
235
236       •   A QRZ.COM subscription that includes access to the QRZ XML Database
237           Service
238

TODO

240       •   Session key reuse between instances (maybe).
241
242       •   Look into any escaping or filtering of data that would be helpful,
243           particularly with regard to get_bio_file().
244

ACKNOWLEDGEMENTS

246       Thanks to Thomas Schaefer NY4I for the idea, original code, and data
247       for the ARRL Section additions!
248
249       This module accesses data from the widely popular QRZ.COM Database.
250       See http://www.qrz.com
251

SEE ALSO

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
256       •   The technical reference for the QRZ XML Database Service is at
257           http://www.qrz.com/XML/current_spec.html
258

AUTHOR

260       Brad McConahay N8QQ, "<brad at n8qq.com>"
261
263       "Ham::Reference::QRZ" is Copyright (C) 2008-2016 Brad McConahay N8QQ.
264
265       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
269       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.
272
273
274
275perl v5.38.0                      2023-07-20            Ham::Reference::QRZ(3)
Impressum