API do LogBeam

Fundamentos

Todos os pedidos são feitos a https://api.logbeam.org/api. As respostas são JSON (UTF-8), comprimidas com gzip quando o cliente o aceita, e usam sempre o mesmo envelope:

{ "status": "success", "message": "Success", "data": { … } }

Em caso de erro, status é "error" e message explica o motivo. O código HTTP acompanha: 200 ou 201 em sucesso, 400 pedido inválido, 401 sem autorização, 404 não encontrado, 423 logbook bloqueado, 429 demasiados pedidos, 500 erro interno.

Identificador do logbook: os 10 caracteres hexadecimais do URL do logbook (…/view.php?id=d4405e6967). Datas e horas em UTC, no formato YYYY-MM-DD HH:MM:SS.

Autenticação

A maior parte da leitura é pública: os endpoints da secção "Endpoints públicos" não exigem autenticação. A escrita exige a API key do próprio logbook. Os endpoints de pesquisa e enumeração (pesquisa de indicativos, perfis de estação, listas de logbooks) exigem uma API key válida de qualquer logbook — ver "Leitura com API key". Em todos os casos a chave vai no cabeçalho X-API-Key.

X-API-Key: 3f9c…(64 caracteres hexadecimais)

A API key obtém-se no próprio logbook, em Gerir → API Keys (é preciso a password do logbook). Cada chave pertence a um único logbook, pode ter uma etiqueta (por exemplo "N1MM+" ou "LogBeam Uplink") e pode ser revogada a qualquer momento sem alterar a password.

Limites

Os limites são por endereço IP. Ao excedê-los a API responde 429 com o cabeçalho Retry-After (segundos). Os endpoints não listados têm um limite genérico de 120 pedidos por minuto.

Cada logbook aceita no máximo 25 000 QSOs. O parâmetro limit vai até 25 000 em /qsos, 100 em /instances e 200 em /search.

Além dos limites por IP há tectos globais por minuto, somando todos os clientes: 2000 pedidos no total, 600 em /instance/{id}/qsos, 300 em /search e em /instances/check, 20 criações de logbook. Acima deles a API responde 503 aos pedidos anónimos e continua a servir os que trazem uma API key válida ou vêm das páginas do LogBeam. É a protecção contra inundações distribuídas, em que um limite por IP não chega.

Endpoints públicos (leitura)

Sem autenticação. Devolvem apenas dados que já são públicos no site. Os caminhos são relativos à base https://api.logbeam.org/api.

GET /instance/{id}

{
  "status": "success", "message": "Success",
  "data": {
    "string_id": "d4405e6967", "callsign": "CT7BFV", "title": "CT7BFV - 2026 LogBook",
    "created_at": "2026-06-16 19:30:55",
    "home_lat": 40.1875, "home_lon": -8.375, "home_qth": "Coimbra, Portugal", "home_country": "Portugal",
    "operator_name": "Octávio Filipe Pereira Gonçalves", "grid_locator": "IN50TE", "itu_zone": 37, "cq_zone": 14,
    "has_password": true, "is_locked": false, "enriching": false, "pending_qsos": 0,
    "stats": {
      "total_qsos": 1190, "countries_worked": 97, "date_start": "2025-04-28", "date_end": "2026-06-18",
      "modes": { "CW": 232, "SSB": 958 }, "bands": { "10m": 86, "15m": 312, "20m": 663, "40m": 128, "80m": 1 },
      "max_distance_km": 19831, "farthest_qso": { "callsign": "ZL3SV", "country": "New Zealand" }
    },
    "sibling_logbooks": [ { "string_id": "8ba2e1f834", "title": "EUDX - CONTEST 2026", "created_at": "2026-07-19 17:58:49" } ]
  }
}

GET /instance/{id}/qsos

{
  "status": "success", "message": "Success",
  "data": {
    "instance": { "callsign": "CT7BFV", "title": "CT7BFV - 2026 LogBook" },
    "total": 1190, "limit": 2, "offset": 0, "enriching": false,
    "qsos": [
      {
        "id": 16666, "callsign": "F5RAG", "band": "20m", "mode": "SSB", "freq": 14.238,
        "date_time": "2026-06-18 22:10:51", "rst_sent": "59", "rst_received": "59",
        "confirmed_lotw": true, "confirmed_eqsl": false, "confirmed_logbeam": false,
        "qth": { "latitude": 48.86, "longitude": 2.36, "city": "PAU", "country": "France", "approximate": false }
      },
      { "id": 16665, "callsign": "S51DX", "band": "20m", "mode": "SSB", "freq": 14.31, "date_time": "2026-06-18 21:59:15", "…": "…" }
    ]
  }
}

qth.approximate = true indica coordenadas ao nível do país (o indicativo não foi encontrado no HamQTH). Enquanto enriching for true ainda há QSOs sem coordenadas a ser resolvidos em segundo plano.

GET /dxcc/resolve/{call}

{
  "status": "success", "message": "Success",
  "data": { "callsign": "CT7BFV",
            "entity": { "id": 86, "name": "Portugal", "prefix": "CT", "cq_zone": 14, "itu_zone": 37, "continent": "EU", "lat": "39.5000", "lon": "-8.0000", "deleted": 0 } }
}

GET /space-weather

{
  "status": "success", "message": "Success",
  "data": {
    "source": "N0NBH", "updated": "13 Sep 2026 1159 GMT",
    "sfi": 109, "a_index": 7, "k_index": 2, "sunspots": 77, "xray": "B4.2", "aurora": 2, "geomag_field": "QUIET", "signal_noise": "S1-S2",
    "band_conditions": [ { "band": "80m-40m", "time": "day", "condition": "Fair" }, { "band": "30m-20m", "time": "day", "condition": "Good" }, "…" ],
    "fetched_at": "2026-09-13 12:00:01"
  }
}

Endpoints com API key

Cabeçalho X-API-Key obrigatório em todos. São os endpoints que o LogBeam Uplink para Windows usa — qualquer software de logging pode fazer o mesmo.

Leitura com API key — pesquisa e enumeração

Estes endpoints aceitam a API key de qualquer logbook — não tem de ser o logbook consultado. A exigência não vem da confidencialidade dos dados, que são os mesmos que o site mostra, mas da necessidade de identificar quem consome a API em volume e de poder revogar o acesso em caso de abuso. Sem chave válida a resposta é 401.

As páginas do LogBeam (pesquisa de logs, perfil de operador, registo de QSOs) chamam estes endpoints com um token de curta duração emitido pela própria página, ligado à rede do visitante — por isso funcionam sem chave. Esse token não substitui a API key em software próprio.

GET /search?callsign=CT7BFV

{
  "status": "success", "message": "Success",
  "data": {
    "callsign": "CT7BFV", "found_in": 1,
    "results": [
      { "string_id": "327032a2b8", "callsign": "CT1FAC", "title": "Log_Geral",
        "qsos": [ { "band": "2m", "mode": "FM", "date_time": "2026-05-15 22:53:09" }, { "band": "10m", "mode": "SSB", "date_time": "2026-05-15 17:36:19" } ] }
    ]
  }
}

POST /instance/{id}/qso — registar um QSO em tempo real

Adiciona um QSO ao logbook. O servidor resolve a entidade DXCC, as coordenadas do correspondente (HamQTH, com fallback ao país) e a confirmação LogBeam-a-LogBeam. A resposta é imediata; o enriquecimento corre em segundo plano.

POST /api/instance/d4405e6967/qso
Content-Type: application/json
X-API-Key: 3f9c…

{ "callsign": "F5RAG", "band": "20m", "mode": "SSB", "freq": 14.238,
  "date_time": "2026-06-18 22:10:51", "rst_sent": "59", "rst_received": "59" }

Resposta 201 com o id do QSO. Se o QSO já existir (mesmo indicativo, banda, modo e minuto) a API devolve 200 com duplicate: true e não cria nada — pode reenviar sem medo.

HTTP 201  { "status": "success", "message": "Created", "data": { "qso_id": 16667, "callsign": "F5RAG", "confirmed_logbeam": false } }
HTTP 200  { "status": "success", "message": "Success", "data": { "duplicate": true, "message": "QSO já existe" } }
HTTP 401  { "status": "error", "message": "API Key ou password obrigatória" }
HTTP 400  { "status": "error", "message": "date_time inválido (use YYYY-MM-DD HH:MM:SS ou ISO 8601)" }

GET /instance/{id}/apikey/verify — verificar a API key

Confirma que a chave é válida para este logbook. Devolve apenas a confirmação e o indicativo — 401 se a chave for inválida ou estiver em falta. Use-o ao configurar o cliente.

HTTP 200  { "status": "success", "message": "Success", "data": { "valid": true, "callsign": "CT7BFV" } }
HTTP 401  { "status": "error", "message": "API Key inválida ou em falta" }

POST /instance/{id}/import/lotw · /import/eqsl — importar confirmações

Envie o ficheiro ADIF exportado do LoTW ou do eQSL como texto simples (Content-Type: text/plain). Os QSOs correspondentes (indicativo, banda, modo e data) ficam marcados como confirmados.

POST /api/instance/d4405e6967/import/lotw
Content-Type: text/plain
X-API-Key: 3f9c…

<ADIF_VER:5>3.1.4 … <EOH>
<CALL:5>F5RAG<BAND:3>20m<MODE:3>SSB<QSO_DATE:8>20260618<TIME_ON:4>2210<QSL_RCVD:1>Y<EOR>

Resposta: origem, total de registos no ficheiro, matched (QSOs confirmados) e skipped (sem correspondência no logbook).

HTTP 200  { "status": "success", "message": "Success", "data": { "source": "lotw", "total": 312, "matched": 297, "skipped": 15 } }

Erros

Todos os erros usam o mesmo envelope, com status "error" e uma mensagem legível:

{ "status": "error", "message": "Logbook não encontrado" }

Exemplos

Substitua {id} pelo identificador do logbook e {key} pela API key.

Metadados de um logbook

curl https://api.logbeam.org/api/instance/{id}

Os 100 QSOs mais recentes

curl "https://api.logbeam.org/api/instance/{id}/qsos?limit=100"

Registar um QSO

curl -X POST https://api.logbeam.org/api/instance/{id}/qso \
  -H "Content-Type: application/json" \
  -H "X-API-Key: {key}" \
  -d '{"callsign":"F5RAG","band":"20m","mode":"SSB","freq":14.238,"date_time":"2026-06-18 22:10:51","rst_sent":"59","rst_received":"59"}'

Verificar a API key

curl -H "X-API-Key: {key}" https://api.logbeam.org/api/instance/{id}/apikey/verify

Python

import requests

API = "https://api.logbeam.org/api"
LOGBOOK, KEY = "{id}", "{key}"

r = requests.post(f"{API}/instance/{LOGBOOK}/qso",
                  headers={"X-API-Key": KEY},
                  json={"callsign": "F5RAG", "band": "20m", "mode": "SSB",
                        "freq": 14.238, "date_time": "2026-06-18 22:10:51"},
                  timeout=15)
print(r.status_code, r.json())          # 201 {'status': 'success', 'message': 'Created', 'data': {...}}

Notas

Não documentados de propósito: criação e gestão de logbooks, passwords, credenciais LoTW/eQSL e administração. Essas operações fazem-se na interface web, com a password do logbook.

Esta é a mesma API que o site e o LogBeam Uplink usam; alterações incompatíveis serão anunciadas nesta página. Versão actual: 2.5.0.

Dúvidas, ou um cliente novo para partilhar? Contacte-nos.