Ham::Re...nce::QRZ(3)

📦
version 0.04 · 2 versions
, in fedora 43

🎀 Ham::Reference::QRZ 🎀

okay bestie, this is a page from the User Contributed Perl Documentation collection, and it's about Ham::Reference::QRZ — an object oriented front end for the QRZ.COM Amateur Radio callsign database. it's giving very niche, very powerful, and we're gonna walk through it together 💖

✨ VERSION ✨

Version 0.04 — yeah she's a lil vintage but she works 💅

🌈 SYNOPSIS 🌈

here's the whole vibe, copy-paste ready:

use Ham::Reference::QRZ;
use Data::Dumper;

my $qrz = Ham::Reference::QRZ->new(
  callsign => 'N8QQ',
  username => 'your_username',
  password => 'your_password'
);

# get the listing, bio and other information
my $listing = $qrz->get_listing;
my $bio = $qrz->get_bio;
my $dxcc = $qrz->get_dxcc;
my $session = $qrz->get_session;

# dump the data to see how it's structured
print Dumper($listing);
print Dumper($bio);
print Dumper($dxcc);
print Dumper($session);

# set a different callsign to look up
$qrz->set_callsign('W8IRC');

# get the listing and print some specific info
$listing = $qrz->get_listing;
print "Name: $listing->{name}\n";

# show some dxcc info
print "DXCC Continent: $dxcc->{continent}\n";
print "DXCC Name: $dxcc->{name}\n";
print "CQ Zone: $dxcc->{cqzone}\n";

# show some session info
print "Lookups in current 24 hour period: $session->{Count}\n";
print "QRZ subscription expiration: $session->{SubExp}\n";

# show the ARRL section
my $arrl_section = $qrz->get_arrl_section;
print "ARRL Section: $arrl_section\n";

# show biography details, if any
my $bio = $qrz->get_bio_file;
print "Biography: $bio\n";

🦋 DESCRIPTION 🦋

so "Ham::Reference::QRZ" is a module that gives you a super easy, object oriented front end for pulling Amateur Radio callsign data out of the QRZ.COM online database. no cap, it's the plug 🔌

it does this through the QRZ XML Database Service, which — heads up — requires a subscription from QRZ.COM. pay up bestie, that's the deal 💸

the QRZ XML Database Service specification says, and I quote:

"The data supplied by the XML port may be extended in a forwardly compatible manner. New XML elements and database objects (with their associated elements) may be transmitted at any time. It is the developers responsibility to have their program ignore any unrecognized objects and/or elements without raising an error, so long as the information received consists of properly formatted XML."

which basically means: this module is not gonna try to list or manage individual elements of a callsign. nope. you have to go look at the hash reference keys yourself to see which elements are available for any given callsign — the synopsis shows you exactly how. peek inside, girl, that's the whole point 👀

also fyi: this module does not handle any management of reusing session keys at this time. noted.

🌸 CONSTRUCTOR 🌸

new()

  • Usage — my $qrz = Ham::Reference::QRZ->new;
  • Function — creates a brand new Ham::Reference::QRZ object, fresh out the box ✨
  • Returns — a Ham::Reference::QRZ object
  • Args — a hash, and here's the tea on every single key:
  • timeout — not required. an integer of seconds to wait for the timeout of the xml site. default = 10
  • api_url — not required. a string to override the default base api url. default = http://xmldata.qrz.com/xml
  • callsign — not required. you can drop a callsign to look up right here, or you can do it later with the set_callsign() method
  • username — not required. you can drop a username to log in with right here, or you can do it later with the set_username() method
  • password — not required. you can drop a password to log in with right here, or you can do it later with the set_password() method
  • key — not required. set a session key here if you have a valid key so that no time is wasted doing another login. only useful if you are managing the reuse of your own keys

💜 METHODS 💜

set_callsign()

  • Usage — $qrz->set_callsign( $callsign );
  • Function — sets the callsign to look up at QRZ
  • Returns — n/a
  • Args — a case-insensitive string containing an Amateur Radio callsign.
  • Notes — calling this will reset the listing and bio data to null until you do another get_listing() or get_bio(), respectively. so like, don't be surprised when it's empty, she warned you 🙈

set_username()

  • Usage — $qrz->set_username( $username );
  • Function — sets the username for your QRZ subscriber login
  • Returns — n/a
  • Args — a string

set_password()

  • Usage — $qrz->set_password( $password );
  • Function — sets the password for your QRZ subscriber login
  • Returns — n/a
  • Args — a string

set_key()

  • Usage — $qrz->set_key( $session_key );
  • Function — sets a session key for retrieving data at QRZ
  • Returns — n/a
  • Args — a string
  • Notes — this is useful only if you already have a valid key before the first login during a particular instance of the module. iykyk 🔑

set_timeout()

  • Usage — $qrz->set_timeout( $seconds );
  • Function — sets the number of seconds to wait on the xml server before timing out
  • Returns — n/a
  • Args — an integer

set_api_url()

  • Usage — $qrz->set_api_url( $url );
  • Function — overrides the base url path of the QRZ API URL. Example: http://xmldata.qrz.com/xml
  • Returns — n/a
  • Args — a string

get_listing()

  • Usage — $hashref = $qrz->get_listing;
  • Function — retrieves data for the standard listing of a callsign from QRZ
  • Returns — a hash reference
  • Args — n/a
  • Notes — if a session key has not already been set, this method will automatically login. and if there is already listing information set from a previous lookup, this will just return that data. call a new set_callsign() if you need to refresh the data with a new call to the qrz database. periodt 💅

get_bio()

  • Usage — $hashref = $qrz->get_bio;
  • Function — retrieves data for the biography of a callsign from QRZ
  • Returns — a hash reference
  • Args — n/a
  • Notes — if a session key has not already been set, this method will automatically login. if there is already biographical information set from a previous lookup, this will just return that data. call a new set_callsign() if you need to refresh the data with a new call to the qrz database. important: this method only retrieves the meta information about the bio — call get_bio_file to get the actual contents of the bio 🫶

get_bio_file()

  • Usage — $scalar = $qrz->get_bio_file;
  • Function — retrieves the full biography of a callsign from QRZ, if any is available
  • Returns — a scalar
  • Args — n/a
  • Notes — if the get_bio method has not been called yet, it will be called first to get the url for the bio file. any html entities in the contents of the bio will be converted to plain text, and all html will be stripped. hard line breaks will be left in place. suggestions are welcome on how this data might better be filtered — the author literally said so, so slide into those suggestions bestie 💌

get_dxcc()

  • Usage — $hashref = $qrz->get_dxcc;
  • Function — retrieves DXCC information for a callsign from QRZ
  • Returns — a hash reference
  • Args — n/a
  • Notes — if a session key has not already been set, this method will automatically login. if there is already dxcc information set from a previous lookup, this will just return that data. call a new set_callsign() if you need to refresh the data with a new call to the qrz database.

get_arrl_section()

  • Usage — $scalar = $qrz->get_arrl_section;
  • Function — returns ARRL Section information for a callsign
  • Returns — a scalar
  • Args — n/a
  • Notes — if get listing has not yet been called, it will call get_listing to get state and county. this method gets its data internally, and does not query the qrz xml server. so it's fast, no network drama 🌈

login()

  • Usage — $session = $qrz->login;
  • Function — initiates a login to the QRZ xml server
  • Returns — a hash reference of the session data
  • Args — n/a
  • Notes — this generally shouldn't need to be used since the get_listing() and get_bio() methods will automatically initiate a login to the server if it hasn't already been done. she's independent, she logs herself in 💁‍♀️

get_session()

  • Usage — $session = $qrz->get_session;
  • Function — retrieves the session information from the most recent call to the XML site
  • Returns — a hash reference of the session data
  • Args — n/a

is_error()

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

error_message()

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

🧚 DEPENDENCIES 🧚

she does not come alone, she brings her whole entourage:

  • XML::Simple
  • LWP::UserAgent
  • HTML::Entities
  • An Internet connection (yes fr, no wifi no data, no lookups 😭)
  • A QRZ.COM subscription that includes access to the QRZ XML Database Service

💀 TODO 💀

the author's own lil wishlist, we respect the transparency:

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

👑 ACKNOWLEDGEMENTS 👑

shoutout to Thomas Schaefer NY4I for the idea, original code, and data for the ARRL Section additions! iconic behavior, we love to see it 🫶

and also — this module accesses data from the widely popular QRZ.COM Database. See http://www.qrz.com

⭐ SEE ALSO ⭐

💖 AUTHOR 💖

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

"Ham::Reference::QRZ" is Copyright (C) 2008-2016 Brad McConahay N8QQ.

This module is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0. For details, see the full text of the license in the file LICENSE.

This program is distributed in the hope that it will be useful, but it is provided "as is" and without any express or implied warranties. For details, see the full text of the license in the file LICENSE.

and that's the whole page bestie, no notes 💅 this was Ham::Reference::QRZ(3), served up by perl v5.42.0 and dated 2025-07-25, straight out of the User Contributed Perl Documentation. go forth and look up some callsigns, you've got this 🦋✨

📦 where this page comes from