Programming notes

Ham::Resources::HamQTH

The Ham::Resources::HamQTH is born because the developer access to QRZ.com XML Service is currently paying. So the friend Petr (OK2CQR) has created a new XML free service to be used in applications for hams.

The Ham::Resources::HamQTH module provides an easy way to access Amateur Radio callsign data from the HamQTH.com online free database.

This module uses the HamQTH XML database service, which requires a valid user account.

This module requieres XML::LibXML::Reader and LWP::UserAgent to obtain a hash from the response XML.

For create the new object you must use:

my $qth = Ham::Resources::HamQTH->new(
                       callsign       => 'callsign to find',
                       username       => 'your HamQTH username',
                       password       => 'your HamQTH password',
                       strip_html_bio => 1,
               );

This arguments are requiered, except timeout that is optional argument.

• callsign: a text, this is the callsign to search
• username: a text, this must be a valid account username for Hamqth.com
• password: a text, this must be a valid account password for Hamqth.com
• timeout: an integer, this is de timeout value for the connexion. By default is 10.
• strip_html_bio: binary, this value strip HTML code from the Biography. By default is ‘1’ (pass HTML code) otherwise ‘0’ strip HTML code and show the Bio in text plain.

Use it is very simple!!!

The new() call to a login internal function for validate the user against the server and to send the callsign to search.
The HamQTH service always response with a XML, that maybe with data founds or a error message.
In this response also are the session ID, that the module save in a file with a timestamp. The session duration is from 1 hour.
When a new callsign is searching, the module check the file and compare with the actual time(), if this request is between the hour session period use the same session ID, otherwise call to login() function and save the new session ID and the new timestamp.

Then you have two methods to use:

• get_list(): with no requiered arguments, retrieves a list of elements, or tags, from the XML that have a valid value.
• get_bio(): retrieves a complet hash with tags and values. This method is not arguments requiered.
• get_dxcc(): retrieves the DXCC information. The callsign may be a valid DXCC or ADIF number.

For example:

If you’d like looking for a callsign you can do:

	my $bio = $qth->get_bio;
	foreach (sort keys %{$bio}){
		     print $_.": ".$bio->{$_}."\n";
	}

The function get_bio() first check if the object hasn’t a null callsign.

Then it checks if exists a valid session ID and uses it or forces a new login() to get a new valid session ID. Then it construct the URL with valids arguments, like this:

	my $url = "$qth_url/xml.php?id=".$self->{_session_id}."&callsign=".$self->{_callsign}."&prg=".$self->{_agent};

Where it contains the session ID, the callsign to search and argument ‘prg‘ that is a string with the name of the module and its version that is requiered for the database service for statistics purposes.

Then, it calls to internal function _get_content() that use a GET method for launch the request against the XML service database.

The XML::LibXML::Reader retrieves the XML server response and then it calls to an internal function that clean the response and return a hash.

An example of output:

		BIO for: ea3hmb
	----------------------------------------
    adif: 281
    adr_adif: 281
    adr_city: Barcelona
	adr_country: Spain
	adr_name: Carlos Juan
	adr_street1: My house 
	adr_zip: 08005
    bio: <Text of the biograpahy if exists, maybe in text plain or HTML>
	birth_year: <When I was born :p>
	callsign: ea3hmb
    continent: EU
	country: Spain
	cq: 14
	email: <my email>
	eqsl: Y
	grid: jn11cj
	itu: 37
    latitude: 41.41385269165039
	lic_year: 2011
    link: <HamQTH URL of the callsign>
    longitude: 2.2143776416778564
	lookups: 138
	lotw: N
	nick: Carlos
	picture: <URL of the photo if exits>
	qsl: Y
	qsl_via: Direct or eQSL. SWL are Welcome
	qth: Barcelona
	skype: <my skype adress>
    utc_offset: -1

The get_dxcc() function is similar to get_bio(). You can call it with a valid DXCC code or an ADIF number, and return some information about the DXCC.

my $dxcc = $qth->get_dxcc;
foreach (sort keys %{$dxcc}) {
  print $_.": ".$dxcc->{$_}."\n";
}

The response is like that (for example for ADIF 281):

adif: 281
continent: EU
itu: 37
lat: 41.416
lng: -3.7
name: Spain
utc: -1
waz: 14

The function get_list() works like previous function, but returns a list with only the tags of the XML.

$bio = $qth->get_list;
foreach my $tag (@{$bio}) {
        print $tag."\n";
}

The number of response elements by the XML database can be different between each callsign, depending if it has any information of a callsign or not. For this reason exist the get_list() method, which retrieves a list of valid elements for a callsign found.

Also you can call only to an specific element for example:

	print "Callsign found: ".$bio->{callsign}."\n" if (!$bio->{error});

Here you can see how to check if there are errors … throught the $bio->{error}.

Errors messages are:

• Callsign not found
• Without callsign
• Lost internet connection
• Without access to the session file
• Fail on server response

ACKNOWLEDGEMENTS
This module accesses the data provided free by Petr (OK2CQR). See http://www.hamqth.com

COPYRIGHT AND LICENSE
This module is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.

Copyright (C) 2012-2014 by Carlos Juan Diaz (CJUAN) – EA3HMB

Good Perl!