Un endpoint per servizio, con lo stesso nome che il servizio ha qui dentro: /contatto, /deduplica, /email, /telefono, /sito, /codicefiscale, /arricchimento. Ognuno accetta un elemento nel corpo della richiesta oppure una lista in elementi, fino a 500 per chiamata (100 per i siti, che vanno contattati uno a uno). La deduplica fa eccezione e vuole sempre una lista: confronta le anagrafiche fra loro. A parte stanno /suggerisci, l'autocomplete per i form (lavora a sessione mentre l'utente digita, non a lotti), e /credito, che dice quante elaborazioni restano e in che stato è ogni contatore, senza consumarne.

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}

Alla creazione puoi dare al token una scadenza facoltativa: passata quella data le richieste ricevono HTTP 401 con codice token_expired; senza scadenza il token vale finché non lo revochi. Puoi revocarlo o rigenerarlo in qualsiasi momento dalla tua area personale, dove vedi anche ultimo uso e numero di richieste servite. Una richiesta senza token o con token non valido restituisce HTTP 401.

Endpoint verifica contatto

Sistema il contatto intero: indirizzo secondo lo standard di recapito italiano, nominativo e — se la richiesta lo porta — il codice fiscale, che viene ripulito, completato se manca il solo carattere di controllo e confrontato con cognome, nome, sesso e data di nascita. Un contatto per volta, oppure fino a 500 in elementi: lo schema è lo stesso di tutti gli altri endpoint.

Il paese è facoltativo e si indica con nazione_iso2 (ISO 3166-1, per esempio IT o DE) oppure con nazione, scritto come capita: «Germania», «Germany», «Deutschland», «Repubblica federale di Germania», «UK», «Olanda». Se manca si presume Italia. Gli indirizzi esteri tornano con esito ESTERO e nella forma in uso nel paese: codice postale, abbreviazioni della via, maiuscole e nome della città come li scrive la posta di quel paese (Hauptstr. 5, Monaco di Baviera → Hauptstraße 5, MÜNCHEN), con la riga del paese; in più indirizzo_confronto, la forma con cui la deduplica riconosce la stessa via scritta in due modi. Non verifichiamo l'esistenza della via: fuori dall'Italia lavoriamo sulla forma, e lo diciamo. Con "esteri": "rileva" un record senza paese che non risulta in Italia viene riconosciuto come estero quando il testo lo dice chiaramente; il default dichiarati lascia estero solo chi lo dice. Il catalogo completo, con nome italiano breve e ufficiale, inglese e nella lingua del paese, è disponibile con GET /api/v1/nazioni e si può interrogare con ?q=Germania, ?q=Deutschland o ?q=DE.

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

Per il lotto, gli stessi campi dentro elementi; la risposta è { count, results: [ { id, result } ] } nello stesso ordine dell'invio.

curl -X POST https://radaraddress.it/api/v1/contatto \
  -H 'Authorization: Bearer IL_TUO_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"elementi":[{"id":"1","indirizzo":"via leopardi 4","localita":"milano"},
                   {"id":"2","indirizzo":"via roma 1","cap":"20121","codice_fiscale":"RSSMRA85M01H501Q"}]}'

Opzioni valide per l'intera chiamata: postal_form (forza anche normalizzato nella forma postale), preserva_originale (tiene il nome scritto dall'utente ed espone il canonico a parte), precisione 1–5 (default 3; oltre 3 il match è approssimato e l'affidabilità non sarà alta).

Insieme all'indirizzo torna localita_tipo, che dice se il recapito è in un capoluogo di provincia o in un comune della provincia — la differenza che serve a chi taglia una campagna per città. capoluogo è true, false oppure null quando non abbiamo elementi per dirlo — e in quel caso non tiriamo a indovinare.

→ { "localita_tipo": { "capoluogo": true, "label": "Capoluogo di provincia" } }

Tornano anche le coordinate in geo (latitudine e longitudine WGS84) e gli identificativi territoriali in territorio: codice ISTAT e codice catastale del comune, CAB, e l'identificativo nazionale della via. Il campo precisione dice a che livello siamo arrivati: civico quando il numero è georeferenziato, interpolato quando il numero esatto manca e il punto è stimato, via quando abbiamo il punto della strada, comune quando abbiamo solo il centro del comune. fonte vale anncsu oppure osm: in quel caso i dati sono © OpenStreetMap contributors, licenza ODbL, e l'attribuzione va riportata se li pubblichi. Nel CSV dei lavori in blocco sono le colonne latitudine, longitudine, precisione_geo, codice_istat e codice_catastale.

→ { "geo": { "lat": 45.4762711, "lon": 9.207104, "precisione": "civico", "fonte": "anncsu" },
  "territorio": { "istat": "015146", "catastale": "F205", "cab": "01600", "via_id": "1026700" } }

Endpoint deduplica

Riconosce i record riferiti alla stessa persona allo stesso recapito anche quando sono scritti in modo diverso: diminutivi ed equivalenze dei nomi (Dany ≈ Daniela), cognome e nome invertiti, abbreviazioni ("V. Roma" ≈ "Via Roma"), refusi di battitura. Il confronto degli indirizzi passa dal motore di normalizzazione: due grafie diverse della stessa via collassano sulla forma canonica prima del confronto. Massimo 500 contatti per chiamata (anagrafiche + riferimento); per liste più grandi usa il lavoro in blocco dall'area personale.

Rubriche. Un contatto della rubrica (Contatti di Apple, Google, Outlook: il modello vCard) ha più indirizzi, più telefoni e più email, ognuno con un'etichetta. L'endpoint li accetta così, senza tetto: indirizzi è un elenco di oggetti con tipo e i campi di sempre; telefoni ed emails sono elenchi in cui ogni elemento è il dato solo ("340 7491386") oppure {"tipo": "ufficio", "valore": "02 66710423"}, anche misti; i campi piatti di sempre restano validi e valgono come primo indirizzo e primo recapito. Due contatti sono la stessa persona se una qualunque coppia dei loro indirizzi coincide (l'ufficio dell'uno con l'unico indirizzo dell'altro), oppure se hanno lo stesso nominativo e un telefono o un'email in comune, in qualunque posizione e con qualunque etichetta. Il tipo non pesa sull'abbinamento: torna com'è arrivato, più tipo_norm nel vocabolario vCard (home, work, cell…), così l'app sa dove riscrivere. Un contatto è una elaborazione, quanti indirizzi e recapiti abbia.

curl -X POST https://radaraddress.it/api/v1/deduplica \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "anagrafiche": [
      { "id": "C1", "cognome": "Rossi", "nome": "Daniela",
        "indirizzo": "Via Leopardi 4", "cap": "20123", "localita": "Milano", "provincia": "MI" },
      { "id": "C2", "cognome": "Rossi", "nome": "Daniela",
        "indirizzo": "V. Leopardi 4", "cap": "20100", "localita": "milano", "provincia": "MI" }
    ]
  }'

La risposta raggruppa i doppioni in gruppi: ogni gruppo elenca gli id dei suoi membri, indica quale tenere (principale) e propone il record consolidato: il nominativo migliore e l'unione di indirizzi e recapiti (indirizzi, telefoni, emails), ognuno col tipo, con provenienza (da quali contatti viene) e deduplicato: la stessa via in due grafie è un indirizzo solo, lo stesso numero con due etichette un numero solo. I contatti senza corrispondenze sono in singoli, come oggetti {id, esito}: con esito DOPPIO_INTERNO il contatto non ha doppioni con altri ma ne ha al suo interno (indirizzo scritto due volte, numero ripetuto), e porta il suo record fuso. Riconosce la stessa via scritta in modi diversi ("V. Leopardi 4" ≈ "Via Giacomo Leopardi 4"), il CAP rimesso a posto in automatico e cognome e nome invertiti.

Endpoint codice fiscale

Tre azioni sul codice fiscale delle persone fisiche: genera dai dati anagrafici, valida un codice esistente (formato, carattere di controllo e omocodia), estrai le informazioni contenute — data di nascita, età, sesso, comune o stato estero di nascita. In più confronta verifica che un CF corrisponda ai dati anagrafici dichiarati. Copre i codici catastali di tutti i comuni italiani e degli stati esteri. Cognome e nome vanno passati in caratteri latini: per chi ha un nome in un altro alfabeto, il codice si calcola sulla traslitterazione riportata sul documento, che non è unica (Dmitrij/Dmitry); un nome non latino torna cognome_non_latino o nome_non_latino, e nel confronta una differenza sul nominativo di chi è nato all'estero porta una nota sulla possibile traslitterazione diversa.

Le prime 500 elaborazioni leggere al mese sono gratuite (codice fiscale compreso), e la franchigia è una sola in ogni modalità di utilizzo: quello che fai qui, sul sito e nei file in blocco conta sullo stesso plafond. Oltre le mille, si paga il prezzo delle operazioni leggere (vedi prezzi).

curl -X POST https://radaraddress.it/api/v1/codicefiscale \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "azione": "genera",
    "cognome": "Rossi", "nome": "Mario", "sesso": "M",
    "data_nascita": "1980-01-01", "comune_nascita": "Roma"
  }'

→ { "ok": true, "codice_fiscale": "RSSMRA80A01H501U", "luogo": "Roma", "provincia": "RM" }

Per i volumi: { "azione": "valida", "elementi": [ … ] } processa fino a 500 elementi per chiamata, ognuno col proprio id di correlazione. L'estrazione segnala con anno_ambiguo i casi in cui le due cifre dell'anno non distinguono il secolo (1926 vs 2026).

Endpoint arricchimento

Arricchisce un nominativo: sesso dedotto dal nome, tipo di soggetto (persona fisica o giuridica), titolo normalizzato (Dott.ssa, Avv., …) e forme di saluto pronte per la corrispondenza — "Egregio Sig. Rossi", "Gentile Dott.ssa Bianchi", "Spett.le" per le aziende, "Gentile Famiglia" per i nuclei, "Caro/Cara" per l'informale. Riconosce anche la forma coniugale nel cognome ("Rossi in Verdi" → donna, con il dettaglio dei due cognomi). Il campo sesso accetta anche le forme scritte («maschio», «donna», «Sig.ra», «male»); X indica un ente e G una famiglia o una coppia. Se il titolo manca, lo ricaviamo da qualifica (la professione) o da titolo_studio, quando ne danno uno.

curl -X POST https://radaraddress.it/api/v1/arricchimento \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "cognome": "Rossi", "nome": "Dott.ssa Maria" }'

→ { "ok": true, "sesso": "F", "tipo_soggetto": "fisica", "titolo": "Dott.ssa",
    "saluto_formale": "Gentile Dott.ssa Rossi", "saluto_informale": "Cara Maria", … }

A lotti: { "elementi": [ … ] }, fino a 500 per chiamata.

Endpoint verifica email

Verifica un indirizzo email: sintassi, esistenza del dominio (record MX/A), refusi dei domini comuni con correzione proposta (gmial.com → gmail.com), domini usa-e-getta, indirizzi generici (info@, amministrazione@: non di una persona). Non facciamo la verifica SMTP della singola casella, pratica invasiva e inaffidabile. Batch elementi fino a 500; "dns": false salta il lookup del dominio.

Endpoint verifica telefono

Controlla un numero senza chiamare nessuno: forma, classe e tipo, lunghezza secondo il piano di numerazione, distretto del fisso e operatore a cui il blocco è stato assegnato in origine. La classe è la lettura che serve a lavorare una lista: mobile (ci mandi un SMS), fisso (lo chiami in orario d'ufficio), speciale (non è il recapito di una persona: emergenze, pubblica utilità, numeri verdi e a tariffa maggiorata), estero per i numeri con prefisso internazionale. Quando riconosciamo anche il servizio preciso, tipo lo dice (numero verde, tariffa speciale, costo ripartito, pubblica utilità). Il prefisso italiano scritto senza il + (39347…, refuso classico degli export) lo togliamo quando le cifre non lasciano dubbi — 3934567890 resta il cellulare che è. Se nello stesso campo ci sono più numeri («347… - 338…») li separiamo: tornano come telefono, telefono2, telefono3, e telefono non è mai vuoto quando almeno un numero c'è. Con "formato": "internazionale" il numero italiano esce in forma +39…; il valore predefinito nazionale lo lascia nudo e mette il prefisso solo agli esteri. Per gli esteri torna anche formato_e164, il paese del prefisso in nazione_iso2 e lo zero di rete dopo il prefisso viene tolto («+44 (0)20…» e «+44 20…» danno lo stesso numero). Con nazione_iso2 (o nazione) nella chiamata o nell'elemento, un numero scritto senza prefisso è letto come numero nazionale di quel paese: «020 7946 0958» in una scheda del Regno Unito è Londra, non Milano. Senza paese resta italiano. Lotto elementi fino a 500.

curl -X POST https://radaraddress.it/api/v1/telefono \
  -H 'Authorization: Bearer IL_TUO_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"telefono":"3470328959 - 011 1253265"}'

Endpoint verifica sito web

Verifica che l'indirizzo sia scritto bene e che il sito risponda davvero: esistenza del dominio, richiesta HTTP con i reindirizzamenti seguiti, codice finale, validità del certificato. Nessun giudizio sul contenuto. Anche qui più indirizzi nello stesso campo tornano come sito, sito2, sito3. Con "rete": false controlliamo solo la forma, senza contattare il sito. Lotto elementi fino a 100: ogni verifica apre una connessione, quindi il lotto è più piccolo degli altri endpoint.

curl -X POST https://radaraddress.it/api/v1/sito \
  -H 'Authorization: Bearer IL_TUO_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"sito":"www.esempio.it"}'

Endpoint autocomplete indirizzo

Se parti da zero: come aggiungere l'autocomplete degli indirizzi al tuo form, in tre pezzi.

Suggerimenti mentre l'utente digita un indirizzo nel tuo form: l'intero stradario nazionale, con nome completato («via verdi» → «Via Giuseppe Verdi»), comune, provincia e CAP — nelle grandi città zonate il CAP giusto del civico. Funziona a sessione: il client genera un UUID per ogni indirizzo in compilazione, le query di suggerimento sono gratuite, e si paga una sola operazione leggera quando l'utente seleziona e i campi si riempiono (azione seleziona, che restituisce il record già normalizzato dal motore). I campi già compilati nel form — anche in parte — viaggiano come contesto e stringono i suggerimenti.

curl -X POST https://radaraddress.it/api/v1/suggerisci \
  -H 'Authorization: Bearer IL_TUO_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"sessione":"UUID-DEL-CLIENT","q":"via verdi","localita":"monz"}'

# alla scelta dell'utente: chiude la sessione e addebita la selezione
curl -X POST https://radaraddress.it/api/v1/suggerisci \
  -H 'Authorization: Bearer IL_TUO_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"sessione":"UUID-DEL-CLIENT","azione":"seleziona","via_id":1063428,"civico":"4"}'

Scelta la via, si completa il civico: passando via_id con il civico parziale si ottengono i civici esistenti di quella via, con esiste vero/falso per validare quello digitato — e la selezione si può ripetere con il civico senza nuovo addebito: l'addebito è a sessione, non a click. Nelle città zonate è il civico che determina il CAP esatto.

Il token API non va mai nel browser: il widget pronto all'uso (ra-suggerisci.js) chiama un piccolo proxy sul tuo server, che aggiunge il token e inoltra. Ogni sessione ammette fino a 30 query e vale 10 minuti.

nazione_iso2 (o nazione) è facoltativo: se manca si presume IT. Il catalogo dei suggerimenti è italiano; per un paese estero valido la risposta resta HTTP 200 con supportato:false e suggerimenti:[], senza creare la sessione né addebitare nulla, così il form può continuare con la compilazione manuale.

Volumi grossi: il lavoro asincrono

Le chiamate normali rispondono subito, e per questo hanno un tetto di elementi — una richiesta HTTP che dura minuti non serve a nessuno. I tetti seguono quanto costa l'operazione:

Oltre quei numeri non serve spezzare la lista a mano: si aggiunge "asincrono": true e la chiamata torna subito con un codice, mentre l'elaborazione va nella stessa coda del caricamento file. Fino a 100.000 elementi per chiamata, e in I miei lavori ne compare uno solo.

curl -X POST https://radaraddress.it/api/v1/contatto \
  -H 'Authorization: Bearer IL_TUO_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"asincrono":true,"elementi":[ … 100.000 contatti … ]}'

{"ok":true,"lavoro":"369e46e9e7bb…","stato":"in_coda","righe":100000}

Poi si rilegge quando serve, e il risultato arriva in JSON o come CSV:

curl 'https://radaraddress.it/api/v1/contatto?lavoro=369e46e9e7bb…' \
  -H 'Authorization: Bearer IL_TUO_TOKEN'

{"ok":true,"stato":"completato","righe":100000,"fatte":100000,
 "esiti":{"ok":1240,"modificati":95300,"da_controllare":2100,"non_risolti":1360}}

curl 'https://radaraddress.it/api/v1/contatto?lavoro=369e46e9e7bb…&formato=csv' \
  -H 'Authorization: Bearer IL_TUO_TOKEN' -o risultato.csv

Sotto le 5.000 righe il risultato torna anche in results dentro il JSON; sopra, si scarica in CSV. L'addebito avviene quando il lavoro viene accodato, e la parte non elaborata torna nel saldo se il lavoro si ferma. Il token dev'essere legato a un account: il lavoro finisce nella tua coda.

Codici di esito

Ogni risposta include il campo esito: una lista di parole chiave, vuota quando non c'è niente da segnalare. Lo schema è sempre <condizioni> [MODIFICATO <tipi>] — le condizioni davanti, le modifiche in coda — e vale per tutti i servizi. Accanto trovi esito_label (o kind) con ok, modified, warning, error, e motivo con la spiegazione in una riga.

Indirizzo (verifica contatto)

Codice fiscale

Sull'endpoint /codicefiscale gli stessi controlli hanno codici propri — CF_CONTROLLO_ERRATO, CF_CONTROLLO_MANCANTE, CF_LUNGHEZZA_ERRATA, CF_FORMATO_ERRATO, CF_MESE_ERRATO, CF_DATA_INESISTENTE, CF_COMUNE_SCONOSCIUTO, CF_VUOTO — perché lì il codice fiscale è l'oggetto della verifica, non un campo del record.

Email

Telefono

Sito web

Quanto costa ogni chiamata

Ogni chiamata consuma elaborazioni del contatore del servizio: verifica contatto (/contatto, /suggerisci alla selezione), deduplica (/deduplica) ed elaborazioni leggere (/email, /telefono, /sito, /arricchimento, /codicefiscale oltre la franchigia). Le elaborazioni si comprano a pacchetti che restano, o con un abbonamento mensile; il prezzo per 1.000 scende con la taglia ed è nella pagina prezzi. Ogni mese sono gratuite 50 verifiche contatto, 100 anagrafiche in deduplica e 500 elaborazioni leggere.

Ogni risposta dice che cosa ha consumato e da dove: il campo credito del JSON (contatore, consumate, gratuite, abbonamento e pacchetti con le elaborazioni prelevate e il residuo, disponibili, auto_ricarica con il numero di pacchetti comprati in automatico, nota in italiano) e gli header X-RA-Addebito, X-RA-Disponibili e, quando interviene, X-RA-Auto-Ricarica. Se le elaborazioni disponibili non coprono la chiamata e l'auto-ricarica del contatore non è attiva (o non riesce), la risposta è 402 payment_required e non viene elaborato nulla.

Per sapere quante elaborazioni restano senza consumarne nessuna c'è GET /api/v1/credito. Per ciascuno dei tre contatori (contatto, deduplica, leggere) restituisce disponibili, le gratuite rimaste nel mese e la data in cui si azzerano (il 1°), l'abbonamento (residuo, taglia, rinnovo), i pacchetti attivi uno per uno con quanto resta (non scadono) e quanti ne hai comprati, l'auto_ricarica (attiva, taglia, tetto e speso del mese in euro), l'uso (usate nel mese, totali, ultimo uso) e soprattutto lo stato, perché uno zero da solo non dice se hai esaurito o se quel servizio non lo usi: mai_usato, gratuite (mai comprato, lavori nelle gratuite del mese), gratuite_esaurite, attivo, in_attesa_del_rinnovo, esaurito (hai comprato in passato e non resta nulla: va ricaricato), con un avviso in italiano. In cima da_ricaricare elenca i contatori su cui intervenire ed endpoint dice quale contatore consuma ogni endpoint. Vuole il token di un account.

curl https://radaraddress.it/api/v1/credito -H 'Authorization: Bearer IL_TUO_TOKEN'
→ { "ok": true, "contatori": { "contatto": { "disponibili": 48250, "gratuite": { "rimaste": 50, "mese": 50 },
      "abbonamento": { "residuo": 23200, "taglia": 25000, "si_rinnova_il": "2026-10-03" }, "pacchetti": { "residuo": 25000, "attivi": [ … ] },
      "stato": "attivo", "avviso": "" }, "deduplica": { "stato": "mai_usato", "avviso": "Contatore mai usato: lo zero non è un esaurimento. …", … },
      "leggere": { … } }, "da_ricaricare": [], "endpoint": { "contatto": "contatto", "email": "leggere", … } }

Si paga per elemento verificato, non per chiamata: se in un campo ci sono due numeri di telefono o due email, li verifichiamo tutti (fino a tre per riga) e ciascuno paga il suo prezzo. Una chiamata a lotto costa quanto le operazioni che contiene. Se il credito è esaurito e non hai l'auto-ricarica attiva, l'API risponde HTTP 402 (credito insufficiente); superato il rate limit risponde HTTP 429 con retry_after. Ricarichi il credito dall'area personale, o attivi un abbonamento per pagare meno l'operazione.