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:
- 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.)
- 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 HTTPS "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 QSLing 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. | ||
