QRZCQ XML API Documentation

XML API: URL AND PROTOCOLS
This XML API serves for the purpose of looking up call data for logbook programs and is reachable at the following URLs:

https://ssl.qrzcq.com/xml (with SSL)
http://qrzcq.com/xml (without SSL)

This XML API is mostly compatible to the one at qrz.com, but there are some small changes and additions.

Login and token works the same way, GET parameter separator can be ';' or '&', all methods are GET only.

Tokens are valid for 3 days at this time, you should use it as long as possible. Invalid tokens will be also messaged the same way. Do not get a new token for every single query.

Check answers from server to be sure you got right data. For batch processing you can always asume the token to be valid for the running time.

All data should be properly encoded, if password contains one of the possible separators, then it should be properly url-encoded. If the password contains special chars, those should be additionally UTF-8 encoded.

XML API: FIELDS AND DATA TYPES

Field	Description
name	Text only.
qth	Text only
address	Text only (street and number)
city	Text only (city without zip)
zip	Text or number, varies with country.
license	Text only, some entries have proper char or number.
continent	Text, always 2 chars.
country	Country name, text only.
state	State, if applicable to country.
county	US county.
bmanager	Bureau manager, call only.
manager	Direct manager, call only.
locator	Maidenhead locator, 4 or 6 chars.
latitude	Decimal latitude, signed.
longitude	Decimal longitude, signed.
website	URL only.
dxcc	Integer, 0 < dxcc < 1000
itu	Integer, 0 < itu < 100
cq	Integer, 0 < cq < 100
iota	IOTA continent and number, format: EU-001.
plot	Polish OT number.
dok	German DOK name, mosty 3 chars, but special can be longer.
sondok	DOK is Sonder-DOK (German), 0 = no, 1 = yes.
eqsl	eQSL: 0 = no, 1 = yes.
lotw	LoTW: 0 = no, 1 = yes.
bqsl	Bureau QSL: 0 = no, 1 = yes.
mqsl	Mail (direct) QSL: 0 = no, 1 = yes.
utf8	Set to 1 if any of previous fields contain non-Ascii characters. All else 0.
qslpic	URL of the QSL or user picture if user have any.
prefix	Main country prefix, text only.

XML API: SESSION INPUT FIELDS
username - a valid QRZCQ user name (your main call)
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.

XML API: MISCELLANEOUS

# https://ssl.qrzcq.com/xml?username=DO5SSB&password=false&agent=Program

<?xml version="1.0" encoding="utf-8" ?>
<QRZCQDatabase version="1.00" xmlns="http://qrzcq.com"> 
	<Session> 
		<Error>Password Incorrect</Error> 
		<GMTime>Wed Feb 26 20:35:35 2014</GMTime> 
		<Remark>cpu: 0.004s</Remark> 
	</Session> 
</QRZCQDatabase>

or

<?xml version="1.0" encoding="utf-8" ?>
<QRZCQDatabase version="1.00" xmlns="http://qrzcq.com"> 
	<Session> 
		<Error>Premium Required</Error> 
		<GMTime>Wed Feb 26 20:35:58 2014</GMTime> 
		<Remark>cpu: 0.004s</Remark> 
	</Session> 
</QRZCQDatabase>

# https://ssl.qrzcq.com/xml?username=N0CALL&password=secret&agent=Program

<?xml version="1.0" encoding="utf-8" ?> 
<QRZCQDatabase version="1.00" xmlns="http://qrzcq.com"> 
	<Session> 
		<Key>xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</Key> 
		<Count>18231</Count> 
		<SubExp>Sat Mar 1 20:13:59 2014</SubExp> 
		<GMTime>Wed Feb 26 20:16:05 2014</GMTime> 
		<Remark>cpu: 0.005s</Remark> 
	</Session> 
</QRZCQDatabase>

# https://ssl.qrzcq.com/xml?s=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&callsign=DO5SSB&agent=Program

<?xml version="1.0" encoding="utf-8" ?>
<QRZCQDatabase version="1.00" xmlns="http://qrzcq.com">
	<Callsign>
		<call>DO5SSB</call>
		<dxcc>230</dxcc>
		<name>Grzegorz Surmann</name>
		<qth>Buchholz, near Hamburg</qth>
		<address>Amselweg 1 a</address>
		<city>Buchholz</city>
		<zip>21244</zip>
		<license>E</license>
		<continent>EU</continent>
		<country>Germany</country>
		<state>NDS</state>
		<locator>JO43WH</locator>
		<latitude>53.3199308</latitude>
		<longitude>9.8597973</longitude>
		<website>http://do5ssb.blogspot.de/</website>
		<itu>28</itu>
		<cq>14</cq>
		<eqsl>1</eqsl>
		<lotw>0</lotw>
		<bqsl>0</bqsl>
		<mqsl>1</mqsl>
		<utf8>0</utf8>
		<qslpic>http://qrzcq.com/qslpic/do5ssb.jpg</qslpic>
		<prefix>DL</prefix>
	</Callsign>
	<Session>
		<Key>xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</Key>
		<Count>18232</Count>
		<SubExp>Sat Mar 1 20:13:59 2014</SubExp>
		<GMTime>Wed Feb 26 20:22:21 2014</GMTime>
		<Remark>cpu: 0.006s</Remark>
	</Session>
</QRZCQDatabase>

# https://ssl.qrzcq.com/xml?s=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&callsign=N0CALL&agent=Program

<?xml version="1.0" encoding="utf-8" ?>
<QRZCQDatabase version="1.00" xmlns="http://qrzcq.com"> 
	<Session> 
		<Error>Not found: N0CALL</Error> 
		<GMTime>Wed Feb 26 20:30:53 2014</GMTime> 
		<Remark>cpu: 0.009s</Remark> 
	</Session> 
</QRZCQDatabase>

# https://ssl.qrzcq.com/xml?s=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&callsign=N0CALL&agent=Program

<?xml version="1.0" encoding="utf-8" ?>
<QRZCQDatabase version="1.00" xmlns="http://qrzcq.com"> 
<Session> 
		<Error>Session Timeout</Error> 
		<GMTime>Wed Feb 26 20:33:54 2014</GMTime> 
		<Remark>cpu: 0.596s</Remark> 
	</Session> 
</QRZCQDatabase>

XML API: CHANGELOG AND VERSIONS

Fri Nov 18 10:34:32 UTC 2011 - Ver. 1.00 - Initial version
Tue Jun 17 14:03:14 UTC 2014 - Ver. 1.01 - Field 'qslpic' added
Thu Nov 20 16:22:53 UTC 2014 - Ver. 1.02 - Field 'prefix' added
Tue Apr 04 23:21:37 UTC 2017 - Ver. 1.03 - Field 'sondok' added
Fri Apr  7 09:15:15 UTC 2017 - Ver. 1.04 - Agent parameter added