The QRZ XML Interface Specification

Title:	QRZ XML Logbook Data Specification
Version:	1.12
Date:	September 17, 2009
Author:	Fred Lloyd, AA7BQ
Email:	flloyd@qrz.com

Overview

This document describes the interface specification for access to QRZ's XML data service. This interface provides network access to raw data from the QRZ.COM servers and databases.

Access to this interface requires user authentication through the use of a valid QRZ.COM username and password. Users may be both subscribers and non-subscribers, however, those not having a subscription will have limited capabilities.

For subscription rates and information see our subscription info page

Access Methodology

Transactional access is provided by the XML server. Requests are sent as arguments to a URL and the results are returned as XML formatted data.

To begin a transaction or series of transactions, the client program must first authenticate the user and obtain a session key. The session key must be sent as a parameter along with all subsequent communications with the server.

A session key remains valid for a period of time which may be varied by the server. Most keys are good for at least a few hours, sometimes more. It is essential that session keys be reused by the client program until they expire. Initial login tends to be slow and should be avoided unless necessary.

A typical client program will perform a login transaction to obtain a fresh session key and will save that key for further use. The key may be stored on the local computer, or it may be held in memory. A required capability of any client program is the ability to redo the login sequence when necessary and to otherwise use an existing key.

A session key is valid for one user only and may become invalidated should the user's IP address change in midstream. The interface does not use HTTP cookies.

QRZ XML Data Structure

The QRZ XML data structure follows the standard proposed by WWW.W3C.ORG. QRZ's top-level node is the <QRZDatabase> element. All responses from the QRZ server are prefaced with this element. Three child node types are defined. These include:

<Session>
<Callsign>
<Bio>

Each of these child nodes is described in detail below, however, the following notice regarding our XML structure must be closely observed:

The XML data supplied by this interface may be extended at any time in a forward compatible manner. QRZ may add new XML nodes and/or attributes at any time. Therefore, it is critically important that software developers carefully parse the data received in a accordance with the XML 1.0 standard. User programs that use QRZ XML data must be prepared to ignore any unrecognized nodes or attributes, and must not depend on the order in which nodes or sub-nodes appear within the response.

The Session Node

The Session node contains information pertaining to the status of the user's session, error codes and informational messages relating to the request.

Setting up a Session
A simple login, which can be tested using any browser, is to pass the username and password as arguments to the server's URL. The QRZ XML interface is available from these equivalent URL's:

http://www.qrz.com/xml
http://xml.qrz.com/xml
http://xml.qrz.com/bin/xml

The first URL, i.e. http://www.qrz.com/xml is the preferred address while the remaining addresses are maintained for legacy applications. All are served by the same server process.

To perform a simple login, the client program sends the username and password using either an HTTP GET or POST operation. A typical login exchange looks like this:

    http://www.qrz.com/xml?username=xx1xxx;password=abcdef;agent=q5.0

The URI may use either the ampersand (&) or the semicolon (;) as the parameter separator.

Session Input Fields:

username - a valid QRZ user name
password - the correct password for the username
agent - a string that contains the product name and version of the client program

The only required parameters are username and password, however the use of the agent parameter is strongly recommend. The agent= parameter permits us to stay abreast of which programs our members are using, and potentially to notify the program suppliers. Developers are urged to register their client program agent names with QRZ by sending an email to flloyd@qrz.com.

If the username and password are accepted, the system will respond with:

<?xml version="1.0" ?> 
<QRZDatabase version="1.12" xmlns="http://xml.qrz.com">
  <Session>
    <Key>2331uf894c4bd29f3923f3bacf02c532d7bd9</Key> 
    <Count>123</Count> 
    <SubExp>Wed Jan 1 12:34:03 2010</SubExp> 
    <GMTime>Sun Aug 16 03:51:47 2009</GMTime> 
  </Session>
</QRZDatabase>

As with all server responses, the return begins with QRZDatabase. Note that the QRZDatabase node also contains two attributes, version and xmlns. The version attribute represents the QRZ XML version currently in use as defined by the release number of this specification. The xmlns attribute identifies the XML namespace of this product.

The possible elements in a session node are:

Session section fields

Field	Description
Key	a valid user session key
Count	Number of lookups performed by this user in the current 24 hour period
SubExp	time and date that the users subscription will expire - or - "non-subscriber"
GMTime	Time stamp for this message
Message	An informational message for the user
Error	XML system error message

Both Error and Message responses should be presented to the end user. Typical Error responses include things such as "password incorrect", "session timeout", and "callsign not found". Typical Message messages return notices like: "A subscription is required to obtain the complete data.".

A user session is established whenever a session key is returned. Any response from from the server that does not contain the Key element indicates that no valid session exists and that a re-login is required to continue.

The Count, SubExp, and GMTime nodes are simply informational and may be shown to the end user if determined to be useful.

Callsign Lookups

To make a callsign query, simply pass the current session key in the s= parameter, followed by a callsign= parameter.

A typical request might look like this:

http://www.qrz.com/xml?s=f894c4bd29f3923f3bacf02c532d7bd9;callsign=aa7bq

This returns the following data:

<?xml version="1.0" ?> 
<QRZDatabase version="1.12" xmlns="http://www.qrz.com">
  <Callsign>
      <call>AA7BQ</call> 
      <fname>FRED L</fname> 
      <name>LLOYD</name> 
      <addr1>8711 E PINNACLE PEAK RD 159</addr1> 
      <addr2>SCOTTSDALE</addr2> 
      <state>AZ</state> 
      <zip>85014</zip> 
      <country>USA</country> 
      <lat>34.23456</lat> 
      <lon>-112.34356</lon> 
      <grid>DM32af</lat> 
      <county>Maricopa</county> 
      <fips>04013</fips> 
      <land>USA</land> 
      <efdate>2000-01-20</efdate> 
      <expdate>2010-01-20</expdate> 
      <p_call>KJ6RK</p_call> 
      <class>E</class> 
      <codes>HAI</codes> 
      <qslmgr>NONE</qslmgr> 
      <email>flloyd@qrz.com</email> 
      <url>http://www.qrz.com/callsign/aa7bq</url> 
      <u_views>115336</views> 
      <bio>3937/2003-11-04</bio> 
      <image>http://www.qrz.com/hampix/q/b/aa7bq.1012971412.jpg</image> 
      <serial>3626</serial> 
      <moddate>2003-11-04 19:37:02</moddate> 
      <MSA>6200</MSA> 
      <AreaCode>602</AreaCode> 
      <TimeZone>Mountain</TimeZone> 
      <GMTOffset>-7</GMTOffset> 
      <DST>N</DST> 
      <eqsl>Y</eqsl> 
      <mqsl>Y</mqsl> 
      <cqzone>3</cqzone> 
      <ituzone>2</ituzone> 
      <locref>1</locref> 
      <born>1953</born> 
  </Callsign>
  <Session>
      <Key>2331uf894c4bd29f3923f3bacf02c532d7bd9</Key> 
      <Count>123</Count> 
      <SubExp>Wed Jan 1 12:34:03 2010</SubExp> 
      <GMTime>Sun Nov 16 04:13:46 2009</GMTime> 
  </Session>
</QRZDatabase>

The possible callsign data fields are listed below. Not all fields may be returned with each request. The field ordering is arbitrary and subject to change.

Callsign node fields

Field	Description
call	callsign
fname	first name
name	last name
addr1	address line 1 (i.e. house # and street)
addr2	address line 2 (i.e, city name)
state	state (USA Only)
zip	Zip/postal code
country	mailing address country
lat	lattitude of address (signed decimal) S < 0 > N
lon	longitude of address (signed decimal) W < 0 > E
grid	grid locator
county	county name (USA)
fips	FIPS county identifier (USA)
land	country of callsign issue
efdate	license effective date (USA)
expdate	license expiration date (USA)
p_call	previous callsign
class	license class
codes	license type codes (USA)
qslmgr	QSL manager info
email	email address
url	web page address
u_views	QRZ web page views
bio	biography tag info (length/date)
image	primary image url
serial	QRZ db serial number
moddate	QRZ db last modified date
MSA	Metro Service Area (USPS)
AreaCode	Telephone Area Code (USA)
TimeZone	Time Zone (USA)
GMTOffset	GMT Time Offset
DST	Daylight Saving Time Observed
eqsl	Will accept e-qsl
mqsl	Will return paper QSL
cqzone	CQ Zone identifier
ituzone	ITU Zone identifier
locref	location reference code (lat/long source)
born	operator's year of birth
user	User who manages this callsign on QRZ
lotw	Will accept LOTW
iota	IOTA Designator

Biography Data

The <bio> field is present in the callsign record whenever a biography exists for the indicated callsign on the server. The <bio> field in the callsign record contains the size of the bio and the date of last update To fetch a bio URL, issue a separate request using the bio= parameter with a callsign.

Here is a typical biography fetch operation:

http://www.qrz.com/xml?s=2331uf894c4bd29f3923f3bacf02c532d7bd9;bio=g1srd

And this is the result:

<?xml version="1.0" ?> 
<QRZDatabase version="1.12" xmlns="http://www.qrz.com">
    <Bio>
	<call>g1srd</call> 
	<size>258</size> 
	<bio>http://www.qrz.com/hampages/d/r/g1srd/bio.html</bio> 
	<modified>2008-10-10</modified> 
    </Bio>
    <Session>
	<Key>3431u4eaf13b8336d61982c1fd1099c9a38ac</Key> 
	<GMTime>Sun Nov 16 04:43:21 2003</GMTime> 
    </Session>
</QRZDatabase>

Bio node fields

Field	Description
call	callsign for this bio
size	length in bytes of the bio text
bio	fully qualified URL to the HTML biography file
modified	date of last bio text modification

Note that the bio URL returned by this call is not guaranteed to be always the same. The file referenced by the bio URL will be an HTML file. Note that any <img> tags in the returned HTML document will contain relative path links and will necessarily need fixup in order to display the images. Repaired image URL's will have the same directory path prefix as the bio.html file. In other words, the images for a particular bio.html file will be located in the same directory as the HTML file itself.

Error Conditions

There are two general types of errors. Data errors, which are typically of the genere "item not found", and Session errors which deal with the user's session key. If the <Session> node contains an <Error> sub-node, then the message should be examined and/or presented to the user.

Here's an example of a typical "callsign not found" error:

<?xml version="1.0" ?> 
<QRZDatabase version="1.12" xmlns="http://www.qrz.com">
    <Session>
	<Error>Not found: g1srdd</Error> 
	<Key>1232u4eaf13b8336d61982c1fd1099c9a38ac</Key> 
	<GMTime>Sun Nov 16 05:07:14 2003</GMTime> 
    </Session>
</QRZDatabase>

Should a session expire or become invalidated, the <Key> field will not be sent.

Here's an example of a "Session" error:

<?xml version="1.0" ?> 
<QRZDatabase version="1.12" xmlns="http://www.qrz.com">
    <Session>
	<Error>Session Timeout</Error> 
	<GMTime>Sun Nov 16 05:11:58 2003</GMTime> 
    </Session>
</QRZDatabase>

A special Error message, Connection refused is significant in that it indicates that service is refused for the given user. No further explanation is given, however, it does indicate that successful login will not be possible for at least 24 hours.

Further Information

For questions concerning this document or the XML interface, please contact the author at flloyd@qrz.com .

Revision History:

1.0 Sat Nov 15, 2003	original draft
1.1 Mon Feb 28, 2005	update to reflect correct image path
1.2 Wed Mar 2, 2005	image tag now contains URL
1.3 Thu Jun 22, 2006	reworded and added Alert tag and extensions policy
1.4 Thu Jun 23, 2006	documented the "agent=" parameter
1.5 Wed Dec 3, 2008	some new data fields, field description section
1.6 Wed Jan 15, 2009	rename site from online.qrz.com to xml.qrz.com
1.7 Wed Jan 15, 2009	new bio fetch procedure
1.8 Fri Apr 10, 2009	field list (grid), session key description, Expires removed
1.9 Thu Sep 10, 2009	numerous incl. QRZDatabase version attribute
1.10 Sat Sep 12, 2009	some typographical corrections
1.11 Sun Sep 13, 2009	add emphasis to the Extensions paragraph
1.12 Thu Sep 17, 2009	rewrite - new Message node, new explanations.