to QRZ
Latest Awards
QRZ Logbook API Developer Guide
This guide will help you develop applications or scripts that interact with a QRZ logbook using our API.
INTRODUCTION
This API provides methods for external programs to interact with the QRZ Logbook using an HTTP REST interface. The QRZ Logbook is a combination free and paid subscription service of QRZ. Some advanced features require a valid subscription while the majority of operations are free to all QRZ members. All users of the QRZ Logbook, regardless of their subscription status, may access, edit, update, and view their complete logs online at the QRZ website.
LOGBOOK MODEL
A QRZ Logbook is a collection of QSO records that share common attributes. Every QSO in the QRZ Logbook has its own unique integer logid which is used as a unique selector for that log record. In addition, every logbook has its own integer bookid, and belongs to a specific QRZ member. Logbook attributes govern which QSO’s are included in the ‘book’. Every QSO record contains set of key attributes which must be provided in order to be inserted into a given user’s logbook. These are: a bookid, the sending station’s callsign, the receiving station’s callsign, the date and time of the QSO, the frequency band, and the transmission mode.
A given QRZ logbook serves just one callsign. Every character in a callsign is significant including mobile or portable identifiers such as /M or /P. For example, XX1XX and XX1XX/M are treated as separate callsigns, each requiring its own logbook. When a user has a callsign change, a new logbook is opened for the new callsign, and thereafter the user has at least two logbooks, one for the old callsign and one for the new.
Each QRZ logbook has a configurable date range. The date range includes the dates over which the given callsign was or will be active. For example, if a license was issued in 2012-04-01, its date range will start in on that date and its end date will coincide with the published expiration date of their license. QSO reports that are received outside the configured date range will be rejected.
A QRZ member may have or have access to multiple logbooks, each having a unique bookid. Bookid’s are not transmitted in the API but rather are conveyed by an opaque API ACCESS KEY that is provided by QRZ. The unique access key for a given logbook is available to users on the QRZ website. The access key conveys both the user identification and QSO routing necessary to connect an external program to the correct QRZ logbook.
API END POINT
Requests should be made to
https://logbook.qrz.com/api
API INTERFACE
The API uses a name=value pair, HTTP POST interface for both input and output response. QSO data is conveyed in ADIF format as an argument to an ADIF=… parameter.
Below is an example transaction that inserts a new QSO record.
POST DATA:
KEY=ABCD-0A0B-1C1D-2E2F&
ACTION=INSERT&
ADIF=<band:3>80m<mode:3>SSB<call:4>XX1X<qso_date:8>20140121<station_callsign:6>AA7BQ<time_on:4>0346<eor>
Note that line breaks shown above are used for illustration only and are typically not present in the protocol. In practice, all post data is URL encoded into a single string.
RESPONSE:
RESULT=OK&LOGIDS=130877825&COUNT=1
API REQUESTS
Every API interaction with the QRZ server must include the following fields: KEY and ACTION. Other named parameters are either optional or dependent upon the action specified. The server will reject requests containing unrecognized parameters.
API REQUEST PARAMETERS TYPES
| KEY | A QRZ supplied logbook access key |
| ACTION | Type of request, i.e. INSERT, DELETE, UPLOAD, etc. |
| ADIF | ADIF formatted input data |
| OPTION | Action-specific options |
| LOGIDS | A comma separated list of integer logid values |
API RESPONSE TYPES
| RESULT | OK when the operation succeeds, FAIL when the operation failed, AUTH when API Access lacked sufficient privileges for the operation, or other action-specific codes |
| REASON | Used with RESULT=FAIL to describe the specific reason for failure |
| LOGIDS | A comma separated list of logid values that were affected by the action |
| LOGID | The logid value of the record that was inserted or replaced. (Singular “LOGID” response only used by INSERT as it is a single record operation.) |
| COUNT | The number of QSO records that were affected by the action |
| DATA | Used for action-specific data such as status reports |
API COMMANDS
INSERT ACTION (Note: subscription required)
This action inserts one record into the logbook selected by the API Access Key.
REQUEST
| ACTION | INSERT |
| ADIF | The ADIF data to be inserted |
| OPTION |
REPLACE To automatically overwrite any existing duplicate QSOs. |
RESPONSE
| RESULT |
OK when QSO was inserted into the logbook |
| COUNT | Returns the number of records inserted or replaced (Always 1 or 0) |
| LOGID | The logid value of the record that was inserted or replaced |
| REASON | Used with RESULT=FAIL to describe the nature of the error. |
DELETE ACTION (Note: subscription required)
This action deletes one or more QSO records from logbook selected by the API Access Key.
REQUEST
| ACTION | DELETE |
| LOGIDS | LOGIDS A comma separated list of logid values |
RESPONSE
| RESULT | OK if all the requested logid’s were deleted PARTIAL if some or all requested logid’s were not deleted FAIL if none of the requested logid values were found. |
| LOGIDS | Comma separated list of logid values that were not found. Provided only when RESULT=PARTIAL |
| COUNT | Returns the number of QSO records that were deleted |
USAGE NOTES
This command permanently deletes one or more QRZ log entries.
NOTE: There is no ‘undo’ from this operation. Deleted records cannot be recovered.
STATUS ACTION (Note: subscription required)
This command returns a status report on the logbook selected by the API Access Key.
REQUEST
| ACTION | STATUS |
| LOGIDS | LOGIDS A comma separated list of logid values |
RESPONSE
| RESULT | OK if the command succeeded FAIL if the Access Key is invalid |
| DATA | Returns logbook status parameters in a & separated list of name=value pairs. May include items such as: Total QSO’s in book, total confirmed, DXCC total, USA States total, start date, end date, book owner, bookid, book name, authorized users. |
FETCH ACTION (Note: subscription required)
Fetch one or more QSO records from the logbook selected by the API Access Key. This command provides for selection of specific records meeting specific criteria.
REQUEST
| ACTION | FETCH |
| OPTION |
ALL to fetch the entire logbook (default) |
PAGING RESULTS
We recommend that your application implements some form of paging when retrieving data, Some logbooks can be extremely large and downloading the entire book in on transaction may timeout.
The easiest way to achieve this is adding MAX:250,AFTERLOGID:0 to your options, this will return a maximum of 250 results starting at the begining of the logbook. If the data your receive contains 250 records you should make additional requests, altering the AFTERLOGID value to be the highest value of app_qrzlog_logid returned in the previous request, until you receive less than 250 (or the MAX value requested) records.
USAGE NOTES
The options values are sent as a comma separated list of colon separated name:value pairs. There should be no spaces in the option request. For example,
BAND:80m,MODE:SSB,MAX:400
RESPONSE
| RESULT | OK if any QSO’s matched the fetch option(s). FAIL if there was a parameter or other problem. |
| COUNT | Number of records matching the selection criteria. |
| LOGIDS | Comma separated list of logid values that match the selection criteria, limited by the MAX parameter. |
| ADIF | ADIF data containing the QSO’s that match the selection criteria, limited by the MAX parameter. |
USAGE NOTES
Multiple options may be combined, separated by the ampersand or semicolon (& or ;) characters. COUNT always returns the number of records matching given OPTIONS criteria. To fetch only the COUNT result of a selection, specify a MAX of 0. When the option ALL is given, only the options TYPE and STATUS may also be specified. For general logbook status, use the STATUS command