Specifications for XML access to the QRZ Database

Title:	QRZ Online XML Callsign Database Specifications
Version:	1.7
Date:	Feburary 6, 2009
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.
Need a subscription? Click Here for subscription info.

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://xml.qrz.com/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://xml.qrz.com/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://xml.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://xml.qrz.com/xml?s=2331uf894c4bd29f3923f3bacf02c532d7bd9;callsign=aa7bq
This request would return the following data:
<?xml version="1.0" ?> 
<QRZDatabase xmlns="http://xml.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> 
      <grid>DM32af</lat> 
      <lon>-112.34356</lon> 
      <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> 
      <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> 
  </Callsign>
  <Session>
      <Key>2331uf894c4bd29f3923f3bacf02c532d7bd9</Key> 
      <GMTime>Sun Nov 16 04:13:46 2003</GMTime> 
      <Alert>optional message</Alert> 
      <Error>optional message</Error> 
  </Session>
</QRZDatabase>
Callsign section 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

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

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)

Session section fields

Field Description

Key unique user session key

Expires time and date that the session key will expire

GMTime Time of last message

Alert message the must be shown to the end user

Error XML system error message

Bio section fields

Field Description

callsign 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 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. Programs must not rely upon the ordering of the element fields as described above. Returned fields may arrive in any order.

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 paramater bio=[callsign] instead of callsign=[callsign].
Here is a typical biography fetch operation:
http://xml.qrz.com/xml?s=2331uf894c4bd29f3923f3bacf02c532d7bd9;bio=g1srd
And this is the result:
<?xml version="1.0" ?> 
<QRZDatabase xmlns="http://xml.qrz.com">
    <Bio>
	<call>g1srd</call> 
	<size>258</size> 
	<bio>http://xml.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>
Note that the bio URL returned by this call is not guaranteed to be always the same. Always use the value that is returned from this call and then fetch the bio data in a separate request.

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.
Image files may be in any of several formats, including JPG, PNG and GIF.

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://xml.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://xml.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
1.5 Wed Dec 3, 2008 - update - some new data fields, field description section
1.6 Wed Jan 15, 2009 - update - rename site from online.qrz.com to xml.qrz.com
1.7 Wed Jan 15, 2009 - update - new bio fetch procedure