The QRZ XML Logbook Data Specification

Title:QRZ XML Logbook Data Specification
Version:1.9
Date: September 10, 2009
Author:Fred Lloyd, AA7BQ
Email:flloyd@qrz.com

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

The QRZ XML interface provides program level access to the QRZ callsign database.

Access to the QRZ XML port requires a valid subscriber login consisting of a username and password, and a current, active subscription with QRZ. For subscription information see: Our subscription info page

Sessions

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 generated each time a user logs in. A session key is valid for one user, operating from a single IP address.

Session keys may be valid for up to 24 hours. A session key may 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 XML service can be accessed from these equivalent locations:

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:

    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 agent parameter is optional however it is recommended so that we can stay abreast of what programs our members are using. In addition, if we might use this info to contact developers regarding upcoming or proposed changes. Developers are urged to register their client program agent names with QRZ by sending an email to flloyd@qrz.com.

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

<?xml version="1.0" ?> 
<QRZDatabase version="1.1" xmlns="http://xml.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>

The QRZDatabase Tag

The QRZDatabase tag starts and ends the return response. The QRZDatabase tag contains two attributes, version and xmlns. The version attribute represents the QRZ release version for this version of its XML data. The xmlns attribute identifies the XML namespace of this product.

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:

Fetching Data
To make a callsign query, a "callsign=" and an "s=" parameter is needed. These parameters are passed in the URL as follows:
http://xml.qrz.com/xml?s=2331uf894c4bd29f3923f3bacf02c532d7bd9;callsign=aa7bq
This request returns the following data:
<?xml version="1.0" ?> 
<QRZDatabase version="1.1" xmlns="http://xml.qrz.com">
  <Callsign>
      <call>AA7BQ</call> 
      <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>USA</country> 
      <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>flloyd@qrz.com</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> 
      <GMTime>Sun Nov 16 04:13:46 2003</GMTime> 
      <Alert>optional message</Alert> 
      <Error>optional message</Error> 
  </Session>
</QRZDatabase>
Callsign data fields
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.
FieldDescription
callcallsign
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
u_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)
bornoperator's year of birth
userUser who manages this callsign on QRZ
lotwWill accept LOTW
iotaIOTA Designator

Session section fields
FieldDescription
Keyunique user session key
CountNumber of lookups performed in current 24 hour period
SubExptime and date that the users subscription will expire
GMTimeTime stamp for this message
ErrorXML system error message

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

http://xml.qrz.com/xml?s=2331uf894c4bd29f3923f3bacf02c532d7bd9;bio=g1srd
And this is the result:
<?xml version="1.0" ?> 
<QRZDatabase version="1.1" xmlns="http://xml.qrz.com">
    <Bio>
	<call>g1srd</call> 
	<size>258</size> 
	<bio>http://xml.qrz.com/hampages/d/r/g1srd/bio.html</bio> 
	<modified>2008-10-10</modified> 
    </Bio>
    <Session>
	<Key>3431u4eaf13b8336d61982c1fd1099c9a38ac</Key> 
	<GMTime>Sun Nov 16 04:43:21 2003</GMTime> 
    </Session>
</QRZDatabase>

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. Also, embedded <img> tags in the bio.html file may contain relative path references that might need fixup before displaying in a browser.

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 version="1.1" xmlns="http://xml.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.1" xmlns="http://xml.qrz.com">
    <Session>
	<Error>Session Timeout</Error> 
	<GMTime>Sun Nov 16 05:11:58 2003</GMTime> 
    </Session>
</QRZDatabase>
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 flloyd@qrz.com .
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
  • 1.9 Thu Sep 10, 2009 - update - numerous incl. QRZDatabase version attribute

  • Copyright © 2009 by QRZ.COM