Документація HAMBOOK API

Інтеграція вашого радіоаматорського софту з апаратним журналом hambook.site

Авторизація та безпека

Для роботи з API вам необхідний персональний ключ API Key. Усі запити до API повинні виконуватися в контексті конкретного користувача сайту.

Як отримати ваш API-ключ:
  1. Увійдіть до Особистого кабінету на порталі hambook.site.
  2. Перейдіть на вкладку «Налаштування» та знайдіть розділ «Ключі API».
  3. Вкажіть назву вашого додатка та натисніть кнопку «Згенерувати ключ».
Формат HTTP-запиту

Передача даних QSO виконується стандартним POST-запитом. Ключ авторизації повинен передаватися в HTTP-заголовку або у вигляді GET-параметра.

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]

Прийнятні параметри запиту

Дані повинні передаватися у форматі application/x-www-form-urlencoded (звичайний POST-запит з форми).

Parameter Type Required Description / Example
call string YES Позивний кореспондента (буде автоматично переведений у верхній регістр).
Example: W1AW, R3TJL/3
my_call string No Ваш позивний (станція). Якщо порожній — автоматично підставиться основний позивний користувача з профілю.
Example: UB3TLU
band string No Діапазон зв'язку в ADIF-форматі (буде автоматично переведений у верхній регістр).
Example: 20m, 40m, 2m (или вычисляется автоматически по freq)
mode string No Вид модуляції (вид роботи) в ADIF-форматі.
Example: CW, SSB, FT8
submode string No Підвид модуляції (для FT4, PSK31 та ін.).
Example: FT4, USB, LSB
freq float No Точна частота зв'язку в МГц.
Example: 14.074 (MHz)
qso_date string No Дата проведення зв'язку у форматі РРРРММДД. Якщо порожня — підставиться поточна дата.
Example: 20260623 (YYYYMMDD)
time_on string No Час початку зв'язку у форматі ГГХХ (за UTC). Якщо порожній — підставиться поточний час.
Example: 1753 или 175300 (HHMM / HHMMSS, UTC)
rst_sent string No Переданий RST (рапорт).
Example: 599, -12 (Default: 59)
rst_rcvd string No Отриманий RST (рапорт).
Example: 59, -08 (Default: 59)
gridsquare string No QTH-локатор кореспондента.
Example: FN31, LO26ah (автоматически рассчитывает координаты для карты!)
my_gridsquare string No Ваш QTH-локатор під час зв'язку.
Example: LO26mg
qth string No Місто/місцезнаходження кореспондента.
Example: Nizhny Novgorod
name string No Ім'я кореспондента.
Example: John
comment string No Довільний коментар до QSO.
Example: QRP 5W, dipole

Формати відповідей сервера (JSON)

API hambook.site завжди повертає відповідь у форматі JSON з HTTP-статусом 200, навіть у разі помилок.

Успішний запис 
{
  "status": "success",
  "id": 1430955,
  "confirmed": true
}
confirmed: true означает мгновенное встречное подтверждение (CFM)!
Виявлено дублікат (пропущено) 
{
  "status": "success",
  "message": "Duplicate ignored",
  "id": 1430954
}
Помилка авторизації 
{
  "status": "error",
  "message": "Invalid API Key"
}

Приклади інтеграції в код

<?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"
  }'