ADIF Output
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://p1k.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 HTTP "GET" string, formed in accordance with standard URL requirements (e.g., RFC1738). An example query URL might look like:
https://p1k.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_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. | |
| 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 | |||
| QSO_DATE | |||
| TIME_ON | |||
| QSL_RCVD | "Y" if QSL received, "N" if not | ||
| QSLRDATE | Present only if QSL_RCVD="Y" | ||
| QSO Detail Fields (Present only if QSL_RCVD="Y" and qso_qsldetail="yes") |
|||
| DXCC | Value is the ARRL DXCC Entity number | ||
| CONT | Present only if the QSLing station included a valid continent value in its log | ||
| CQZ | Present only if the QSLing station included a valid CQ zone value in its log | ||
| ITUZ | Present only if the QSLing station included a valid ITU zone value in its log | ||
| IOTA | Present only if the QSLing station included a valid IOTA number value in its log | ||
| GRIDSQUARE | Present only if the QSLing station included a valid grid square value in its log | ||
| STATE | US State or Canadian province. Present only if the QSLing station included a valid US state or Canada province value in its log. | ||
| CNTY | US County. Present only if the QSLing station included a valid US county value in its log | ||
| 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>. | ||
