For application developers

A: 20 | K: 5 | SFI: 127 | SSN: 99 | GF: STORM

HamQTH provides a simple interface for application developers.
You can use:

XML callbook search, very fast, without any limitation (user has to be registered here)
XML DXCC search which can give you very accurate information (for free, no registration needed)
XML recent activity search give you a list of station activity from Reverse beacon network, dxcluster and HamQTH logbook
log upload function to upload whole log in ADIF format (plain text or compressed in zip,rar, 7zip etc.)
realtime QSO upload to upload individual QSO after user saves it into your program
DX cluster spots you can use DX cluster feed in your application
Self spotting inteface - self spots to dxcluster network are not allowed but sometimes is good to have an opportuninty to let others know you are CQing somewhere.

HamQTH has very powerful log search function with nice graphical statistics - look at my own profile
List of apps supporting HamQTH is on dedicated site.

XML callbook search

If you want to use HamQTH callbook query search in your logging program, you don't need to parse HTML code to get the data. You can use our XML service. However, the user who wants to use data from HamQTH, has to be registered here.

How XML search works?

At first, you have to ask for session ID:

http://www.hamqth.com/xml.php?u=username&p=password

where

u	username registered on HamQTH (station callsign)
p	user's password

If your username or password is correct, you'll get something like this:

    <?xml version="1.0"?>
    <HamQTH version="2.0" xmlns="http://www.hamqth.com">
    <session>
    <session_id>09b0ae90050be03c452ad235a1f2915ad684393c</session_id>
    </session>
    </HamQTH>

If your username or password is NOT correct, XML search returns:

    <?xml version="1.0"?>
    <HamQTH version="2.0" xmlns="http://www.hamqth.com">
    <session>
    <error>Wrong user name or password</error>
    </session> 
    </HamQTH>

Session ID is valid for one hour. After it expires, you need to request for new one.
If your session expired or the query is not valid, XML query will return:

    <?xml version="1.0"?>
    <HamQTH version="2.0" xmlns="http://www.hamqth.com">
    <session>
    <error>Session does not exist or expired</error>
    </session> 
    </HamQTH>

How do I search for callsign data?

Now we have our session ID and can try to search for callsign e.g. OK2CQR:

http://www.hamqth.com/xml.php?id=09b0ae90050be03c452ad235a1f2915ad684393c&callsign=ok2cqr&prg=YOUR_PROGRAM_NAME

where

id	session ID requested before
callsign	callsign you are looking for
YOUR_PROGRAM_NAME	Name of the application using XML search (without spaces)

If your session is valid and callsign exists you get this XML structure:

    <?xml version="1.0"?>
    <HamQTH version="2.0" xmlns="http://www.hamqth.com"> 
    <search> 
	<callsign>ok2cqr</callsign> 
	<nick>Petr</nick> 
	<qth>Neratovice</qth> 
	<country>Czech Republic</country>
     	<adif>503</adif>
	<itu>28</itu> 
	<cq>15</cq> 
	<grid>jo70gg</grid> 
	<adr_name>Petr Hlozek</adr_name> 
	<adr_street1>17. listopadu 1065</adr_street1> 
	<adr_city>Neratovice</adr_city> 
	<adr_zip>27711</adr_zip> 
	<adr_country>Czech Republic</adr_country> 
     	<adr_adif>503</adr_adif>
	<district>GZL</district>
	<lotw>Y</lotw> 
	<qsl>Y</qsl> 
	<eqsl>Y</eqsl> 
	<email>petr@ok2cqr.com</email> 
	<jabber>petr@ok2cqr.com</jabber> 
	<skype>PetrHH</skype> 
	<birth_year>1982</birth_year> 
	<lic_year>1998</lic_year> 
	<web>http://www.ok2cqr.com</web> 
	<latitude>50.07</latitude>
	<longitude>14.42</longitude>
	<continent>EU</continent>
        <utc_offset>-1</utc_offset>
	<picture>http://www.hamqth.com/userfiles/o/ok/ok2cqr/_profile/ok2cqr_nove.jpg</picture> 
    </search> 
    </HamQTH>

where

callsign	callsign you searched
nick	name used on the air
qth	callsign's QTH
country	country related to callsign, not to the address
adif	ADIF ID of country related to callsign
itu	ITU zone
CQ	CQ (WAZ) zone
grid	station locator
adr_name	address name
adr_street1	street address
adr_street2	street address
adr_street3	street address
adr_city	city address
adr_zip	zipcode
adr_country	country related to the address
adr_adif	ADIF ID of address country
district	station district
us_state	US state (USA stations only)
us_county	US county (USA stations only)
oblast	something like district (Russian stations)
dok	DOK (DL stations)
iota	IOTA reference number
qsl_via	QSL information
lotw	Y - uses LoTW, N - doesn't use LoTW, ? - we don't know
eqsl	Y - uses eQSL, N - doesn't use eQSL, ? - we don't know
qsl	Y - accept paper QSL cards, N - doesn't accept papaer QSL cards, ? - we don't know
email	email
jabber	jabber
icq	icq number
msn	MSN
skype	Skype
birth_year	Year of birth
lic_year	Licenced since
picture	link to user's picture
latitude	station position - latitude
longitude	station position - longitude
continent	continent
utc_offset	offset to UTC time in station location
facebook	link to Facebook profile
twitter	link to user's Twitter feed
gplus	link to GooglePlus profile
youtube	link to user's YouTube channel
linkedin	link to user's LinkedIn profile
flicker	link to user's flicker profile
vimeo	link to user's Vimeo channel

If callsign doesn't exist in HamQTH database, you get this:

    <?xml version="1.0"?>
    <HamQTH version="2.0" xmlns="http://www.hamqth.com">
    <session>
      <error>Callsign not found</error>
    </session>
    </HamQTH>

How do I get callsign bio?

If you have session ID, it's very easy. Just use this http request:

http://www.hamqth.com/xml_bio.php?id=09b0ae90050be03c452ad235a1f2915ad684393c&callsign=ok2cqr&strip_html=1

where:

id	session ID requested before
callsign	callsign's bio you are looking for
strip_html	1 - if you want to get plain text without HTML tags (default value), 0 - you want to get as is, also with HTML code

The result when station is at HamQTH:

    <?xml version="1.0"?>
    <HamQTH version="2.0" xmlns="http://www.hamqth.com"> 
    <search> 
      <callsign>ok2cqr</callsign> 
      <bio>my looong biography</bio> 
    </search> 
    </HamQTH>

where:

callsign	callsign you searched
bio	the bio information text

If callsign doesn't exist in HamQTH database, you get this:

    <?xml version="1.0"?>
    <HamQTH version="2.0" xmlns="http://www.hamqth.com">
      <session>
      <error>Callsign not found</error>
    </session>
    </HamQTH>

XML recent activity search

Recent activity of any callsign is collected from Reverse beacon network and dx cluster. It's very usefull utility especially for dx expedition and rare stations. This inteface also makes accessible list of QSO with searched station in the HamQTH logbook database and list of most recent QSO from station's log (if any exists).

How it works?

This search also needs xml session id. How to get it is described at XML callbook search. If you have it, you can try query like this:

http://www.hamqth.com/xml_recactivity.php?id=session_id&callsign=ok2cqr&rec_activity=1&log_activity=1&logook=1

where:

id	session ID requested before
callsign	callsign you are looking for
rec_activity	1 - include also data from RBN and dx clusters (default value), 0 do not add RBN and DX clusters data
log_activity	1 - include 20 qso QSO from HamQTH logbook (default value), 0 do not add logbook data
logbook	1 - include last 20 QSO from HamQTH station's logbook (default value), 0 do not add logbook data

If callsign doesn't exist in HamQTH database, you get this:

    <?xml version="1.0"?>
    <HamQTH version="2.0" xmlns="http://www.hamqth.com">
      <session>
      <error>Callsign not found</error>
    </session>
    </HamQTH>

and if it does, you'll get this XML:

    <?xml version="1.0"?>
    <HamQTH version="2.0" xmlns="http://www.hamqth.com">
    <search>
      <activity>
        <data>
          <source>DXC</source>
          <spotter>ZL2HAM</spotter>  
          <callsign>OK2CQR</callsign>          
          <note>calling CQ</note>
          <freq>21025.0</freq>
          <date>2011-09-10</date>
          <time>05:34:28</time>
        </data>    
        <data>
          <source>RBN</source>
          <spotter>IK3STG</spotter>
          <callsign>OK2CQR</callsign>
          <note>13 dB  34 WPM  CQ</note>
          <freq>14026.3</freq>
          <date>2011-09-07</date>
          <time>13:34:28</time>
        </data>    
      </activity>
      <log_activity>
        <data>
          <callsign>PT0S</callsign>
          <band>20M</band>
          <mode>CW</mode>
          <date>2012-11-13</date>
        </data>
        <data>
          <callsign>OK1RR</callsign>
          <band>40M</band>
          <mode>CW</mode>
          <date>2012-09-07</date>
        </data>
      </log_activity>
      <logbook>
        <data>
          <callsign>AA3B</callsign>
          <band>15M</band>
          <mode>CW</mode>
          <date>2012-11-11</date>
        </data>
        <data>
          <callsign>OK7WA</callsign>
          <band>80M</band>
          <mode>SSB</mode>
          <date>2012-05-07</date>
        </data>
      </logbook>
    </search>
    </HamQTH>

where:

activity	section with records from RBN and DX clusters network
source	source of the data - RBN or DXC
spotter	station that send the spot (DXC) or callsign of reverse beacon network station
callsign	spotted callsign
note	short note related to the spot
freq	frequency in kHz
date	spot sent date
time	spot sent time
log_activity	section with records HamQTH logbook - list of station that has callsign in their logs
callsign	station that has QSO in the log with station you are looking for
mode	mode of operating
band	band like in ADIF spec e.g. 160M, 40M etc.
date	QSO date
logbook	section with records in station's HamQTH logbook - list of 20 most recent QSOs in station's log
callsign	wkd callsign
mode	mode of operating
band	band like in ADIF spec e.g. 160M, 40M etc.
date	QSO date

If you find any problem or have an idea how to improve it, please let me know.

DXCC search

HamQTH also provides DXCC search based on Martin's (OK1RR) DXCC tables used in CQRLOG. The tables are excellent and probably the best ever. It provides excellent detail info e.g. callsign U3AP - http://hamqth.com/dxcc.php?callsign=U3AP you don't get only basic info that it is European Russia, but also Gorod Moskva (MA), World War II. Veteran.

How DXCC XML search works?

It is very easy. If you query HamQTH like this: http://hamqth.com/dxcc.php?callsign=U3AP where:

callsign

the callsign you are looking for DXCC info

You'll get this XML structure:

      <?xml version="1.0"?>
      <HamQTH version="2.0" xmlns="http://www.hamqth.com"> 
      <dxcc>
        <callsign>U3AP</callsign>
        <name>Russia (European)</name>
        <details>Russia (European), Gorod Moskva (MA), World War II. Veteran</details>
        <continent>EU</continent>
        <utc>-3</utc>
        <waz>16</waz>
        <itu>29</itu>
        <lat>55.75</lat>
        <lng>37.63</lng>
        <adif>54</adif>
      </dxcc>
      </HamQTH>

There is another way. If you set callsign parameter to adif number (http://hamqth.com/dxcc.php?callsign=503), you'll get something like this:

      <?xml version="1.0"?>
      <HamQTH version="2.0" xmlns="http://www.hamqth.com">     
      <dxcc>
        <name>Czech Republic</name>
        <continent>EU</continent>
        <utc>-1</utc>
        <waz>15</waz>
        <itu>28</itu>
        <lat>50.07</lat>
        <lng>14.42</lng>
        <adif>503</adif>
      </dxcc>
      </HamQTH>

You can use it for free, without any registration. Have a fun!

LOG upload

HamQTH also has very nice and powerful log search function. To make upload much easier, I've created simple page for uploading logs from mobile phone or your own application http://www.hamqth.com/prg_log_upload.php. Remember you always have to upload whole log. HamQTH doesn't support partial upload.

How log upload works?

It's very similar to log upload function in station profile but much easier to add to your application. To upload the log, you have to use POST method with these parameters:
u - username
p - password
c - callsign (if empty, username as callsign will be used)
f - file name of the uploading log
send_log - send OK as value (like user click on the OK button)
The file size is limited to 20MB but you can compress ADIF with zip, rar, 7zip, tar.gz or tar.bz2. File name in the archive has to have adi or adif extension otherwise won't be imported. If you'll upload plain ADIF file, adi/adif and txt extensions are allowed.

Like the upload from user's profile, log is not imported in run-time but on background. User will be informed via email about import progress. After you send POST request, there are four error messages you can get:

User parameter missing
Password parameter missing
Wrong username or password
You cannot upload log for this callsign

And after successful upload you'll get this:
Log uploaded successfully

I hope, they are self-explained. If there will be any problem with ADIF file itself, user will be informed via email.

Examples

I'm pure Linux user and use CQRLOG for my daily logging. It has auto backup function which always after I close the program exports all QSO into ADIF file and stores into defined directory (/home/ok2cqr/Ubuntu One/cqrlog_zaloha on my computer). If I want to upload last log backup to HamQTH, I use this script:

#!/bin/bash
BACKUPDIR="/home/ok2cqr/Ubuntu One/cqrlog_zaloha/"
USERNAME=ok2cqr
PASSWORD=my_password

cd "$BACKUPDIR"
curl -F f=@`ls | tail -n 1` -F send_log=OK -F u=$USERNAME -F p=$PASSWORD http://hamqth.com/prg_log_upload.php

That's all! I have an icon on the panel and when I click on it, it makes backup of my log to HamQTH. Very easy and powerfull. You can also create program to use Windows command line. I'm not so keen in windows scripting but if you are, please send me your script and I'll put it here.

Real-time QSO upload

You can upload individual QSO to HamQTH logbook in real-time as well. Use POST request to http://www.hamqth.com/qso_realtime.php with these parameters:
u - username
p - password
c - callsign (if empty, username as callsign will be used)
adif - the QSO in ADIF format
prg - name of your application (without version number)
cmd - command to real time upload function (insert, update, delete)

The result will be send as HTTP status code with message in the body. The HTTP status codes are:

403 Forbidden: Access denied. Your username and/or password was incorrect. The QSO will NOT be logged.
500 Internal error: This may occurs if the server has any problem in general or there is a problem with your ADIF file. In the body should be more information what happened. The QSO will NOT be logged.
400 QSO Rejected: QSO was rejected for some reason e.g. wrong band, already exists in database etc. The QSO will NOT be logged.
200 QSO OK: QSO was successfully saved into database.

HamQTH supports these ADIF fields:
QSO_DATE, TIME_ON, TIME_OFF, CALL, FREQ, MODE, RST_S, RST_R, NAME, QTH, QSL_SENT, QSLSDATE, QSL_RCVD, QSLRDATE, QSL_VIA, IOTA, TX_PWR, ITUZ, CQZ, CONT, GRIDSQUARE, MY_GRIDSQUARE, STATE, CNTY, COMMENT, DXCC, BAND, LOTW_QSL_SENT, LOTW_QSLSDATE, LOTW_QSL_RCVD, LOTW_QSLRDATE, EQSL_QSL_SENT, EQSL_QSLSDATE, EQSL_QSL_RCVD, EQSL_QSLRDATE

All values should not be HTML escaped.

Please DO NOT use this real time access to batch upload of thousands of QSOs. If your you are uploading log for the first time, upload whole ADIF file through the website.

New QSO

HamQTH will accept new QSO record in ADIF format with at least QSO_DATE, TIME_ON, CALL, MODE, BAND, RST_S, RST_R fields. If you try to post less fields, you'll get HTTP status code 400 with error message in the body.

Update existing QSO

To specify the QSO you want to update in the database, you have to post old values of qso date, time on, callsign and mode. Without these values server won't be able to find your QSO and update it. Old values are also part of ADIF ouput but with OLD_ prefix - OLD_QSO_DATE, OLD_TIME_ON, OLD_CALL, OLD_BAND, OLD_MODE. E.g. you want to update name in the QSO, send only all mandatory fields (OLD_QSO_DATE etc.) and NAME field.

Delete QSO

Specify QSO to delete using OLD_QSO_DATE, OLD_TIME_ON, OLD_CALL, OLD_BAND and OLD_MODE field in ADIF output.

Please DO NOT use this real time QSO upload to batch delete of whole log. If you want to delete it, just disable log search function in your profile preferences.

To be sure that your DXCC statistics will be correct, sending DXCC resp. OLD_DXCC field with every QSO is strongly recommended!

DX cluster spots

HamQTH provides DX cluster spots feed in simple CSV format with this structure:

        Call^Frequency^Date/Time^Spotter^Comment^LoTW user^eQSL user^Continent

No registration needed, just use this link:

http://hamqth.com/dxc_csv.php?limit=10 where:

limit

maximim of downloaded spots, default is 60, max is 200

You'll get this:

ZL2AUB^14103.0^I0UGC^ROS TNX For QSO TU 73!.^0831 2013-05-10^^^EU
SP3CMX^50045.7^SV9GPV/B^JO72OR<ES>KM25EH 599^0830 2013-05-10^^^EU
HA0LG^14044.0^EO5JFF^urff-085, URMA314    73/44^0830 2013-05-10^^^EU
WA4JPT^14200.0^EA8TL^S8 here in North Carolina^0830 2013-05-10^L^E^AF
ON6NL^21071.3^FK8CE^PSK31^0830 2013-05-10^^E^OC
W7BV^14210.0^VK9NT^59 in AZ  CQing^0829 2013-05-10^^^OC
DL3ASM^28004.0^RI1FJ^Franz Josef Land/ Arctic Russia^0829 2013-05-10^L^^EU
UR5EDX^24906.6^7Q7FOC^UP 1^0829 2013-05-10^^^AF
F8CRS^14290.0^TM64PAU^^0828 2013-05-10^^^EU
VK3OHM^7150.0^VK9NT^CQ 59^0828 2013-05-10^^^OC

Please do not refresh the page often then every 10 seconds. Spots from DX spider are saved every 15 seconds so shorter time period won't return any new spots.

Self spotting

Self spotting to dxcluster network is not allowed but sometimes is good to have an opportuninty to let others know you are CQing somewhere. I know that very well. It's late evening, I'm on 17M and calling CQ. RBN receives me on ZL, W, PJ etc. but real hams are gone. So now I can let others to know "Hey, I'm on 18070.0, calling CQ, band seems to be open but nobody's here!".

Uploading spots

You can send this self spots from you app using this link:

http://hamqth.com/addselfspot.php?u=ok2cqr&p=xxx&callsign=ok2cqr&freq=18070.0&mode=CW&comment=band is open!! where:

u	your HamQTH username
p	your HamQTH password
callsign	callsign that will be self spotted
freq	frequency in kHz the station is CQing
mode	mode of operating (CW, SSB, RTTY, etc.)
comment	your comment

The result will be send as HTTP status code with message in the body. The HTTP status codes are:

500 Internal error: This may occurs if the server has any problem in general or there is a problem with your HTTP request. In the body should be more information what happened.
403 Forbidden: Access denied. Your username and/or password was incorrect.
400 QSO Rejected: Spot was rejected for some reason e.g. wrong freq, mode etc.
200 QSO OK: Spot was successfully saved into database.

Supported modes: SSB, CW, FM, AM, DSTAR, FSK31, FSK441, GTOR, HELL, JT44, JT4A, JT4B, JT4C, JT4D, JT4E, JT4F, JT4G, JT65, JT9, JT6M, MFSK16, MT63, OLIVIA, PSK2K, PSK31, PSK63, PSK63F, PSK125, PSKAM10, PSKAM31, PSKAM50, PSKFEC31, PSKHELL, QPSK31, QPSK63, QPSK125, ROS, RTTY, SSTV, THRB, THOR, THRBX, WSPR

Downloading spots

Downloading spots is also very easy and don't require username and password. Use this link: http://hamqth.com/getselfspot.php?limit=10 where:

limit

maximim of downloaded spots, default is 60, max is 200

You'll get this:

        OK2CQR^18086.1^Band seems to be open!^1022 2013-05-12^L^E^EU

The structure is:

        Call^Frequency^Date/Time^Comment^LoTW user^eQSL user^Continent

Spots are added to database as they come from users, so you can poll very often e.g. every 10 seconds or so.

If you find any bug or have any problem with developer's interface, please let me know via petr [at] ok2cqr.com. Everything is provided for free, but please put HamQTH banner on your page, tell your friends about us, or consider small donation. Thank you!

Changelog

2.2 - (12 may 2013) added self spotting inteface
2.1 - (10 may 2013) added dxcluster inteface
2.0 - (20 feb 2013) added social network fields
1.9 - (18 nov 2012) real-time QSO upload interface added
1.8 - (29 sep 2012) added access to bio information through XML interface
1.7 - (02 sep 2012) added log upload interface
1.6 - (28 jun 2012) added ADR and ADR_ADIF fields
1.5 - (22 apr 2012) added XML DXCC search
1.4 - (02 mar 2012) added latitude, longitude, utc_offset and continent fields
1.3 - (07 oct 2011) added prg parameter into XML search query
1.2 - (26 sep 2011) added country and adr_country fields
1.1 - (01 sep 2011) added IOTA field