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 (Form-Data или JSON)
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: UB3TLU
band string No Frequency band in ADIF format (will be automatically capitalized).
Example: 20m, 40m, 2m (или вычисляется автоматически по freq)
mode string No Modulation type (mode) in ADIF format.
Example: CW, SSB, FT8
submode string No Modulation submode (for FT4, PSK31, etc.).
Example: FT4, USB, LSB
freq float No Exact QSO frequency in MHz.
Example: 14.074 (MHz)
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 или 175300 (HHMM / HHMMSS, 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, LO26ah (автоматически рассчитывает координаты для карты!)
my_gridsquare string No Your Grid Locator during the QSO.
Example: LO26mg
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": 1430955,
  "confirmed": true
}
confirmed: true означает мгновенное встречное подтверждение (CFM)!
Duplicate detected (ignored) 
{
  "status": "success",
  "message": "Duplicate ignored",
  "id": 1430954
}
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',
    'freq'       => 14.074,
    'mode'       => 'FT8',
    'rst_sent'   => '-10',
    'rst_rcvd'   => '-05',
    'gridsquare' => 'FN31pr',
    'comment'    => 'Logged via Hambook API v5'
];

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',
    'freq': 14.074,
    'mode': 'FT8',
    'rst_sent': '-10',
    'rst_rcvd': '-05',
    'gridsquare': 'FN31pr',
    'comment': 'Logged via Python API'
}

response = requests.post(url, headers=headers, json=data)
print(response.json())
curl -X POST https://hambook.site/api/v1/qso/ \
  -H "Content-Type: application/json" \
  -H "X-Hambook-Key: YOUR_API_KEY_HERE" \
  -d '{
    "call": "W1AW",
    "band": "20m",
    "freq": 14.074,
    "mode": "FT8",
    "rst_sent": "-10",
    "rst_rcvd": "-05",
    "gridsquare": "FN31pr"
  }'