Specifications for XML access to the QRZ Database

Title:	QRZ Online XML Callsign Database Specifications
Version:	1.4
Date:	Thu Jun 23 2006
Author:	Fred Lloyd, AA7BQ
Email:	flloyd@qrz.com

Summary

This document describes the XML interface provided for client programs that connect to QRZ.COM through its XML data port.

Description

The QRZ XML port provides data level access to the QRZ callsign database and selected content resources. The data provided by our XML port is mostly conformant to mainstream XML standards and has been designed with simplicity and flexibility as its primary goals. Our XML implementation works with Microsoft's .NET Framework which offers native XML support for data objects. Its simple design also makes it relatively easy to parse using ordinary programming languages of all types.
Access to the QRZ XML port requires a valid subscriber login consisting of a username and password, and a current, active subscription with QRZ. A variety of subscription plans may be offered, as well as free trials and/or complimentary subscriptions as deemed appropriate.
This specification is for indepentent comemrcial software developers as well as private individuals who wish to write software that interfaces directly with the QRZ database.
Users seeking to establish a subscription should refer to http://online.qrz.com for user registration information.

Sessions

The QRZ XML port maintains login/logout state information on for each user through the use of a session key. Upon successful login, an encrypted session key is returned to the client application which must be cached so that it can be used with subsequent data requests to the server.
Session keys are unique and are generated at anew upon each login. They contain state information that identifies a single user instance such that two users may not share the same username and password.
Session keys are valid for a maximum of 24 hours from a given login location. When another instance of the same user is detected, the previous session is invalidated, effectively logging out the first instance.
Network mobility is not a problem as a user may take his username and password and login from anywhere, so long as only one instance of his username is logged into the system at a given time. The information contained in an instance session key relates to the username, password, IP address, and other proprietary information as deemed necessary by QRZ. No data or personal information is contained within the session key which is implemented as a digital signature of the actual information held on the server.

Setting up a Session

The QRZ data port runs on port 80 at http://online.qrz.com/bin/xml
To establish a session, the calling appliation sends the username and password through either an HTTP GET or POST operation. A typical login exchange goes like this:
http://online.qrz.com/bin/xml?username=xx1xxx;password=abcdef;agent=q5.0
The URL 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 agent= parameter is currently optional however is is recommended so that we can stay abreast of which programs are using QRZ and under some circumstances, tailor the output based on the client. Certain promotional programs and developer incentives may also be tied to this parameter. Developers are urged to register their client programs with QRZ by sending an email to aa7bq@qrz.com.
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 Aug 16 03:51:47 2006</GMTime> 
    <Expires>2007-02-21</Expires> 
  </Session>
</QRZDatabase>
Session Return Values
All return data is bracketed by opening and closing tags, except for the <?xml version"1.0" ?> which is a header element. The elements in the session response are:

<Key> Your session key, for use in subsequent calls. All subsequent calls to the server should contain this value in the "s=" parameter.

<GMTime> The current server time, expressed in GMT (UTC)

<Expires> The expiration date of the users subscription account. This information may be provided to the user as a reminder of when his/her subscription expires.

<Alert> A priority message to the user. If present, this message MUST be presented to the user. Alert messages (if present) are only sent during the login sequence.

<Error> An error message, if present. This message may be shown to the user, or may be interpreted by the client program.

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> 
      <latd>34.23456</latd> 
      <lond>-112.34356</lond> 
      <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 object containing the session key and GMT time is returned in all successful responses.
Note that blank fields for a given database record are not transmitted. If, for example, there is no email address on file for the callsign then the <email> field will not appear. Your program must not rely upon the ordering of element fields as they are subject to change without notice.

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 in the format size/yyyy-mm-dd. To fetch a bio, issue a separate request using the URL paramater bio=[callsign] instead of callsign=[callsign].
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.

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

Extensions to this Specification

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.

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, 2003 - original draft
1.1 Mon Feb 28, 2005 - update to reflect correct image path
1.2 Wed Mar 2, 2005 - update - image tag now contains URL
1.3 Thu Jun 22, 2006 - update - reworded and added Alert tag and extensions policy
1.4 Thu Jun 23, 2006 - update - documented the "agent=" parameter