Documentation de l'API HAMBOOK

Intégrez vos logiciels radioamateurs avec le carnet de trafic hambook.site

Authentification et Sécurité

Pour travailler avec l'API, vous avez besoin d'une clé API personnelle (API Key). Toutes les requêtes API doivent être exécutées dans le contexte d'un utilisateur spécifique.

Comment obtenir votre clé API :
  1. Connectez-vous à votre Espace personnel sur le portail hambook.site.
  2. Allez dans l'onglet 'Paramètres' et trouvez la section 'Clés API'.
  3. Indiquez le nom de votre application et cliquez sur 'Générer la clé'.
Format de la requête HTTP

La transmission des données QSO se fait via une requête POST standard. La clé d'autorisation doit être transmise dans l'en-tête HTTP ou comme paramètre GET.

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]

Paramètres de requête acceptés

Les données doivent être soumises au format application/x-www-form-urlencoded (requête POST classique).

Parameter Type Required Description / Example
call string YES Indicatif du correspondant (sera automatiquement converti en majuscules).
Example: W1AW, R3TJL/3
my_call string No Votre indicatif (station). Si vide, l'indicatif principal de l'utilisateur sera utilisé automatiquement.
Example: R8LCA
band string No Bande de fréquence au format ADIF (sera automatiquement convertie en majuscules).
Example: 20m, 40m, 2m
mode string No Type de modulation (mode) au format ADIF.
Example: CW, SSB, FT8
submode string No Sous-mode de modulation (pour FT4, PSK31, etc.).
Example: FT4
freq float No Fréquence exacte du QSO en MHz.
Example: 14.074
qso_date string No Date du QSO au format AAAAMMJJ. Si vide, la date actuelle sera utilisée.
Example: 20260623 (YYYYMMDD)
time_on string No Heure de début du QSO au format HHMM (en UTC). Si vide, l'heure actuelle sera utilisée.
Example: 1753 (HHMM, UTC)
rst_sent string No Rapport RST envoyé.
Example: 599, -12 (Default: 59)
rst_rcvd string No Rapport RST reçu.
Example: 59, -08 (Default: 59)
gridsquare string No Localisateur d'antenne (Grid) du correspondant.
Example: FN31, LO06ff
my_gridsquare string No Votre localisateur d'antenne (Grid) pendant le QSO.
Example: LO06ee
qth string No Ville/localisation du correspondant.
Example: Nizhny Novgorod
name string No Nom du correspondant.
Example: John
comment string No Commentaire personnalisé pour le QSO.
Example: QRP 5W, dipole

Formats des réponses du serveur (JSON)

L'API hambook.site renvoie toujours une réponse au format JSON avec un statut HTTP 200, même en cas d'erreurs.

Enregistré avec succès 
{
  "status": "success",
  "id": 471295
}
Doublon détecté (ignoré) 
{
  "status": "success",
  "message": "Duplicate ignored",
  "id": 471294
}
Erreur d'authentification 
{
  "status": "error",
  "message": "Invalid API Key"
}

Exemples d'intégration de code

<?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)