The QRZ XML Interface Specification

Title:QRZ XML Logbook Data Specification
Version:1.19
Date: November 9, 2011
Author:Fred Lloyd, AA7BQ
Email:flloyd@qrz.com

Overview

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

Access Methodology

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.

QRZ XML Data Structure

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

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 http://xml.qrz.com/xml 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:

    http://www.qrz.com/xml?username=xx1xxx;password=abcdef;agent=q5.0

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 flloyd@qrz.com.

Note: if the agent parameter is not used, the QRZ will use the HTTP_USER_AGENT string that is passed in the HTTP request.

If the username and password are accepted, the system will respond with:

<?xml version="1.0" ?> 
<QRZDatabase version="1.18" 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 and xmlns. The version attribute represents the QRZ XML version currently in use as defined by the release number of this specification. The xmlns attribute identifies the XML namespace of this product.

The possible elements in a session node are:

Session section fields
FieldDescription
Keya valid user session key
CountNumber of lookups performed by this user in the current 24 hour period
SubExptime and date that the users subscription will expire - or - "non-subscriber"
GMTimeTime stamp for this message
MessageAn informational message for the user
ErrorXML system error message

Both Error and Message responses should be presented to the end user. Typical 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.

The Count, SubExp, and GMTime nodes are simply informational and may be shown to the end user if determined to be useful.

Callsign Lookups

To make a callsign query, simply pass the current session key in the s= parameter, followed by a callsign= parameter.

A typical request might look like this:

http://www.qrz.com/xml?s=f894c4bd29f3923f3bacf02c532d7bd9;callsign=aa7bq
This returns the following data:
<?xml version="1.0" ?> 
<QRZDatabase version="1.18" 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</grid> 
      <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> 
      <u_views>115336</views> 
      <bio>3937/2003-11-04</bio> 
      <image>http://files.qrz.com/q/aa7bq/aa7bq.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
FieldDescription
callcallsign
dxccDXCC entity ID for the callsign
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
ccodedxcc entity code for the mailing 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
u_viewsQRZ web page views
biobiography location info
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 (0/1 or blank if unknown)
mqslWill return paper QSL (0/1 or blank if unknown)
cqzoneCQ Zone identifier
ituzoneITU Zone identifier
locreflocation reference code (lat/long source)
bornoperator's year of birth
userUser who manages this callsign on QRZ
lotwWill accept LOTW (0/1 or blank if unknown)
iotaIOTA Designator (blank if unknown)

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 bio= parameter with a callsign.

Here is a typical biography fetch operation:

http://www.qrz.com/xml?s=2331uf894c4bd29f3923f3bacf02c532d7bd9;bio=g1srd
And this is the result:
<?xml version="1.0" ?> 
<QRZDatabase version="1.18" xmlns="http://www.qrz.com">
    <Bio>
	<call>g1srd</call> 
	<size>258</size> 
	<bio>http://www.qrz.com/db/g1srd</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>

Bio node fields
FieldDescription
callcallsign for this bio
sizelength in bytes of the bio text
biofully qualified URL to the user's biography page
modifieddate of last bio text modification

Note: in contrast to previous versions of this specification, the bio command no longer returns a path to a biography file. Instead, it returns the location of the user's full biography page on QRZ.


DXCC / Prefix Lookups

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:

  1. Look up a DXCC entity by its code,
  2. Determine the matching DXCC entity for a given callsign
  3. Return the entire list of QRZ DXCC entities.

Functions are accessed using variations of the dxcc= input paramter. The allowed parameters are:

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

A typical dxcc fetch for entity 291 (USA):

http://www.qrz.com/xml?s=d0cf9d7b3b937ed5f5de28ddf5a0122d;dxcc=291
Resulting in:
<?xml version="1.0" ?> 
<QRZDatabase version="1.18" 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
FieldDescription
dxccDXCC entity number for this record
cc2-letter country code (ISO-3166)
cc3-letter country code (ISO-3166)
namelong name
continent2-letter continent designator
ituzoneITU Zone
cqzoneCQ Zone
timezoneUTC timezone offset +/-
latLatitude (approx.)
lonLongitude (approx.)
notesSpecial notes and/or exceptions

Notes:

Error Conditions
There are two general types of errors. Data errors, which are typically of the genere "item not found", and Session errors which deal with the user's session key. If the <Session> node contains an <Error> sub-node, then the message should be examined and/or presented to the user.

Here's an example of a typical "callsign not found" error:

<?xml version="1.0" ?> 
<QRZDatabase version="1.18" 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.18" xmlns="http://www.qrz.com">
    <Session>
	<Error>Session Timeout</Error> 
	<GMTime>Sun Nov 16 05:11:58 2003</GMTime> 
    </Session>
</QRZDatabase>

A special Error message, 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.

Further Information
For questions concerning this document or the XML interface, please contact the author at flloyd@qrz.com .
Revision History:
1.0 Sat Nov 15, 2003original draft
1.1 Mon Feb 28, 2005update to reflect correct image path
1.2 Wed Mar 2, 2005image tag now contains URL
1.3 Thu Jun 22, 2006reworded and added Alert tag and extensions policy
1.4 Thu Jun 23, 2006documented the "agent=" parameter
1.5 Wed Dec 3, 2008some new data fields, field description section
1.6 Wed Jan 15, 2009rename site from online.qrz.com to xml.qrz.com
1.7 Wed Jan 15, 2009new bio fetch procedure
1.8 Fri Apr 10, 2009field list (grid), session key description, Expires removed
1.9 Thu Sep 10, 2009numerous incl. QRZDatabase version attribute
1.10 Sat Sep 12, 2009some typographical corrections
1.11 Sun Sep 13, 2009add emphasis to the Extensions paragraph
1.12 Thu Sep 17, 2009rewrite - new Message node, new explanations.
1.13 Sat Oct 3, 2009revised support for eqsl,mqsl,lotw and iota fields
1.14 Fri Oct 9, 2009update for dxcc entity field
1.15 Mon Oct 12, 2009added new dxcc / prefix search, added ccode field
1.16 Tue Jun 8, 2010corrected documentation to reflect returned xmlns behavior
1.17 Tue Jan 26, 2011corrected documentation to reflect new bio/image results
1.18 Thu Mar 24, 2011corrected documentation to reflect new bio/image results
1.19 Wed Nov 9, 2011documentation update for the 'agent' parameter

Copyright © 2011 by QRZ.COM