Developer Information: Querying LoTW for Acceptance and Confirmation of Submitted QSOs
LoTW provides a web service at https://lotw.arrl.org/lotwuser/lotwreport.adi that accepts RESTful queries that report QSOs satisfying specified criteria:
- accepted by LoTW after a specified date
- confirmed by LoTW after a specified date
- with a specified callsign
- with an operator in a specified DXCC entity
- in a specified mode
- on a specified band
- at a specified date and timeusing a specified station callsign
Using this web service, a logging application can update logged QSOs to reflect their status in LoTW:
- submitted, but not accepted
- accepted, but not confirmed
- confirmed
- award credit granted to LoTW confirmations
Note: award credit granted to QSOs for QSL card confirmations is not reported.
In normal use, client applications are expected to
- Request QSO records received (uploaded) since the last request in order to verify receipt of sent data. This can be done by keeping track of the APP_LoTW_LASTQSORX value returned with the results of a query. That value can be used to as the qso_qslsince value if the identical query is subsequently made.
- Request QSL records received since the last request in order to update the "QSL received" status of logged QSOs. This can be done by keeping track of the APP_LoTW_LASTQSL value returned with the results of a query. That value can be used to as the qso_qslsince value if the identical query is subsequently made.
Matching a downloaded record to data in a logging application'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 that a QSO's mode may be mapped to a different value by the user when the data is prepared to be sent to LoTW. 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.
Logging application developers should keep in mind that users may submit QSOs to LoTW from more than one source, so the downloaded data may contain QSOs not present in the logging application's database.
Each 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 recieved (matched) since previous download for user ke3z if "notmypass" were ke3z's password.
QSO records and QSL records are reported in ADIF format, with a header and one record per QSO or QSL using the ADIF fields described below.
If the query fails, an HTML page containing an explanation will be returned; the absence of an ADIF end of header tag can be used to detect this outcome.
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 (matched or updated) on or after the specified date. Will also accept date/time in "YYYY-MM-DD HH:MM:SS" format. Ignored unless qso_qsl="yes". *Default value (when qso_qslsince is missing or empty) is the greasted value of APP_LoTW_LASTQSL returned for a non-specific 'qso_qsl="yes" query. |
| qso_qsorxsince | date (YYYY-MM-DD) | * |
Returns QSO records received (uploaded) on or after the specified date. Will also accept date/time in "YYYY-MM-DD HH:MM:SS" format. Ignored unless qso_qsl="no". *Default value (when qso_qsorxsince is missing or empty) is the value of APP_LoTW_LASTQSORX returned for a non-specific 'qso_qsl="no" query. |
| 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 this report was received. This will be the QSL date/time of the first QSO record in the file. This value only applies to the records in this 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 this report was received. This will be the QSO received (uploaded) date/time of the first QSO record in the file. This value only applies to the records in this file. | |
| 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 | |||
| FREQ | in megahertz, with fixed precision of 5 decimal places | ||
| BAND_RX | only present if value is different than BAND | ||
| FREQ_RX | in megahertz, with fixed precision of 5 decimal places; only present if value is different than FREQ | ||
| 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" Indicates 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 | |||
| APP_LoTW_QSO_TIMESTAMP | Combined QSO Date & Time in ISO-8601 format | ||
| PROP_MODE | Present only if uploaded QSO included the PROP_MODE field | ||
| SAT_NAME | Present only if uploaded QSO included the SAT_NAME field | ||
| APP_LoTW_RXQSO | Timestamp (YYYY-MM-DD HH:MM:SS) at which QSO record was inserted/updated at LoTW | ||
| QSL_RCVD | "Y" if QSL received, "N" if not | ||
| QSLRDATE | Present only if QSL_RCVD="Y" | ||
| APP_LoTW_RXQSL | Timestamp (YYYY-MM-DD HH:MM:SS) at which the conrfirmation match (QSL) was made/updated at LoTW. 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. | ||
| QSO Detail Fields (Present only if QSL_RCVD="Y" and qso_qsldetail="yes") | |||
| DXCC | The ARRL DXCC Entity code | ||
| COUNTRY | Name (in English) of the ARRL DXCC Entity | ||
| APP_LoTW_DXCC_ENTITY_STATUS | Current, Deleted | Indicates whether the ARRL DXCC entity is "Current" -- counts toward Honor Roll, 5 Band DXCC and DXCC Challenege awrads -- or "Deleted" | |
| APP_LoTW_NPSUNIT | Present only if the QSLing station included a valid NPOTA Park code or a comma-delimited list of valid NPOTA Park codes | ||
| PFX | The prefix 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 | ||
| APP_LoTW_CQZ_UserInvalid | Present only if the QSLing station included an invalid 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 | ||
| APP_LoTW_ITUZ_UserInvalid | Present only if the QSLing station included an invalid 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 specified a single valid grid square value in its station location uploaded to LoTW. | ||
| VUCC_GRIDS | A comma-delimited list of grid squares present only if the QSLing station specified multiple valid grid grid square values because its station location was at a grid boundary or intersection (see VUCC rule #4). | ||
| STATE | US State or Canadian province. Present only if the QSLing station included a valid US state or Canada province value in its station location uploaded to LoTW. | ||
| CNTY | US County. Present only if the QSLing station included a valid US 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. | ||
| MY_VUCC_GRIDS | A comma-delimited list of grid squares present only if the Logging station specified multiple valid grid square values because 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>. DEPRECATED -- Since this tag is not ADIF-compliant it will be replaced in a future release when an ADIF-compliant end-of-file marker is available. | ||
