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.

APPLICATION IDENTIFICATION REQUIREMENTS

All applications accessing the Logbook API *MUST* provide an identifiable user agent header.

For individuals writing scripts for personal use please include your callsign and a unique (to you) name for your script so that it can be identified if we need to contact you. For example MyCoolUploadScript.py/1.0.0 (VA7STV) or MyUploadScriptIsCoolerThanYours.py/1.0.1 (KF8KI)

For application developers or widely distributed scripts we suggest using the format ApplicationName/1.20.2112 (where the second component is a version number or date of release)

Applications making requests without providing a user agent or that provide a generic user agent such as node-fetch or python-requests could be subject to rate limiting or other restrictions.

User agents should be 128 characters or less.

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:5>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

API RESPONSE TYPES

API COMMANDS

INSERT ACTION    (Note: subscription required)

This action inserts one record into the logbook selected by the API Access Key.

REQUEST

RESPONSE

DELETE ACTION    (Note: subscription required)

This action deletes one or more QSO records from logbook selected by the API Access Key.

REQUEST

RESPONSE

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

RESPONSE

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

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

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