QRZ.COM
ad: Radclub22-1
ad: L-HROutlet
ad: l-rl
ad: Radclub22-2
ad: Left-3
ad: Left-2
ad: L-MFJ
ad: abrind-2
Latest Awards
United States Awards Issued
United States Awards Issued
United States Awards Issued
United States Awards Issued
United States Awards Issued
United States Awards Issued
United States Awards Issued
United States Awards Issued
United States Awards Issued
United States Awards Issued
United States Awards Issued
United States Awards Issued
United States Awards Issued
United States Awards Issued
United States Awards Issued

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.
(WARNING: This WILL overwrite confirmed QSOs with the supplied unconfirmed QSO until the new QSO data is verified as a match)

 

RESPONSE

RESULT

OK when QSO was inserted into the logbook
FAIL if the QSO was NOT inserted
REPLACE if the QSO was a duplicate, and subsequently overwritten

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)
DXCC:nnn fetch those records having DXCC=nnn
BETWEEN:2014-01-01+2014-01-31 applies a date range to the fetch. Fetches those records dated between the two dates (start+end) (default: all)
MODSINCE:2023-01-01 only return records modified since this date
AFTERLOGID:123123123 only return records with a app_qrzlog_logid value greater than the number provided.
BAND:xxx fetch those QSO’s from the given band
MODE:xxx fetch those QSO’s having the given mode
CALL:XX1XX fetch those records of QSO’s with the indicated callsign LOGIDS:nnn+nnn+nnn list of logid’s to fetch
MAX:nnnn maximum number records to fetch (can be 0). Not specified = unlimited (default)
TYPE:ADIF|LOGIDS used to select either a logid list or ADIF data (default)
STATUS:CONFIRMED|ALL used to select either confirmed records, or, all matching records (default is ALL)

 

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


This page was last updated October 18, 2023 16:15