• Bug Fix Release - due to changes in the QRZ master server, the bio html and image information was replaced with a new source. No changes to the interface resulted.

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.

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.

The QRZ XML service is located at http://www.qrz.com/xml/. If greater security is desired to protect login credentials, HTTPS may be used as https://www.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.

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://www.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

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://www.qrz.com/xml/?username=xx1xxx;password=abcdef
2. http://www.qrz.com/xml/1.31/?username=xx1xxx;password=abcdef
3. http://www.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.

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:

• <Session>
• <Callsign>
• <DXCC>

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 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://www.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:

• 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 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.31" xmlns="http://www.qrz.com">
  <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:

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.

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/current/?s=f894c4bd29f3923f3bacf02c532d7bd9;callsign=aa7bq

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

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:

• user - the value was input by the user
• geocode - the value was derived from USA Geocoding data
• grid - the value was derived from a user supplied grid square
• zip - the value was derived from the callsign's USA Zip Code
• state - the value was derived from the callsign's USA State
• dxcc - the value was derived from the callsign's DXCC entity (country)
• none - no value could be determined

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://www.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.

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:

• 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 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/current/?s=d0cf9d7b3b937ed5f5de28ddf5a0122d;dxcc=291

<?xml version="1.0" ?> 
<QRZDatabase version="1.31" 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 2013</SubExp>
<GMTime>Mon Oct 12 22:33:56 2012</GMTime>
</Session>
</QRZDatabase>

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.

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

<?xml version="1.0" ?> 
<QRZDatabase version="1.31" 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>

Here's an example of a "Session" error:

<?xml version="1.0" ?> 
<QRZDatabase version="1.31" 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.