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:

• <Session>
• <Callsign>
• <Bio>

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:

• http://www.qrz.com/xml
• http://xml.qrz.com/xml
• http://xml.qrz.com/bin/xml

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:

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

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

Field	Description
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

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.

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

Field	Description
call	callsign
dxcc	DXCC entity ID for the callsign
fname	first name
name	last name
addr1	address line 1 (i.e. house # and street)
addr2	address line 2 (i.e, city name)
state	state (USA Only)
zip	Zip/postal code
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
grid	grid locator
county	county name (USA)
fips	FIPS county identifier (USA)
land	country of callsign issue
efdate	license effective date (USA)
expdate	license expiration date (USA)
p_call	previous callsign
class	license class
codes	license type codes (USA)
qslmgr	QSL manager info
email	email address
url	web page address
u_views	QRZ web page views
bio	biography location info
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 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

Field	Description
call	callsign for this bio
size	length in bytes of the bio text
bio	fully qualified URL to the user's biography page
modified	date 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.

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:

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

Field	Description
dxcc	DXCC entity number for this record
cc	2-letter country code (ISO-3166)
cc	3-letter country code (ISO-3166)
name	long name
continent	2-letter continent designator
ituzone	ITU Zone
cqzone	CQ Zone
timezone	UTC timezone offset +/-
lat	Latitude (approx.)
lon	Longitude (approx.)
notes	Special notes and/or exceptions

Notes:

• QRZ's DXCC list includes some entities that are unique to QRZ. Such entities have identifiers that are greater than 900.


• Timezone values are notated in hours, +/- UTC. Odd timezones, such as 0545 mean "5 hours, 45 minutes". The plus (+) sign is implied.


• Lat and lon values are usually located at the approximate geographic center of the entity.


• Lookups other than 'all' return No DXCC information for: xxxx on non-match failures.

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.

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	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.16 Tue Jun 8, 2010	corrected documentation to reflect returned xmlns behavior
1.17 Tue Jan 26, 2011	corrected documentation to reflect new bio/image results
1.18 Thu Mar 24, 2011	corrected documentation to reflect new bio/image results