API del log

Introduzione

L’API di PingDX permette a un membro di mantenere il proprio log PingDX sincronizzato con un altro programma di logging, uno script o il proprio sito web: scaricare i QSO, aggiungerne di nuovi, correggerli o eliminarli. Dà accesso solo al log del membro che ha creato la chiave.

Richieste e risposte sono in JSON (UTF-8). Invia Content-Type: application/json con ogni richiesta che ha un corpo. Le date sono stringhe ISO 8601; il server risponde sempre in UTC (2026-10-05T18:42:00.000Z).

Una descrizione leggibile da macchina (OpenAPI 3.1, pubblica, senza chiave) è disponibile per i generatori di codice e per strumenti come Postman: https://pingdx.org/api/v1/openapi.json

Ottenere una chiave

Ogni membro crea le proprie chiavi in Profilo → Accesso API. Dai a ogni chiave un nome (il programma o il sito che la usa) e scegli i suoi permessi:

• Sola lettura (READ): può leggere il log (richieste GET) — sufficiente per mostrare i tuoi QSO su un sito web.
• Lettura e scrittura (WRITE): può anche creare, aggiornare ed eliminare QSO — necessaria per una sincronizzazione bidirezionale con un programma di logging.
• La chiave completa viene mostrata una sola volta, subito dopo la creazione: copiala subito. PingDX ne conserva solo un’impronta e non può mostrarla di nuovo.
• Puoi revocare una chiave in qualsiasi momento: smette di funzionare immediatamente. Al massimo 10 chiavi attive per membro.

Autenticazione

Invia la chiave con ogni richiesta, nell’header Authorization (Bearer) oppure nell’header X-API-Key. La tua sessione di accesso a PingDX non è accettata da questa API e i cookie non vengono mai usati.

Authorization: Bearer pdx_…
# oppure
X-API-Key: pdx_…

Senza una chiave valida l’API risponde 401; una chiave READ che tenta di scrivere riceve 403:

• 401 API_KEYS.INVALIDChiave mancante, sconosciuta o revocata (o account non più attivo).
• 403 API_KEYS.READ_ONLYLa chiave è di sola lettura: crea una chiave WRITE per scrivere.

Endpoint

Tutti i percorsi sono relativi all’URL di base. Ogni QSO è identificato dal proprio clientId, un UUID scelto dal tuo programma.

{
  "callsign": "14KM001",
  "locator": "JN03ql",
  "scope": "WRITE"
}

{
  "items": [
    {
      "id": "cmgd4w1x70003s60e8k2v9qhz",
      "clientId": "0b9e6c1e-5f3a-4d2b-9c7e-1a2b3c4d5e6f",
      "band": "ELEVEN_METERS",
      "frequencyMhz": "27.555",
      "channel": null,
      "ctcssTone": null,
      "dcsCode": null,
      "mode": "USB",
      "callsignWorked": "14KM123",
      "operatorCallsign": "14KM001",
      "dxLocator": "JN18du",
      "dxLat": null,
      "dxLng": null,
      "txPowerW": 4,
      "myLocator": "JN03ql",
      "splitKhz": null,
      "path": null,
      "qsoStatus": null,
      "rstSent": "59",
      "rstReceived": "57",
      "qslSent": false,
      "qslReceived": false,
      "qslVia": null,
      "qsoAt": "2026-10-05T18:42:00.000Z",
      "notes": null,
      "radio": "President Lincoln II+",
      "antenna": "Sirio 827",
      "crossConfirmedAt": null,
      "spottedAt": null,
      "createdAt": "2026-10-05T18:43:10.512Z",
      "syncedAt": "2026-10-05T18:43:10.512Z"
    }
  ],
  "nextCursor": null,
  "serverTime": "2026-10-05T18:45:12.345Z"
}

{
  "items": [
    { "id": "cmgd4w1x70003s60e8k2v9qhz", "clientId": "0b9e6c1e-5f3a-4d2b-9c7e-1a2b3c4d5e6f" },
    { "id": "cmgd51b2c0007s60efq3m1abc", "clientId": "7d1f2a90-3b4c-4e5f-8a6b-9c0d1e2f3a4b" }
  ]
}

{
  "entries": [
    {
      "clientId": "0b9e6c1e-5f3a-4d2b-9c7e-1a2b3c4d5e6f",
      "band": "ELEVEN_METERS",
      "frequencyMhz": "27.555",
      "mode": "USB",
      "callsignWorked": "14KM123",
      "qsoAt": "2026-10-05T18:42:00Z",
      "rstSent": "59",
      "rstReceived": "57",
      "dxLocator": "JN18DU"
    },
    {
      "clientId": "7d1f2a90-3b4c-4e5f-8a6b-9c0d1e2f3a4b",
      "band": "PMR446",
      "channel": 8,
      "ctcssTone": "67.0",
      "mode": "FM",
      "callsignWorked": "PMR-ALPHA",
      "qsoAt": "2026-10-05T19:05:00+02:00",
      "dxLocator": "JN1"
    }
  ]
}

{
  "results": [
    { "clientId": "0b9e6c1e-5f3a-4d2b-9c7e-1a2b3c4d5e6f", "id": "cmgd4w1x70003s60e8k2v9qhz", "spottedAt": null },
    { "clientId": "7d1f2a90-3b4c-4e5f-8a6b-9c0d1e2f3a4b", "id": null, "error": "LOCATOR_INVALID", "permanent": true }
  ]
}

HTTP/1.1 204 No Content

L’oggetto QSO

Lo stesso oggetto viene inviato a POST /logs/batch e restituito da GET /logs. Il campo band seleziona una delle due varianti:

• 11 m (CB) — "band": "ELEVEN_METERS": frequencyMhz (facoltativo); channel, ctcssTone e dcsCode devono essere assenti o null.
• PMR446 — "band": "PMR446": channel (da 1 a 16) è obbligatorio, ctcssTone / dcsCode facoltativi; frequencyMhz deve essere assente o null.
• Un aggiornamento sostituisce il QSO: invia sempre il QSO completo. Un campo omesso viene reimpostato (vuoto, oppure false per qslSent / qslReceived), tranne operatorCallsign, dxLat, dxLng, txPowerW, radio e antenna, che mantengono il valore memorizzato se omessi.
• Il testo viene ripulito dagli spazi, i locator vengono normalizzati (jn18DU → JN18du) e i campi sconosciuti vengono ignorati. I campi di sola lettura sono impostati dal server: non serve inviarli.

• clientIdobbligatorio
  string (UUID)

  Il tuo id stabile per questo QSO: un UUID casuale (es. crypto.randomUUID()), generato una sola volta e memorizzato con il QSO nel tuo programma. È la chiave di sincronizzazione.

• bandobbligatorio
  "ELEVEN_METERS" | "PMR446"

  La banda: ELEVEN_METERS (11 m / CB) oppure PMR446.

• qsoAtobbligatorio
  string (ISO 8601)

  Data e ora del QSO, ISO 8601 con fuso orario (Z oppure +02:00). Memorizzato e restituito in UTC.

• frequencyMhzfacoltativo
  string "27.555" · 26.000–28.000

  Solo 11 m: la frequenza in MHz, come stringa con esattamente 3 decimali, tra 26.000 e 28.000.

• channelobbligatorio su PMR446
  integer 1–16

  Solo PMR446 (qui obbligatorio): il canale, da 1 a 16.

• ctcssTonefacoltativo
  string "67.0" · ^\d{2,3}\.\d$

  Solo PMR446: tono CTCSS in Hz, con un decimale (67.0, 103.5).

• dcsCodefacoltativo
  string "D023N" · ^D?[0-7]{3}[NI]?$

  Solo PMR446: codice DCS, 3 cifre ottali con prefisso D facoltativo e polarità N / I (D023N).

• modefacoltativo
  "FM" | "AM" | "SSB" | "USB" | "LSB" | "CW" | "DIGITAL"

  Il modo.

• callsignWorkedfacoltativo
  string ≤ 20

  L’indicativo della stazione collegata.

• operatorCallsignfacoltativo
  string ≤ 20

  Il tuo indicativo per questo QSO (utile se ne usi più di uno). Mantenuto se omesso in un aggiornamento.

• dxLocatorfacoltativo
  string "JN18" | "JN18du"

  Locator Maidenhead della stazione collegata, di 4 o 6 caratteri.

• dxLatfacoltativo
  number −90…90

  Latitudine esatta della stazione collegata, se nota. Le mappe la preferiscono al locator.

• dxLngfacoltativo
  number −180…180

  Longitudine esatta della stazione collegata, se nota.

• txPowerWfacoltativo
  integer 0–100000

  La tua potenza in trasmissione in watt interi.

• myLocatorfacoltativo
  string "JN03" | "JN03ql"

  Il tuo locator per questo QSO (es. in portatile), di 4 o 6 caratteri.

• splitKhzfacoltativo
  integer −99999…99999

  Split in kHz (differenza tra frequenza di trasmissione e di ricezione).

• pathfacoltativo
  "SP" | "LP"

  Percorso di propagazione: short path (SP) o long path (LP).

• qsoStatusfacoltativo
  "HRD" | "WKD" | "CFM"

  Stato del contatto: ascoltato (HRD), collegato (WKD), confermato (CFM).

• rstSentfacoltativo
  string ≤ 10

  Rapporto inviato (es. 59).

• rstReceivedfacoltativo
  string ≤ 10

  Rapporto ricevuto.

• qslSentfacoltativo
  boolean (false)

  QSL inviata. Predefinito: false.

• qslReceivedfacoltativo
  boolean (false)

  QSL ricevuta. Predefinito: false.

• qslViafacoltativo
  "DIRECT" | "BUREAU" | "EQSL" | "ECARD"

  Come ha viaggiato la QSL: DIRECT (posta), BUREAU, EQSL (eQSL.cc) oppure ECARD (altra cartolina elettronica).

• notesfacoltativo
  string ≤ 2000

  Note libere.

• radiofacoltativo
  string ≤ 80

  La radio utilizzata (testo libero).

• antennafacoltativo
  string ≤ 80

  L’antenna utilizzata (testo libero).

• sendSpotfacoltativo
  boolean

  Solo scrittura, mai restituito: true pubblica anche il QSO come spot sul cluster DX di PingDX (una sola volta per QSO). Solo per QSO in diretta, mai per l’importazione di quelli vecchi.

• idsola lettura
  string

  L’id del QSO sul server.

• crossConfirmedAtsola lettura
  string (ISO 8601) | null

  Impostato da PingDX quando l’altra stazione ha registrato lo stesso QSO su PingDX (conferma incrociata).

• spottedAtsola lettura
  string (ISO 8601) | null

  Quando il QSO è stato pubblicato come spot sul cluster, oppure null.

• createdAtsola lettura
  string (ISO 8601)

  Quando il QSO è stato salvato per la prima volta su PingDX.

• syncedAtsola lettura
  string (ISO 8601)

  Ultima scrittura lato server del QSO (determina l’ordine di GET /logs).

Guida alla sincronizzazione

Una sincronizzazione bidirezionale robusta tra il tuo programma e PingDX in sei passaggi:

1. 1

   Primo download completo

   Chiama GET /logs?limit=500 senza updatedSince, poi segui nextCursor finché non è null. Conserva il serverTime della prima pagina.

2. 2

   Download incrementale

   La volta successiva, chiama GET /logs?updatedSince=… con il serverTime salvato, segui le pagine allo stesso modo, poi salva il nuovo serverTime (sempre quello della prima pagina) solo dopo aver elaborato tutte le pagine. Ricevere due volte lo stesso QSO è innocuo: applicalo in base al clientId.

3. 3

   Invio dei tuoi QSO

   Assegna una volta per tutte a ogni QSO del tuo programma un clientId UUID e memorizzalo. Invia i QSO nuovi o modificati con POST /logs/batch, al massimo 200 per richiesta. Inviare di nuovo lo stesso QSO è sicuro: lo aggiorna invece di creare un duplicato.

4. 4

   QSO rifiutati

   Leggi ogni risultato: se id è null con permanent: true, mostra il QSO all’utente per la correzione (error ne spiega il motivo) invece di riprovare. Senza permanent, riprova più tardi.

5. 5

   Eliminazioni

   Per eliminare su PingDX: DELETE /logs/{clientId}. Per trovare i QSO eliminati su PingDX: GET /logs/ids, poi rimuovi dalla tua copia ogni QSO il cui clientId non è più elencato.

6. 6

   Conflitti

   Vince l’ultima scrittura, per clientId: non c’è unione campo per campo. L’app PingDX recepisce i QSO scritti tramite l’API alla sua sincronizzazione successiva (all’apertura, o entro pochi secondi se è online).

Errori e limiti

Gli errori usano il codice di stato HTTP e un corpo JSON con un codice stabile (mai un testo tradotto):

{ "error": { "code": "API_KEYS.READ_ONLY" } }

• 400 VALIDATION.FAILED

  Richiesta non valida: un parametro errato, un clientId che non è un UUID, o un batch senza un array entries valido (da 1 a 200). details descrive il problema.

• 401 API_KEYS.INVALID

  Chiave mancante, sconosciuta o revocata (o account non più attivo).

• 403 API_KEYS.READ_ONLY

  La chiave è di sola lettura: crea una chiave WRITE per scrivere.

• 404 GENERIC.NOT_FOUND

  Nessun QSO con questo clientId nel tuo log.

• 429 GENERIC.RATE_LIMITED

  Troppe richieste: attendi un po’ e riprova.

• 500 GENERIC.INTERNAL_ERROR

  Errore del server: riprova più tardi.

Motivi di rifiuto per singolo QSO

In POST /logs/batch, un QSO rifiutato ha id: null e un codice error:

• CLIENT_ID_INVALIDclientId non è un UUID valido.
• DATETIME_INVALIDqsoAt non è una data e ora ISO 8601 con fuso orario.
• LOCATOR_INVALIDdxLocator o myLocator non è un locator Maidenhead di 4 o 6 caratteri.
• FREQUENCY_FORMAT_INVALIDfrequencyMhz deve essere una stringa con 3 decimali (27.555).
• FREQUENCY_OUT_OF_BAND_11MfrequencyMhz è al di fuori di 26.000–28.000 MHz.
• CHANNEL_OUT_OF_RANGECanale PMR446 al di fuori di 1–16.
• CTCSS_FORMAT_INVALIDctcssTone deve avere la forma 67.0.
• DCS_FORMAT_INVALIDdcsCode deve avere la forma D023N.
• CLIENT_ID_CONFLICTQuesto clientId appartiene già al QSO di un altro membro: genera un nuovo UUID.

Altre violazioni dello schema (campo mancante, valore sconosciuto in un enum, testo troppo lungo…) restituiscono il messaggio del validatore in inglese, es. Invalid input: expected string, received undefined, sempre con permanent: true.

Limiti

• 300 richieste al minuto per indirizzo IP, oltre le quali 429 (l’header Retry-After indica quanto attendere). Raggruppa i QSO in batch invece di inviarli uno a uno.
• Al massimo 200 QSO per POST /logs/batch.
• Da 1 a 500 QSO per pagina di GET /logs (200 per impostazione predefinita).
• Al massimo 10 chiavi attive per membro.

Chiamata da un browser (CORS)

/api/v1 accetta richieste da qualsiasi origine (CORS), senza cookie né credenziali. Una pagina web può quindi chiamarla direttamente — ma solo con una chiave READ, poiché il codice di una pagina pubblica è visibile a tutti.

Esempi

Sostituisci pdx_… con la tua chiave. Questi esempi sono pronti da copiare; solo i commenti sono in inglese.

curl

# Who am I? (checks the key)
curl -H "Authorization: Bearer pdx_…" https://pingdx.org/api/v1/me

# Everything changed since my last sync
curl -H "Authorization: Bearer pdx_…" \
  "https://pingdx.org/api/v1/logs?updatedSince=2026-10-01T00:00:00Z&limit=500"

# Create or update a QSO (WRITE key)
curl -X POST -H "Authorization: Bearer pdx_…" \
  -H "Content-Type: application/json" \
  https://pingdx.org/api/v1/logs/batch \
  -d '{"entries":[{"clientId":"0b9e6c1e-5f3a-4d2b-9c7e-1a2b3c4d5e6f",
       "band":"ELEVEN_METERS","frequencyMhz":"27.555","mode":"USB",
       "callsignWorked":"14KM123","qsoAt":"2026-10-05T18:42:00Z",
       "rstSent":"59","rstReceived":"57"}]}'

# Delete it (no body, no Content-Type)
curl -X DELETE -H "Authorization: Bearer pdx_…" \
  https://pingdx.org/api/v1/logs/0b9e6c1e-5f3a-4d2b-9c7e-1a2b3c4d5e6f

JavaScript (fetch)

Funziona con Node.js 18+ e Deno. Tieni la chiave lato server (variabile d’ambiente).

const BASE = "https://pingdx.org/api/v1";
const KEY = process.env.PINGDX_API_KEY; // pdx_… — keep it server-side

async function call(method, path, body) {
  const res = await fetch(BASE + path, {
    method,
    headers: {
      Authorization: `Bearer ${KEY}`,
      ...(body ? { "Content-Type": "application/json" } : {}),
    },
    body: body ? JSON.stringify(body) : undefined,
  });
  if (res.status === 204) return null;
  const data = await res.json();
  if (!res.ok) throw new Error(`${res.status} ${data.error?.code}`);
  return data;
}

// Full download, page by page
async function pullAll(updatedSince) {
  const qsos = [];
  let cursor = null;
  let since = null;
  do {
    const q = new URLSearchParams({ limit: "500" });
    if (updatedSince) q.set("updatedSince", updatedSince);
    if (cursor) q.set("cursor", cursor);
    const page = await call("GET", `/logs?${q}`);
    since ??= page.serverTime; // keep the FIRST page's serverTime
    qsos.push(...page.items);
    cursor = page.nextCursor;
  } while (cursor);
  return { qsos, nextUpdatedSince: since };
}

// Push local QSOs (create or update by clientId)
const { results } = await call("POST", "/logs/batch", {
  entries: [{
    clientId: crypto.randomUUID(), // store it with your QSO, reuse it forever
    band: "PMR446", channel: 8, ctcssTone: "67.0", mode: "FM",
    callsignWorked: "PMR-ALPHA", qsoAt: new Date().toISOString(),
  }],
});
for (const r of results) if (r.id === null) console.warn(r.clientId, r.error, r.permanent);

Python (requests)

import os, uuid, requests

BASE = "https://pingdx.org/api/v1"
S = requests.Session()
S.headers["Authorization"] = f"Bearer {os.environ['PINGDX_API_KEY']}"  # pdx_…

def pull(updated_since=None):
    """Every QSO changed since updated_since (all of them if None)."""
    qsos, cursor, next_since = [], None, None
    while True:
        params = {"limit": 500}
        if updated_since:
            params["updatedSince"] = updated_since
        if cursor:
            params["cursor"] = cursor
        r = S.get(f"{BASE}/logs", params=params, timeout=30)
        r.raise_for_status()
        page = r.json()
        next_since = next_since or page["serverTime"]  # first page's serverTime
        qsos += page["items"]
        cursor = page["nextCursor"]
        if not cursor:
            return qsos, next_since

def push(entries):
    """Create or update up to 200 QSOs; returns the rejected ones."""
    r = S.post(f"{BASE}/logs/batch", json={"entries": entries}, timeout=30)
    r.raise_for_status()
    return [x for x in r.json()["results"] if x["id"] is None]

rejected = push([{
    "clientId": str(uuid.uuid4()),  # keep it with your QSO
    "band": "ELEVEN_METERS", "frequencyMhz": "27.555", "mode": "USB",
    "callsignWorked": "14KM123", "qsoAt": "2026-10-05T18:42:00Z",
}])

# Deleted on PingDX? Compare clientIds with your copy
server_ids = {x["clientId"] for x in S.get(f"{BASE}/logs/ids", timeout=30).json()["items"]}

Una domanda o un programma che vorresti collegare? Scrivici dalla pagina Contatti.