For application developers

A: 11 | K: 2 | SFI: 227 | SSN: 126 | GF: QUIET

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

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
uusername registered on HamQTH (station callsign)
puser'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
idsession ID requested before
callsigncallsign you are looking for
YOUR_PROGRAM_NAMEName 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
callsigncallsign you searched
nickname used on the air
qthcallsign's QTH
countrycountry related to callsign, not to the address
adifADIF ID of country related to callsign
ituITU zone
CQCQ (WAZ) zone
gridstation locator
adr_nameaddress name
adr_street1street address
adr_street2street address
adr_street3street address
adr_citycity address
adr_zipzipcode
adr_countrycountry related to the address
adr_adifADIF ID of address country
districtstation district
us_stateUS state (USA stations only)
us_countyUS county (USA stations only)
oblastsomething like district (Russian stations)
dokDOK (DL stations)
iotaIOTA reference number
qsl_viaQSL information
lotwY - uses LoTW, N - doesn't use LoTW, ? - we don't know
eqslY - uses eQSL, N - doesn't use eQSL, ? - we don't know
qslY - accept paper QSL cards, N - doesn't accept papaer QSL cards, ? - we don't know
emailemail
jabberjabber
icqicq number
msnMSN
skypeSkype
birth_yearYear of birth
lic_yearLicenced since
picturelink to user's picture
latitudestation position - latitude
longitudestation position - longitude
continentcontinent
utc_offsetoffset to UTC time in station location
facebooklink to Facebook profile
twitterlink to user's Twitter feed
gpluslink to GooglePlus profile
youtubelink to user's YouTube channel
linkedinlink to user's LinkedIn profile
flickerlink to user's flicker profile
vimeolink 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:
idsession ID requested before
callsigncallsign's bio you are looking for
strip_html1 - 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:
callsigncallsign you searched
biothe 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:
idsession ID requested before
callsigncallsign you are looking for
rec_activity1 - include also data from RBN and dx clusters (default value), 0 do not add RBN and DX clusters data
log_activity1 - include 20 qso QSO from HamQTH logbook (default value), 0 do not add logbook data
logbook1 - 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:
activitysection with records from RBN and DX clusters network
  sourcesource of the data - RBN or DXC
  spotterstation that send the spot (DXC) or callsign of reverse beacon network station
  callsignspotted callsign
  noteshort note related to the spot
  freqfrequency in kHz
  datespot sent date
  timespot sent time
log_activitysection with records HamQTH logbook - list of station that has callsign in their logs
  callsignstation that has QSO in the log with station you are looking for
  modemode of operating
  bandband like in ADIF spec e.g. 160M, 40M etc.
  dateQSO date
logbooksection with records in station's HamQTH logbook - list of 20 most recent QSOs in station's log
  callsignwkd callsign
  modemode of operating
  bandband like in ADIF spec e.g. 160M, 40M etc.
  dateQSO 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:

callsignthe 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:

limitmaximim 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:

uyour HamQTH username
pyour HamQTH password
callsigncallsign that will be self spotted
freqfrequency in kHz the station is CQing
modemode of operating (CW, SSB, RTTY, etc.)
commentyour 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:

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

Simple award verification protocol

Numerous web services and web sites all over the world provide electronic storage of “station logs”. Whatever we call it, eQSL, LoTW, all of them are but centrally managed collections of ham radio station logs in databases. Small amateur radio societies, often issue awards for contacts with their members. “Worked all members” is the simplest possible award imaginable. A really small ham radio society could theoretically avoid checking QSL cards, by inspecting their members’ log books .... continue in SAVP-SimpleAwardVerificationProtocol-short.pdf and SAVPGuidelines.pdf written by Jindra, OK4RM.

Example

HTTP client will send verification request using GET method:

http://hamqth.com/verifyqso.php?mycall=j49c&hiscall=ok2cqr&date=20130620&band=12M
The result is described in specification above.


JSON DXCC search

The same like XML DXCC search but it returns data in JSON.

Example

http://hamqth.com/dxcc_json.php?callsign=U3AP

and you'll get this:

{"callsign":"U3AP", "name":"Russia (European)", "details":"Russia (European), Gorod Moskva (MA), World War II. Veteran", "continent":"EU". "utc":"-3", "waz":"16", "itu":"29", "lat":"55.75", "lng":"37.63", "adif":"54"}



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.4 - (29 Jun 2014) added JSON DXCC search 2.3 - (25 jun 2013) added Simple award verification protocol
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