Le API di RadarAddress ti permettono di normalizzare indirizzi italiani in tempo reale, direttamente dai tuoi sistemi. Puoi verificare un singolo indirizzo o inviare fino a 500 record per chiamata con l'endpoint batch.

Autenticazione

L'accesso alle API avviene tramite token Bearer. Dopo la registrazione, genera il tuo token dall'area personale e includilo nell'header di ogni richiesta nel formato:

# Tutte le richieste richiedono l'header Authorization
Authorization: Bearer {il-tuo-token}

Il token non ha scadenza automatica. Puoi revocarlo o rigenerarlo in qualsiasi momento dalla tua area personale. Una richiesta senza token o con token non valido restituisce HTTP 401.

Endpoint singolo

Accetta una richiesta POST con un oggetto JSON contenente i campi dell'indirizzo e restituisce l'indirizzo normalizzato, il codice di esito e il dettaglio delle modifiche applicate.

Campi accettati in input

Esempio di richiesta

curl -X POST https://radaraddress.it/api/v1/normalizza \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "indirizzo": "via leopardi 4",
    "cap": "20100",
    "localita": "milano",
    "provincia": "mi"
  }'

Esempio di risposta

{
  "trovato": true,
  "esito": "MODIFICATO CAP LOCALITA_NORM PROVINCIA INDIRIZZO",
  "esito_label": {
    "kind": "modified",
    "title": "Indirizzo normalizzato",
    "message": "Abbiamo normalizzato l'indirizzo secondo gli standard di Poste Italiane."
  },
  // forma comunale (CRM): accenti UTF-8, frazione tenuta in località
  "normalizzato": {
    "indirizzo": "Via Giacomo Leopardi 4",
    "cap": "20123", "localita": "MILANO", "provincia": "MI",
    "presso": "", "edificio": ""
  },
  // forma postale (busta): apostrofo al posto dell'accento
  "normalizzato_postale": {
    "indirizzo": "Via Giacomo Leopardi 4",
    "cap": "20123", "localita": "MILANO", "provincia": "MI",
    "presso": "", "edificio": ""
  },
  "comune": "MILANO",
  "confidenza": "alta",
  "note": null,
  "indirizzo_canonico": null,
  "localita_canonica": null,
  "modifiche": [
    { "campo": "indirizzo", "prima": "via leopardi 4", "dopo": "Via Giacomo Leopardi 4" },
    { "campo": "cap", "prima": "20100", "dopo": "20123" }
  ],
  "civico": { "numero": "4", "esponente": null },
  "toponimo": { "dug": "Via", "duf": "Giacomo Leopardi" },
  "multicap": true,
  "zonato": true
}

Campi della risposta

Endpoint batch

Accetta un array JSON di oggetti indirizzo, fino a un massimo di 500 elementi per chiamata. La risposta è un array con lo stesso numero di elementi: ogni oggetto contiene l'indirizzo normalizzato e il relativo codice di esito, nell'ordine in cui sono stati inviati.

curl -X POST https://radaraddress.it/api/v1/batch \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "indirizzi": [
      { "id": "A1", "indirizzo": "via leopardi 4", "localita": "milano" },
      { "id": "A2", "indirizzo": "piazza navona",  "localita": "roma" }
    ]
  }'

Ogni elemento dell'array di risposta riporta lo stesso id opzionale ricevuto in input, così puoi correlare facilmente le righe.

Codici di esito

Ogni risposta include il campo esito con uno dei seguenti codici, che indicano il risultato della normalizzazione:

Limiti e quota

Ogni account ha una quota mensile di chiamate inclusa nel piano sottoscritto (vedi prezzi). L'endpoint singolo conta 1 chiamata per richiesta; l'endpoint batch conta tante chiamate quanti sono i record inviati. Se superi la quota, l'API restituisce HTTP 429 con il campo retry_after che indica quando la quota verrà rinnovata. Per aumentare i limiti contatta il supporto.