Specifications for XML access to the QRZ Database
|Title:||QRZ Online XML Callsign Database Specifications|
Feburary 6, 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
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
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:
The URL may use either the ampersand (&) or the semicolon (;) as
the parameter separator.
Session Input Fields:
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
- 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
If the username and password are correct, the system will respond with:
<?xml version="1.0" ?>
<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="
- <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
- <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.
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" ?>
<addr1>8711 E PINNACLE PEAK RD 159</addr1>
<GMTime>Sun Nov 16 04:13:46 2003</GMTime>
Callsign section fields
|addr1||address line 1 (i.e. house # and street)|
|addr2||address line 2 (i.e, city name)|
|state||state (USA Only)|
|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)|
|codes||license type codes (USA)|
|qslmgr||QSL manager info|
|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
|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
|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.
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" ?>
<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.
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" ?>
<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" ?>
<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.
For questions concerning this document or the XML interface, please
contact the author at the email address listed above.
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
Copyright © 2008 by QRZ.COM