Specifications for XML access to the QRZ Database

Summary

This document specifies the XML interface between external programs and the QRZ.COM network database.

Description

A programmatic access to the QRZ.COM callsign database is provided for programmers and developers who which to integrate realtime online database queries into their applications environment. The interface provided by QRZ loosely conforms to XML standards and has been verified to work with tools such as the Microsoft .NET programming environment, Internet Explorer, and Netscape Navigator (including Mozilla).

Access to the database requires a username and password. See http://online.qrz.com for user registration information.

A registered user will have a username and password that are required to gain access to the database. The QRZ server maintains login/logout state information on the user session through the use of session keys. Upon a successful login, an encrypted session key is returned to the user's application which must be cached for use with subsequent queries.

A session key is a unique token that identifies the user. No two users may utilize the same session key. Session keys are bound to to the user and machine from which the login took place.

Session keys are valid for a maximum of 24 hours, providing that the above conditions are met, namely, that a user remains logged in from the same machine. Users may login from multiple locations, however, upon moving to the new location, the previous location's session key is invalidated.

A new session key may be established by simply sending the user's name and password to the server.

Establishing a Session

To establish a session, the calling appliation sends the username and password in the URL, or, through an HTTP POST operation. Either method achieves the same result. A typical login exchange looks like this:

http://online.qrz.com/bin/xml?username=xx1xxx;password=abcdef

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

<?xml version="1.0" ?> 
<QRZDatabase xmlns="http://online.qrz.com">
  <Session>
    <Key>2331uf894c4bd29f3923f3bacf02c532d7bd9</Key> 
    <GMTime>Sun Nov 16 03:51:47 2003</GMTime> 
  </Session>
</QRZDatabase>

Note the Key parameter that is sent as a part of the Session group. This is your session key.

Fetching Data

To make a callsign query, a "callsign=" and an "s=" parameter is needed. These parameters are passed in the URL as follows:

http://online.qrz.com/bin/xml?s=2331uf894c4bd29f3923f3bacf02c532d7bd9;callsign=aa7bq

This request would return the following data:

<?xml version="1.0" ?> 
<QRZDatabase xmlns="http://online.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> 
      <county>Maricopa</county> 
      <land>USA</land> 
      <efdate>2000-01-20</efdate> 
      <expdate>2010-01-20</expdate> 
      <p_call>KJ6RK</p_call> 
      <class>E</class> 
      <codes>HAI</codes> 
      <email>flloyd@qrz.com</email> 
      <url>http://www.qrz.com/callsign/aa7bq</url> 
      <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> 
  </Callsign>
  <Session>
      <Key>2331uf894c4bd29f3923f3bacf02c532d7bd9</Key> 
      <GMTime>Sun Nov 16 04:13:46 2003</GMTime> 
  </Session>
</QRZDatabase>

Note that the session key is returned in all successful responses from the server. The fields shown above are typical for the database and should be self explanatory. Just ask me if you have any questions.

Note that blank fields are not transmitted. If, for example, there is no email address on file for the callsign then the <email> field will not appear. With this behavior in mind, your application must parse the field names as they arrive in the inpout stream and not rely on their positional arrangement in the server response.

Biography Data

The <bio> field is present in the callsign record whenever a biography exists for the indicated callsign on the server. To fetch a bio, simply use the URL paramater bio=[callsign] instead of callsign=[callsign]. Note that bio= and the callsign= requests must be issued separately.

Here is a typical biography fetch operation:

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

And this is the result:

<?xml version="1.0" ?> 
<QRZDatabase xmlns="http://online.qrz.com">
    <Bio>
	<call>g1srd</call> 
	<size>258</size> 
	<bio>This is my home made 2 element quad for 21Mhz,24Mhz,28Mhz. 3
	    elements for 50Mhz and 5 elements for 145Mhz.That i am sure will be
	    expanded for more bands in the future. The radio is a Yaesu FT-847,
	    100Watts and the microphone is Yaesu MD-100 desk mic.73s _._
	</bio> 
	<modified>2003-10-10</modified> 
    </Bio>
    <Session>
	<Key>3431u4eaf13b8336d61982c1fd1099c9a38ac</Key> 
	<GMTime>Sun Nov 16 04:43:21 2003</GMTime> 
    </Session>
</QRZDatabase>

Images (QSL Pictures)

When an image is available for the selected callsign, its record will contain an <Image> tag that contains the fully qualified URL to the image, which may be located on a different host.

All of our image files are in JPEG (.jpg) format, and the file name must consist completely of lower case letters.

Error Conditions

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

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

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

Session errors differ in that when a session becomes invalid, its Key is not sent.

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

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

Whenever a response is received that does not contain a Session Key, the username= and password= parameters must be again sent to establish a new session.

Further Information

For questions concerning this document or the XML interface, please contact the author at the email address listed above.

Revision History:

1.0 Sat Nov 15 22:24:39 MST 2003 - original draft

1.1 Mon Feb 28 11:48:13 MST 2005 - updated to reflect correct image path

1.2 Wed Mar 2 21:29:03 MST 2005- updated - image tag now contains URL