The QRZ XML Interface Specification

Title:QRZ XML Logbook Data Specification
Version:1.33
Date: September 18, 2014
Author:Fred Lloyd, AA7BQ
Email:flloyd@qrz.com
What's New in Version 1.33
Overview

This document describes the interface specification for access to QRZ's XML subscription data service. This service provides real-time access to information from the QRZ.COM servers and databases.

Access to this service requires user authentication through the use of a valid QRZ.COM username and password. While any QRZ user may login to the service, an active QRZ Logbook Data subscription is required to access most of its features. Non-subscriber access limits the data fields that are returned and is primarily intended for testing and troubleshooting purposes only.

A description of subscription plans and rates is available on the QRZ website.

Access Methodology

QRZ's XML service is implemented using standard HTTP protocols. Requests are made as query string arguments to a standard HTTP URL. Results are returned over HTTP as XML formatted data.

All post-login interactions with the server require that a dynamic session key be included with each request. The session key is sent by specifying the s= parameter. Note that requests to the XML service port may utilize either HTTP GET or HTTP POST methods.

Session keys are dynamically managed by the server and have no guaranteed lifetime. When a session key expires or becomes invalidated, a new key may be issued upon request. Client programs should cache all session keys provided by the server and reuse them until they expire. This practice maximizes client performance and serves to minimize the load on QRZ's servers.

As a general programming pattern, clients should expect to perform only one login operation per session. The session key returned from a successful login should then be locally cached and reused as many times as possible. All clients should monitor the status response returned in each transaction and be prepared to login again whenever indicated.

A session key is valid only for a single user and may become immediately invalidated if it is detected that the user's IP address or other identifying information changes after login has been completed. The interface does not use HTTP cookies, Javascript, or HTML.

QRZ's XML Service Address

The QRZ XML service is located at http://xmldata.qrz.com/xml/. If greater security is desired to protect login credentials, HTTPS may be used as https://xmldata.qrz.com/xml/ with an HTTP POST method. The session key that is returned from an HTTPS login is valid on both the HTTP and HTTPS interfaces. We request that you limit your HTTPS interactions to login (session establishment) operations and not use HTTPS for routine callsign lookups. Session keys are cryptographically secure and non-transferrable and thus do not need to be protected or wrapped with additional encryption protocols.

Versioned URL Interface

Beginning with version 1.25, access to QRZ's XML service is versioned. Versioning provides the ability for QRZ to periodically extend or make significant changes to this specification without sacrificing client compatibility with earlier releases.

This version introduces an extension to the service URL that indicates which version of the interface should be used to service the request. The general format of the service URL is:

http://xmldata.qrz.com/xml/version_identifier/?<query parameters>

The version_identifier indicates which version of the interface will be used. Valid examples are:

Version Identifier Values
Identifieruse
(none)Missing identifier: use version 1.24 (legacy)
1.xxUse version 1.xx
currentUse the latest available version.

Note:
If no version identifier is present, the interface specification follows the legacy 1.24 specification to maintain compatibility with existing client programs.

Examples:

  1. http://xmldata.qrz.com/xml/?username=xx1xxx;password=abcdef
  2. http://xmldata.qrz.com/xml/1.31/?username=xx1xxx;password=abcdef
  3. http://xmldata.qrz.com/xml/current/?username=xx1xxx;password=abcdef

In the first example, no version identifier was specified and so the lowest version (1.24) will be used. In the second example, the version 1.31 interface will be used. In the third example, the most current version avaialable will be used. Note that the trailing slash (/) character following either the 'xml' or the 'version' identifier is highly recommended. Also, the dot (.) in the version identifier may be omitted, e.g. either '1.31' or '131' may be used.

If a version identifier is used, it must be either 'current' or a supported release number. The use of any other value will result in an error.

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 for this level. They are:

Each of these nodes is described below. An important design pattern must be observed in order for your client program to maintain its highest level of reliability:

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 client programs carefully parse the data received in an "object=attribute" manner while ignoring any unknown nodes or attributes, and do so without raising an error condition. Your decoding strategy must make no assumptions regarding the number of nodes returned, the order in which nodes are returned, or the presence of nodes or attributes not previously defined.

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
To perform a simple login and obtain a session key, the client program sends the username and password using either an HTTP GET or POST operation. A typical login exchange looks like this:

    http://xmldata.qrz.com/xml/current/?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 required parameters are username and password. The use of the agent parameter is strongly recommended as it assists in troubleshooting and end user support. You may use any agent identifier you wish, however, it will be most useful if you maintain a unique prefix for your product (for example, Ham Radio Deluxe uses 'HRDv.x'). Please keep it short and simple.

Note: if the agent parameter is not used, the XML server will attempt to use the HTTP_USER_AGENT string obtained from the HTTP protocol.

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

<?xml version="1.0" ?> 
<QRZDatabase version="1.33">
  <Session>
    <Key>2331uf894c4bd29f3923f3bacf02c532d7bd9</Key> 
    <Count>123</Count> 
    <SubExp>Wed Jan 1 12:34:03 2013</SubExp> 
    <GMTime>Sun Aug 16 03:51:47 2012</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 responses 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 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 deemed 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://xmldata.qrz.com/xml/current/?s=f894c4bd29f3923f3bacf02c532d7bd9;callsign=aa7bq
This returns the following data:
<?xml version="1.0" ?> 
<QRZDatabase version="1.33">
  <Callsign>
      <call>AA7BQ</call> 
      <aliases>N6UFT,KJ6RK,DL/AA7BQ</aliases> 
      <dxcc>291</dxcc> 
      <fname>FRED L</fname> 
      <name>LLOYD</name> 
      <addr1>8711 E PINNACLE PEAK RD 193</addr1> 
      <addr2>SCOTTSDALE</addr2> 
      <state>AZ</state> 
      <zip>85255</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</u_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> 
      <geoloc>user</geoloc> 
      <born>1953</born> 
  </Callsign>
  <Session>
      <Key>2331uf894c4bd29f3923f3bacf02c532d7bd9</Key> 
      <Count>123</Count> 
      <SubExp>Wed Jan 1 12:34:03 2013</SubExp> 
      <GMTime>Sun Nov 16 04:13:46 2012</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
xrefCross reference: the query callsign that returned this record
aliasesOther callsigns that resolve to this record
dxccDXCC entity ID (country code) 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
countrycountry name for the QSL mailing address
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)
landDXCC country name of the callsign
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
bioapproximate length of the bio HTML in bytes
biodatedate of the last bio update
imagefull URL of the callsign's primary image
imageinfoheight:width:size in bytes, of the image file
serialQRZ db serial number
moddateQRZ callsign 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
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)
geolocDescribes source of lat/long data

About Lat/Long and Grid Data

The lat/long and grid data returned varies by the method by which it was obtained by QRZ. Whenever a lat/long coordinate pair exists for the queried callsign, its value is used to calculate the appropriate Maidenhead locator (grid) value. In some rare cases, a given QRZ record may be missing its lat/long value but has a user supplied grid locator. When this is the case, the station's lat/long values are stated as the center the given grid locator.

In most cases, when neither a lat/long pair or grid is known for a USA record, it will be derived from its postal address. For USA callsigns, the lat/long pair is determined using a geocoding procedure derived from the US Census Tiger/Line dataset. Not all addresses can be successfully geocoded and subsequently a Zip Code database is used to return an approximate location that roughly centers on the zip code. Failing all of the above, for USA callsigns, the geographic coordinates of the state's approximate center are used.

For non-USA callsigns, no geocoding is available so unless the user has specifically input lat/long or grid coordinates, the approximate center of the DXCC entity (country) is used.

The net result is that nearly every callsign returned by QRZ will include geographic coordinates. While in some cases they may not be exact, they are generally close enough for DX antenna positioning operations.

The geoloc field describes the source of the returned lat/long data. The possible string values for geoloc are:

Biography Data

The <bio> field is present in the callsign record if and only if a biography record exists for the target callsign on the server. This field indicates the approximate size of the bio HTML data and the <biodate> field indicates the date of last bio update.

To fetch the bio HTML, issue a separate request using the html= query parameter for the same callsign.

Bio Fetch Example:

http://xmldata.qrz.com/xml/current/?s=d0cf9d7b3b937ed5f5de28ddf5a0122d;html=xx1xxx

The html=callsign method is unique in this interface in that it does not return XML, but rather regular HTML, including embedded CSS, just as the information would normally appear on the callsign's QRZ page.


DXCC / Prefix Lookups

Support for prefix matching and DXCC entity lookups is also provided 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 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://xmldata.qrz.com/xml/current/?s=d0cf9d7b3b937ed5f5de28ddf5a0122d;dxcc=291
Resulting in:
<?xml version="1.0" ?> 
<QRZDatabase version="1.33">
<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 2013</SubExp>
<GMTime>Mon Oct 12 22:33:56 2012</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 form "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.33">
    <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.33">
    <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
1.20 Wed Nov 14, 2011internal update, added CSS data to HTML request, no interface changes
1.25 Wed Jun 20, 2012Versioned interface, cross references, aliases, https documentation, new bio fetch procedure
1.26 Mon Jul 23, 2012Revised lat/long and grid calculations to match www.qrz.com
1.27 Wed Jul 25, 2012Replaced the 'locref' field with new 'geoloc' field to describe source of lat/long coordinates.
1.28 date not specifiedInternal update
1.29 date not specifiedInternal update
1.30 Tue Feb 11, 2014Bug Fix to restore biography data and image results.
1.31 Tue Feb 25, 2014Bug Fix to biography image URL's
1.32 Tue June 24, 2014Bug Fix to fetch latest biography version
1.33 Thu Sep 18, 2014Bug Fix to fetch latest biography primary image (picture) plus Doc Update

Copyright © 2003-2014 by QRZ.COM