Specifications for XML access to the QRZ Database

Title:QRZ Online XML Callsign Database Specifications
Date: April 10, 2009
Author:Fred Lloyd, AA7BQ


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


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.


The QRZ XML server 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 recreated each time a user logs in. A session key is valid for only one user at a time, logging in from a single IP address.

Session keys are tempoary in nature and may be valid up to 24 hours. Whenever a user logs in, any previously issued session keys are invalidated. A session key may also be invalidated at any time by the server, so client applications should be prepared to re-login at any time.

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:

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">
    <GMTime>Sun Aug 16 03:51:47 2006</GMTime> 
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)

  • <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:
This request would return the following data:
<?xml version="1.0" ?> 
<QRZDatabase xmlns="http://xml.qrz.com">
      <fname>FRED L</fname> 
      <addr1>8711 E PINNACLE PEAK RD 159</addr1> 
      <moddate>2003-11-04 19:37:02</moddate> 
      <GMTime>Sun Nov 16 04:13:46 2003</GMTime> 
      <Alert>optional message</Alert> 
      <Error>optional message</Error> 

Callsign section fields
fnamefirst name
namelast name
addr1address line 1 (i.e. house # and street)
addr2address line 2 (i.e, city name)
statestate (USA Only)
zipZip/postal code
countrymailing address country
latlattitude of address (signed decimal) S < 0 > N
lonlongitude of address (signed decimal) W < 0 > E
gridgrid locator
countycounty name (USA)
fipsFIPS county identifier (USA)
landcountry of callsign issue
efdatelicense effective date (USA)
expdatelicense expiration date (USA)
p_callprevious callsign
classlicense class
codeslicense type codes (USA)
qslmgrQSL manager info
emailemail address
urlweb page address
viewsQRZ web page views
biobiography tag info (length/date)
imageprimary image url
serialQRZ db serial number
moddateQRZ db last modified date
MSAMetro Service Area (USPS)
AreaCodeTelephone Area Code (USA)
TimeZoneTime Zone (USA)
GMTOffsetGMT Time Offset
DSTDaylight Saving Time Observed
eqslWill accept e-qsl
mqslWill return paper QSL
cqzoneCQ Zone identifier
ituzoneITU Zone identifier
locreflocation reference code (lat/long source)

Session section fields
Keyunique user session key
Expirestime and date that the session key will expire
GMTimeTime of last message
Alertmessage the must be shown to the end user
ErrorXML system error message

Bio section fields
callsigncallsign for this bio
sizelength in bytes of the bio text
biofully qualified URL to the HTML biography file
modifieddate 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:

And this is the result:
<?xml version="1.0" ?> 
<QRZDatabase xmlns="http://xml.qrz.com">
	<GMTime>Sun Nov 16 04:43:21 2003</GMTime> 

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">
	<Error>Not found: g1srdd</Error> 
	<GMTime>Sun Nov 16 05:07:14 2003</GMTime> 
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">
	<Error>Session Timeout</Error> 
	<GMTime>Sun Nov 16 05:11:58 2003</GMTime> 
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
  • 1.8 Fri Apr 10, 2009 - update - field list (grid), session key description, Expires removed

    Copyright © 2008 by QRZ.COM