|Title:||QRZ XML Logbook Data Specification|
|Date:||June 8, 2009|
|Author:||Fred Lloyd, AA7BQ|
This document describes the interface specification for access to QRZ's XML data service. This interface provides network access to raw data from the QRZ.COM servers and databases.
Access to this interface requires user authentication through the use of a valid QRZ.COM username and password. Users may be both subscribers and non-subscribers, however, those not having a subscription will have limited capabilities.
For subscription rates and information see our subscription info page
Transactional access is provided by the XML server. Requests are sent as arguments to a URL and the results are returned as XML formatted data.
To begin a transaction or series of transactions, the client program must first authenticate the user and obtain a session key. The session key must be sent as a parameter along with all subsequent communications with the server.
A session key remains valid for a period of time which may be varied by the server. Most keys are good for at least a few hours, sometimes more. It is essential that session keys be reused by the client program until they expire. Initial login tends to be slow and should be avoided unless necessary.
A typical client program will perform a login transaction to obtain a fresh session key and will save that key for further use. The key may be stored on the local computer, or it may be held in memory. A required capability of any client program is the ability to redo the login sequence when necessary and to otherwise use an existing key.
A session key is valid for one user only and may become invalidated should the user's IP address change in midstream. The interface does not use HTTP cookies.
The QRZ XML data structure follows the standard proposed by WWW.W3C.ORG.
QRZ's top-level node is the
<QRZDatabase> element. All responses
from the QRZ server are prefaced with this element. Three child node types are
defined. These include:
Each of these child nodes is described in detail below, however, the following notice regarding our XML structure must be closely observed:
The XML data supplied by this interface may be extended at any time in a forward compatible manner. QRZ may add new XML nodes and/or attributes at any time. Therefore, it is critically important that software developers carefully parse the data received in a accordance with the XML 1.0 standard. User programs that use QRZ XML data must be prepared to ignore any unrecognized nodes or attributes, and must not depend on the order in which nodes or sub-nodes appear within the response.
The Session node contains information pertaining to the status of the user's session, error codes and informational messages relating to the request.
Setting up a Session
A simple login, which can be tested using any browser, is to pass the username and password as arguments to the server's URL. The QRZ XML interface is available from these equivalent URL's:
The first URL, i.e.
http://www.qrz.com/xml is the preferred address
while the remaining addresses are maintained for legacy applications. All are served
by the same server process. Note that if the
URL is used that the
xmlns value will reflect the alternate server name.
The alternate URLs are depricated and should not be used for new code development.
To perform a simple login, the client program sends the username and password using either an HTTP GET or POST operation. A typical login exchange looks like this:
The URI may use either the ampersand (&) or the semicolon (;) as the parameter separator.
Session Input Fields:
The only required parameters are username and password, however the use of the agent parameter is strongly recommend. The agent= parameter permits us to stay abreast of which programs our members are using, and potentially to notify the program suppliers. Developers are urged to register their client program agent names with QRZ by sending an email to email@example.com.
If the username and password are accepted, the system will respond with:
<?xml version="1.0" ?> <QRZDatabase version="1.15" xmlns="http://www.qrz.com"> <Session> <Key>2331uf894c4bd29f3923f3bacf02c532d7bd9</Key> <Count>123</Count> <SubExp>Wed Jan 1 12:34:03 2010</SubExp> <GMTime>Sun Aug 16 03:51:47 2009</GMTime> </Session> </QRZDatabase>
As with all server responses, the return begins with QRZDatabase. Note that the
QRZDatabase node also contains two attributes,
version attribute represents the QRZ XML version currently in use as
defined by the release number of this specification.
xmlns attribute identifies the XML namespace of this product.
The possible elements in a session node are:Session section fields
|Key||a valid user session key|
|Count||Number of lookups performed by this user in the current 24 hour period|
|SubExp||time and date that the users subscription will expire - or - "non-subscriber"|
|GMTime||Time stamp for this message|
|Message||An informational message for the user|
|Error||XML system error message|
Message responses should be presented to the end user.
Error responses include things such as "password incorrect", "session timeout",
and "callsign not found". Typical
Message messages return notices like: "A subscription
is required to obtain the complete data.".
A user session is established whenever a session key is returned. Any response from from the
server that does not contain the
Key element indicates that no valid session
exists and that a re-login is required to continue.
GMTime nodes are simply informational
and may be shown to the end user if determined to be useful.
To make a callsign query, simply pass the current session key in the
followed by a
A typical request might look like this:
http://www.qrz.com/xml?s=f894c4bd29f3923f3bacf02c532d7bd9;callsign=aa7bqThis returns the following data:
<?xml version="1.0" ?> <QRZDatabase version="1.15" xmlns="http://www.qrz.com"> <Callsign> <call>AA7BQ</call> <dxcc>291</dxcc> <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>United States</country> <ccode>291</ccode> <lat>34.23456</lat> <lon>-112.34356</lon> <grid>DM32af</lat> <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>firstname.lastname@example.org</email> <url>http://www.qrz.com/callsign/aa7bq</url> <u_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> <born>1953</born> </Callsign> <Session> <Key>2331uf894c4bd29f3923f3bacf02c532d7bd9</Key> <Count>123</Count> <SubExp>Wed Jan 1 12:34:03 2010</SubExp> <GMTime>Sun Nov 16 04:13:46 2009</GMTime> </Session> </QRZDatabase>
The possible callsign data fields are listed below. Not all fields may be returned with each request. The field ordering is arbitrary and subject to change.Callsign node fields
|dxcc||DXCC entity ID for the callsign|
|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|
|ccode||dxcc entity code for the 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|
|u_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 (0/1 or blank if unknown)|
|mqsl||Will return paper QSL (0/1 or blank if unknown)|
|cqzone||CQ Zone identifier|
|ituzone||ITU Zone identifier|
|locref||location reference code (lat/long source)|
|born||operator's year of birth|
|user||User who manages this callsign on QRZ|
|lotw||Will accept LOTW (0/1 or blank if unknown)|
|iota||IOTA Designator (blank if unknown)|
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
with a callsign.
Here is a typical biography fetch operation:
http://www.qrz.com/xml?s=2331uf894c4bd29f3923f3bacf02c532d7bd9;bio=g1srdAnd this is the result:
<?xml version="1.0" ?> <QRZDatabase version="1.15" xmlns="http://www.qrz.com"> <Bio> <call>g1srd</call> <size>258</size> <bio>http://www.qrz.com/hampages/d/r/g1srd/bio.html</bio> <modified>2008-10-10</modified> </Bio> <Session> <Key>3431u4eaf13b8336d61982c1fd1099c9a38ac</Key> <Count>123</Count> <GMTime>Sun Nov 16 04:43:21 2003</GMTime> </Session> </QRZDatabase>
|call||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 bio URL returned by this call is not guaranteed to be
always the same. The file referenced by the bio URL will be an HTML file.
Note that any
<img> tags in the returned HTML document
will contain relative path links and will necessarily need fixup in
order to display the images. Repaired image URL's will have the same directory
path prefix as the
bio.html file. In other words, the images
for a particular
bio.html file will be located in the same directory
as the HTML file itself.
Support for prefix matching and DXCC entity lookups is also provide by this
interface. Access to this method is via the
dxcc= url parameter.
The dxcc lookup provides three functions:
Functions are accessed using variations of the
dxcc= input paramter.
The allowed parameters are:
dxcc=123(a number) - return up the given DXCC entity.
dxcc=xx1xx(a callsign) - return the computed DXCC entity.
dxcc=all(keyword 'all') - return all the QRZ DXCC entities.
In the first form,
dxcc=123, the server returns the QRZ DXCC record
for the given entity. An entity lookup is inferred whenever the input argument
is all numeric. This entity is the corelates to the key given in both the
dxcc and the
ccode fields returned in callsign listings.
In the second form,
dxcc=xx1xx, the server reduces the callsign to a
4, then a 3, then a 2-letter prefix and returns the first DXCC entity that matches.
This can be useful to determine the country of a random callsign.
In the third form,
dxcc=all, the server returns its entire list
of 380+ DXCC records. Please use this option sparingly so as not to overburden
A typical dxcc fetch for entity 291 (USA):
<?xml version="1.0" ?> <QRZDatabase version="1.15" xmlns="http://www.qrz.com"> <DXCC> <dxcc>291</dxcc> <cc>US</cc> <ccc>USA</ccc> <name>United States</name> <continent>NA</continent> <ituzone>6</ituzone> <cqzone>3</cqzone> <timezone>-5</timezone> <lat>37.788081</lat> <lon>-97.470703</lon> </DXCC> <Session> <Key>d0cf9d7b3b937ed5f5de28ddf5a0122d</Key> <Count>12</Count> <SubExp>Wed Jan 13 13:59:00 2010</SubExp> <GMTime>Mon Oct 12 22:33:56 2009</GMTime> </Session> </QRZDatabase>DXCC node fields
|dxcc||DXCC entity number for this record|
|cc||2-letter country code (ISO-3166)|
|cc||3-letter country code (ISO-3166)|
|continent||2-letter continent designator|
|timezone||UTC timezone offset +/-|
|notes||Special notes and/or exceptions|
0545mean "5 hours, 45 minutes". The plus (+) sign is implied.
No DXCC information for: xxxxon non-match failures.
Here's an example of a typical "callsign not found" error:
<?xml version="1.0" ?> <QRZDatabase version="1.15" xmlns="http://www.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 version="1.15" xmlns="http://www.qrz.com"> <Session> <Error>Session Timeout</Error> <GMTime>Sun Nov 16 05:11:58 2003</GMTime> </Session> </QRZDatabase>
Connection refused is significant
in that it indicates that service is refused for the given user. No further explanation
is given, however, it does indicate that successful login will not be possible for at
least 24 hours.
|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||image tag now contains URL|
|1.3 Thu Jun 22, 2006||reworded and added Alert tag and extensions policy|
|1.4 Thu Jun 23, 2006||documented the "agent=" parameter|
|1.5 Wed Dec 3, 2008||some new data fields, field description section|
|1.6 Wed Jan 15, 2009||rename site from online.qrz.com to xml.qrz.com|
|1.7 Wed Jan 15, 2009||new bio fetch procedure|
|1.8 Fri Apr 10, 2009||field list (grid), session key description, Expires removed|
|1.9 Thu Sep 10, 2009||numerous incl. QRZDatabase version attribute|
|1.10 Sat Sep 12, 2009||some typographical corrections|
|1.11 Sun Sep 13, 2009||add emphasis to the Extensions paragraph|
|1.12 Thu Sep 17, 2009||rewrite - new Message node, new explanations.|
|1.13 Sat Oct 3, 2009||revised support for eqsl,mqsl,lotw and iota fields|
|1.14 Fri Oct 9, 2009||update for dxcc entity field|
|1.15 Mon Oct 12, 2009||added new dxcc / prefix search, added ccode field|
|1.15 Tue Jun 8, 2010||corrected documentation to reflect returned xmlns behavior|
Copyright © 2009 by QRZ.COM