ARRL

ADIF

Logbook of the World - ADIF Output

LoTW can return log data to the user in ADIF format. This is intended principally for verification of receipt of data and for determining the "QSL" (matched) status of log records by third-party logging programs.

Log data is downloaded by accessing the URL https://lotw.arrl.org/lotwuser/lotwreport.adi using appropriate query parameters in the URL. The query parameters select the subset of records to be returned and the set of optional data fields in the output. (Note that the URL requires https, not http!)

In normal use, we expect that logging programs will:

  1. Request QSO records received (uploaded) since the last request in order to verify receipt of sent data. (This is most efficiently done by keeping track of the APP_LoTW_LASTQSORX value returned with the results of a query. That value can be used to determine the qso_qsorxsince value for a subsequent query.)

     

  2. Request QSL records received since the last request in order to update the "QSL received" status of logged QSOs. (This is most efficiently done by keeping track of the APP_LoTW_LASTQSL value returned with the results of a query. That value can be used to determine the qso_qslsince value for a subsequent query.)

     

Matching a downloaded record to data in the logging program's database can be done by comparing the QSO date, time, band, mode and "worked" call sign of the downloaded record to the records of the local database. (Note, though, that the mode may be mapped to a different value by the user when the data is prepared to be sent to Logbook. It may be best to leave the mode out of the comparison except in the case where a downloaded record matches multiple QSO records of the local database.)

Programmers should keep in mind that users may upload data to LoTW from more than one source, so the downloaded data may contain records not in the logging program's database.

Query

The query is an HTTP "GET" string, formed in accordance with standard URL requirements (e.g., RFC1738). An example query URL might look like:

https://lotw.arrl.org/lotwuser/lotwreport.adi?login=ke3z&password=notmypass&qso_query=1

(This query would return all QSL records for user ke3z if "notmypass" were ke3z's password.)

 

Query Parameters

Parameter Allowable
Values
Default
Value
Notes
Required Parameters
login username   Note that while the user's primary call sign is usually the username, this is not always the case and should not be assumed.
password password    
qso_query "1"   If absent, ADIF file will contain no QSO records
Parameters used to select records
qso_qsl "yes" or "no" "yes" If "yes", only QSL records are returned
qso_qslsince date (YYYY-MM-DD)   Returns QSL records received on or after the specified date. Will also accept date/time in "YYYY-MM-DD HH:MM:SS" format. Ignored unless qso_qsl="yes".
qso_qsorxsince date (YYYY-MM-DD)   Returns QSO records received on or after the specified date. Will also accept date/time in "YYYY-MM-DD HH:MM:SS" format. Ignored unless qso_qsl="no".
qso_owncall call sign   Returns only records whose "own" call sign matches.
qso_callsign call sign   Returns only records whose "worked" call sign matches.
qso_mode Mode   Returns only records whose mode matches. Mode must be one of the allowed modes.
qso_band ADIF band value   Returns only records whose band matches. Mode must be one of the allowed bands.
qso_dxcc DXCC number   Returns only records whose DXCC entity matches. (This implies qso_qsl="yes" since the DXCC entity of un-QSL'd stations isn't known to LoTW.) Value must be the ARRL DXCC entity number.
qso_startdate date (YYYY-MM-DD)   Returns only records with a QSO date on or after the specified value.
qso_starttime time (HH:MM:SS)   Returns only records with a QSO time at or after the specified value on the starting date. This value is ignored if qso_startdate is not provided.
qso_enddate date (YYYY-MM-DD)   Returns only records with a QSO date on or before the specified value.
qso_endtime time (HH:MM:SS)   Returns only records with a QSO time at or before the specified value on the ending date. This value is ignored if qso_enddate is not provided.
Parameters used to select output fields
qso_mydetail "yes" or blank   If "yes", returns fields that contain the Logging station's location data, if any.
qso_qsldetail "yes" or blank   If "yes", returns fields that contain the QSLing station's location data, if any.
qso_withown "yes" or blank   If "yes", each record contains the STATION_CALLSIGN and APP_LoTW_OWNCALL fields to identify the "own" call sign used for the QSO.

ADIF Fields

The following table shows the ADIF fields that appear in the output. Where no Value is shown, the value of the field is that of the standard ADIF field of that name.

Field Name Value Notes
Header Fields
PROGRAMID LoTW  
APP_LoTW_LASTQSL date/time
(YYYY-MM-DD HH:MM:SS)
Present only if qso_qsl="yes". Date and time at which the most recent QSL record in the report was received. This will be the QSL date/time of the first QSO record in the file.
APP_LoTW_LASTQSORX date/time
(YYYY-MM-DD HH:MM:SS)
Present only if qso_qsl="no". Date and time at which the most recent QSO record in the report was received.
APP_LoTW_NUMREC   Number of QSO records in this download
QSO Data Fields
APP_LoTW_OWNCALL call sign "own" call sign of the station making the contact. Present only if qso_withown="yes". DEPRECATED -- In the near future, this field will no longer be present in the report output. Programs that import LoTW report files should not rely on the presence of this field. Use STATION_CALLSIGN instead.
STATION_CALLSIGN call sign "own" call sign of the station making the contact. Present only if qso_withown="yes".
CALL    
BAND    
MODE   NOTICE -- In a future release, Logbook will not emit the MODE field if the mode value recorded in Logbook cannot be unambiguously represented as an ADIF-compliant value. In such cases  the mode value for the QSO will be provided via the field APP_LoTW_MODE and the MODE field will not be present in the QSO record
APP_LoTW_MODE   Field is present when the mode recorded in Logbook cannot be unambiguously represented as an ADIF-compliant value
APP_LoTW_MODEGROUP CW, PHONE, DATA The mode group indicates whether the QSO's mode counts towards the CW, Phone or Digital awards respectively in the DXCC program. A  mode group of CW indicates the QSO's mode counts towards tthe CW endorsement on WAS awards. A mode group of PHONE indicates the QSO's mode  counts towards the WAS Phone award. A mode group of DATA indicates the QSO's mode counts towards the CQ WPX Digital award. 
APP_LoTW_2xQSL Y or N APP_LoTW_2xQSL ="Y" Indiicates this confirmation is considered to be "two-way" in the QSO's Mode. It is a confirmation that counts towards the mode-specific awards & endorsement in the WAS program. Only present if QSL_RCVD="Y".
APP_LoTW_QSLMODE   The Mode that your QSO partner indicated on their side of this QSO. Only present if QSL_RCVD="Y" and APP_LoTW_2xQSL="N".
QSO_DATE    
TIME_ON    
PROP_MODE    Present only if uploaded QSO  included the PROP_MODE field
SAT_NAME    Present only if uploaded QSO included the SAT_NAME field
QSL_RCVD   "Y" if QSL received, "N" if not
QSLRDATE   Present only if QSL_RCVD="Y"
CREDIT_GRANTED   Award credits granted based upon this QSL. Awards per ADIF award enumeration.
APP_LoTW_CREDIT_GRANTED   Award credits granted based upon this QSL. Awards per LoTW award enumeration.
CREDIT_SUBMITTED   Award credits for which this QSL has been submitted on an award application to sponsor. Awards per ADIF award enumeration.
APP_LoTW_CREDIT_SUBMITTED   Award credits for which this QSL has been submitted on an award application to sponsor. Awards per LoTW award enumeration.
QSL Detail Fields
(Present only if QSL_RCVD="Y" and qso_qsldetail="yes")
DXCC   The QSKing station's ARRL DXCC Entity code
COUNTRY   Name (in English) of the QSLing station's ARRL DXCC Entity
APP_LoTW_DXCC_ENTITY_STATUS Current, Deleted Indicates whether the QSLing station's ARRL DXCC entity is "Current"  -- counts toward Honor Roll, 5 Band  DXCC  and DXCC Challenege awrads -- or "Deleted"
PFX   The prefix of the QSLing station according to rules of  the CQ WPX Award program 
CONT   Present only if the QSLing station included a valid continent value in its station location uploaded to LoTW
CQZ   Present only if the QSLing station included a valid CQ zone value in its station location uploaded to LoTW
ITUZ   Present only if the QSLing station included a valid ITU zone value in its station location uploaded to LoTW
IOTA   Present only if the QSLing station included a valid IOTA number value in its station location uploaded to LoTW
GRIDSQUARE   Present only if the QSLing station included a valid grid square value in its station location uploaded to LoTW. Multiple instances of GRIDSQUARE appear in a QSO record if the QSLing station indicated that its station location was at a grid boundary or intersection (see VUCC rule #4)
STATE   Present only if the QSLing station included a valid Primary Adminitrative Subdivision (State) value in its station location uploaded to LoTW.
CNTY   Present only if the QSLing station included a valid Secondary Administartive Subdivision (County) value in its station location uploaded to LoTW
QSO (Logging Station) Detail Fields
(Present only if qso_mydetail="yes")
MY_DXCC   The Logging station's ARRL DXCC Entity code
MY_COUNTRY   Name (in English) of the Logging station's ARRL DXCC Entity
APP_LoTW_MY_DXCC_ENTITY_STATUS Current, Deleted Indicates whether the Logging station's  ARRL DXCC entity is "Current"  -- counts toward Honor Roll, 5 Band  DXCC  and DXCC Challenege awrads -- or "Deleted"
MY_CQ_ZONE   Present only if the Logging station included a valid CQ zone value in its station location uploaded to LoTW
MY_ITU_ZONE   Present only if the Logging station included a valid ITU zone value in its station location uploaded to LoTW
MY_IOTA    Present only if the Logging station included a valid IOTA number value in its station location uploaded to LoTW
MY_GRIDSQUARE    Present only if the Loggng station included a valid grid square value in its station location uploaded to LoTW. Multiple instances of MY_GRIDSQUARE appear in a QSO record if the Logging station indicated that its station location was at a grid boundary or intersection (see VUCC rule #4)
MY_STATE   Present only if the Logging station included a valid Primary Administartive Subdivision (State) value in its station location uploaded to LoTW.  
MY_CNTY   Present only if the Logging station included a valid Secondary Administartive Subdivision (County) value in its station location uploaded to LoTW
End-of-file Field
APP_LoTW_EOF   Indicates end of file. This can be used to verify that the file was completely received. This field is not followed by <eor>. DEPRECTAED -- Since this tag is not ADIF-compliant, it will be replaced in a future release once an ADIF-compliant end-of-file maker becomes available.