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

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

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.

The QRZ XML service can be accessed from these equivalent locations:

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

    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:

• 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

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:

• <Key> Your current session key. All subsequent calls to the server should submit this value using the "s=" parameter.
• <Count> Lookup count. The total number of lookups peformed by this user in the current 24-hour period.
• <SubExp> The date that this user's XML subscription expires.
• <GMTime> The current server time, expressed in GMT (UTC)
• <Error> An error message, if present. This message may should 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:

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

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" ?> 
<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.

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

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