HAMBOOK API Documentation

Integrate your amateur radio software with hambook.site logbook

Authentication & Security

To work with the API, you need a personal API Key. All API requests must be executed in the context of a specific site user.

How to obtain your API Key:
  1. Log in to your Personal Cabinet on the hambook.site portal.
  2. Go to the 'Settings' tab and find the 'API Keys' section.
  3. Enter your application name and click the 'Generate Key' button.
HTTP Request Format

QSO data transmission is performed using a standard POST request. The authorization key must be passed either in the HTTP header or as a GET parameter.

Method POST
Endpoint URL https://hambook.site/api/v1/qso/
Auth Header X-Hambook-Key: [your_api_key]
Alternative GET Auth https://hambook.site/api/v1/qso/?key=[your_api_key]

Accepted Request Parameters

Data should be submitted in application/x-www-form-urlencoded format (standard form POST request).

Parameter Type Required Description / Example
call string YES Correspondent's callsign (will be automatically capitalized).
Example: W1AW, R3TJL/3
my_call string No Your callsign (station). If empty, the user's primary callsign from their profile will be used automatically.
Example: R8LCA
band string No Frequency band in ADIF format (will be automatically capitalized).
Example: 20m, 40m, 2m
mode string No Modulation type (mode) in ADIF format.
Example: CW, SSB, FT8
submode string No Modulation submode (for FT4, PSK31, etc.).
Example: FT4
freq float No Exact QSO frequency in MHz.
Example: 14.074
qso_date string No QSO date in YYYYMMDD format. If empty, the current date will be used.
Example: 20260623 (YYYYMMDD)
time_on string No QSO start time in HHMM format (UTC). If empty, the current time will be used.
Example: 1753 (HHMM, UTC)
rst_sent string No Sent RST report.
Example: 599, -12 (Default: 59)
rst_rcvd string No Received RST report.
Example: 59, -08 (Default: 59)
gridsquare string No Correspondent's Grid Locator.
Example: FN31, LO06ff
my_gridsquare string No Your Grid Locator during the QSO.
Example: LO06ee
qth string No Correspondent's city/location.
Example: Nizhny Novgorod
name string No Correspondent's name.
Example: John
comment string No Custom comment for the QSO.
Example: QRP 5W, dipole

Server Response Formats (JSON)

The hambook.site API always returns a response in JSON format with HTTP status 200, even in case of errors.

Successfully recorded 
{
  "status": "success",
  "id": 471295
}
Duplicate detected (ignored) 
{
  "status": "success",
  "message": "Duplicate ignored",
  "id": 471294
}
Authorization error 
{
  "status": "error",
  "message": "Invalid API Key"
}

Code Integration Examples

<?php
$ch = curl_init('https://hambook.site/api/v1/qso/');
$data = [
    'call' => 'W1AW',
    'band' => '20m',
    'mode' => 'CW',
    'rst_sent' => '599',
    'rst_rcvd' => '599',
    'comment' => 'Logged via API'
];

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-Hambook-Key: YOUR_API_KEY_HERE'
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);
?>
import requests

url = 'https://hambook.site/api/v1/qso/'
headers = {
    'X-Hambook-Key': 'YOUR_API_KEY_HERE'
}
data = {
    'call': 'W1AW',
    'band': '20m',
    'mode': 'CW',
    'rst_sent': '599',
    'rst_rcvd': '599',
    'comment': 'Logged via Python API'
}

response = requests.post(url, headers=headers, data=data)
result = response.json()
print(result)