Lo stesso motore,
dentro la tua app.

Un endpoint per servizio, con lo stesso nome che il servizio ha qui dentro: /contact, /dedupe, /email, /phone, /website, /tax-code, /enrichment. Ognuno accetta un elemento nel corpo della richiesta oppure una lista in items, 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 /suggest, l'autocomplete per i form (lavora a sessione mentre l'utente digita, non a lotti), e /credit, che dice quante elaborazioni restano e in che stato è ogni contatore, senza consumarne.

Autenticazione

L'host dell'API è www.radaraddress.com. I nomi dei campi, degli endpoint e dei valori sono identificativi inglesi, uguali in ogni lingua; le etichette, i motivi e i messaggi seguono la lingua della richiesta ("language": "de" o ?language=de, oppure l'header Accept-Language, oppure la lingua dell'account). L'header Content-Language dice in che lingua è arrivata la risposta.

L'accesso alle API avviene tramite token Bearer. L'account è gratuito: crei il token dall'area personale e lo includi nell'header di ogni richiesta nel formato:

# Every request needs the Authorization header
Authorization: Bearer {your-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.

I nomi italiani, per chi li usa già

L'API ha una versione sola, in inglese. Chi integrava con i nomi italiani non deve cambiare niente: i campi italiani sono accettati in ogni richiesta, gli endpoint rispondono anche col nome italiano (/contatto, /deduplica, /codicefiscale, /arricchimento, /telefono, /sito, /suggerisci, /nazioni, /credito), e la risposta esce con le chiavi e i codici italiani a chi lo chiede con "language": "it" o chiama www.radaraddress.it senza indicare la lingua.

La tabella completa dei campi: inglese → italiano

inglese	italiano	inglese	italiano
account	account	members	membri
action	azione	method	metodo
activated_on	attivato_il	metric	metrico
active	attiva	min_level	livello_minimo
active_packs	attivi	missing	mancano
address	indirizzo	modified	modificati
address_key	indirizzo_confronto	month	mese
addresses	indirizzi	monthly_cap_eur	tetto_mese_eur
after	dopo	multiple_postcodes	multicap
age	eta	municipality	comune
agreement	consenso	municipality_code	comune_codice
ambiguous_year	anno_ambiguo	municipality_code_type	comune_codice_tipo
area	area	n_records	n_anagrafiche
async	asincrono	name_id	nome_id
auto_topup	auto_ricarica	name_original	nome_originale
available	disponibile	national_number	nazionale
before	prima	nearby	vicino
belfiore_code	codice_belfiore	needed	necessarie
birth_country	nazione_nascita	needs_topup	da_ricaricare
birth_date	data_nascita	network	rete
birth_place	comune_nascita	normalized	normalizzato
birth_place_name	luogo_nascita	normalized_postal	normalizzato_postale
birth_province	provincia_nascita	not_found	non_trovati
born_abroad	nato_estero	note	nota
bought	comprati	notes	note
building	edificio	number	numero
cadastral_code	catastale	numbers	numeri
canonical_address	indirizzo_canonico	occurrences	occorrenze
canonical_city	localita_canonica	operations	elaborazioni
care_of	presso	operator	operatore
certificate_ok	certificato_ok	origin	origine
changed	modificato	other	altro
changes	modifiche	outcome	esito
charged	consumate	outcome_label	esito_label
check	controlla	outcomes	esiti
check_digit	controllo	overall_cap_eur	tetto_globale_eur
city	localita	packs	pacchetti
city_key	localita_confronto	parsed	letto
city_passes	cicli_localita	phase	fase
city_type	localita_tipo	phone	telefono
class	classe	phone2	telefono2
code	codice	phone3	telefono3
colour	colore	phones	telefoni
comments	commenti	place	luogo
conditions	condizioni	position	posizione
confidence	confidenza	postcode	cap
confirmed	confermato	postcode_check	cap_verifica
consolidate	consolida	precision	precisione
contact	contatto	preserve_original	preserva_originale
contact_person	referente	presumed	presunto
corrected_from	corretta_da	processed	lavorato
counter	contatore	processed_at	datalav
counters	contatori	profession	qualifica
countries	nazioni	provenance	provenienza
country	nazione	province	provincia
country_code	nazione_iso2	provincial_capital	capoluogo
country_original	nazione_originale	reachable	raggiungibile
country_prefix	prefisso_paese	reason	motivo
created	creato	record_outcome	esito_record
credit	credito	records	anagrafiche
dedupe	deduplica	redirects	redirect
detail	dettaglio	reference	riferimento
differences	differenze	reference_id	riferimento_id
discarded	scartati	remaining	rimaste
disposable	usa_e_getta	renews_on	si_rinnova_il
district	quartiere	reset_on	si_azzerano_il
domain_checked	dominio_verificato	rows	righe
domain_exists	dominio_esiste	salutation	saluto
done	fatte	save	salva
duration_ms	durata_ms	segment_passes	cicli_arcostradale
e164	formato_e164	session	sessione
education	titolo_studio	short	breve
entries	schede	singles	singoli
error	errore	size	taglia
exists	esiste	source	fonte
expiry	scadenza	specificity	specificita
explanations	spiegazioni	spent_month_eur	speso_mese_eur
extension	estensione	spent_overall_month_eur	speso_globale_mese_eur
field	campo	state	stato
final_url	url_finale	states	stati
first_name	nome	street	strada
foreign	esteri	street_id	via_id
foreign_address	estero	street_name	toponimo
formal_salutation	saluto_formale	street_passes	cicli_toponimo
format	formato	street_proper_name	duf
found	trovato	street_type	dug
free	gratuite	sub_address	subindirizzo
free_forever	gratis_per_sempre	sub_address_confirmed	subindirizzo_confermato
full_name	nominativo	subject_type	tipo_soggetto
gender	sesso	subscription	abbonamento
gender_source	fonte_sesso	suffix	esponente
generic	generica	suggestion	suggerimento
group	gruppo	summary	riepilogo
groups	gruppi	supported	supportato
hamlet	frazione	syntax	sintassi
hints	suggerimenti	tax_code	codice_fiscale
homocode	omocodo	tax_code_outcome	codice_fiscale_esito
house_number	civico	territory	territorio
house_number_label	civico_label	text	testo
house_number_verified	civico_verificato	time_ms	tempo_ms
house_numbers	civici	title	titolo
informal_salutation	saluto_informale	to_check	da_controllare
iso2	codice_iso2	total	totali
iso3	codice_iso3	town	citta
istat_code	istat	truncated	troncato
items	elementi	type	tipo
job	lavoro	type_normalized	tipo_norm
language	lingua	types	tipi
languages	lingue	unresolved	non_risolti
last_name	cognome	url_normalized	url_normalizzato
last_on	ultimo_il	used	usate
last_used	ultimo_uso	valid	valida
left	residuo	value	valore
legacy_default	default_storico	warning	avviso
level	livello	warnings	avvisi
light	leggere	website	sito
long	lungo	website2	sito2
long_name	nome_esteso	website3	sito3
main_record	principale	websites	siti
match	corrisponde	zoned	zonato
matches	abbinamenti

Anche i valori delle opzioni hanno il nome italiano: format nazionale/internazionale, action genera/valida/estrai/confronta/seleziona, foreign dichiarati/rileva, min_level certo/probabile/ambiguo; con "language": "it" escono così anche level, confidence, state, i codici di outcome e le intestazioni dei file. In ingresso sono accettati anche sinonimi comuni (zip, surname, phone_number, date_of_birth…) e le stesse intestazioni nei file dei lavori in blocco.

Endpoint verifica contatto

Sistema il contatto intero: indirizzo secondo lo standard postale della sua nazione — in Italia e nelle nazioni col registro in servizio via e civico sono verificati nel registro nazionale degli indirizzi, nelle altre l'indirizzo esce nella forma postale del paese —, 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 items: lo schema è lo stesso di tutti gli altri endpoint.

La nazione si indica con country_code (ISO 3166-1: IT, DE, FR…) oppure con country, scritto come capita: «Germania», «Germany», «Deutschland», «Repubblica federale di Germania», «UK», «Olanda». Se manca si presume Italia. Nelle nazioni col registro in servizio — oggi Francia, Germania, Spagna, Paesi Bassi, Belgio, Finlandia, Cechia, Portogallo, Danimarca, Norvegia, Austria, Svizzera, Slovacchia, Croazia, Romania, Ungheria, Slovenia, Irlanda, Islanda, Lussemburgo, Liechtenstein, San Marino, Monaco, Andorra, Città del Vaticano, l'elenco aggiornato è in Nazioni — via e civico vengono verificati nel registro nazionale degli indirizzi come in Italia: codice postale confermato o completato, coordinate del civico in geo, quartiere o arrondissement in district dove la città ne ha (Hamburg-Altstadt, Paris 4e Arrondissement), codice del comune in territory.municipality_code. Con la lingua italiana l'esito porta FOREIGN seguito dalle modifiche, nelle altre lingue solo le modifiche; se la via c'è e il numero no, HOUSE_NUMBER_NOT_FOUND. Nelle altre nazioni lavoriamo sulla forma, e il messaggio lo dice: codice postale nel formato del paese, abbreviazioni della via sciolte, maiuscole e nome della città come li scrive la posta di quella nazione (Hauptstr. 5, Monaco di Baviera → Hauptstraße 5, MÜNCHEN), con la riga della nazione. In entrambi i casi torna address_key, la forma con cui la deduplica riconosce la stessa via scritta in due modi. Con "foreign": "detect" un record senza nazione che non risulta in Italia viene riconosciuto come estero quando il testo lo dice chiaramente; il default declared lascia estero solo chi lo dice. Il catalogo completo delle nazioni, con nome breve e ufficiale, inglese e nella lingua della nazione, è disponibile con GET /api/v1/countries e si può interrogare con ?q=Germania, ?q=Deutschland o ?q=DE.

curl -X POST https://www.radaraddress.com/api/v1/contact \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"address":"via leopardi 4","postcode":"20100","city":"milano","province":"mi","id":"RIF-001"}'

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

curl -X POST https://www.radaraddress.com/api/v1/contact \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"items":[{"id":"1","address":"via leopardi 4","city":"milano"},
                   {"id":"2","address":"via roma 1","postcode":"20121","tax_code":"RSSMRA85M01H501Q"}]}'

Lo stesso endpoint per un indirizzo di un'altra nazione: basta country_code. Qui Amburgo, verificata nel registro tedesco, col quartiere e le coordinate del civico.

curl -X POST https://www.radaraddress.com/api/v1/contact \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"address":"Mönckebergstr. 7","postcode":"20095","city":"Hamburg","country_code":"DE"}'
→ { "outcome": "FOREIGN MODIFIED CITY_FORM STREET_FORM",
  "normalized": { "address": "Mönckebergstraße 7", "postcode": "20095", "city": "HAMBURG", "country": "Germany", "country_code": "DE" },
  "municipality": "Hamburg", "district": "Hamburg-Altstadt", "address_key": "MONCKEBERGSTRASSE",
  "geo": { "lat": 53.5512437, "lon": 10.0028651, "precision": "house_number", "source": "inspire" },
  "territory": { "country": "DE", "municipality_code": "AdminUnitName_49021011010101", "municipality_code_type": "inspire" } }

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

Insieme all'indirizzo torna city_type, 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à. provincial_capital è true, false oppure null quando non abbiamo elementi per dirlo — e in quel caso non tiriamo a indovinare.

→ { "city_type": { "provincial_capital": true, "label": "Provincial capital" } }

Accanto al CAP torna postcode_check: da dove viene (source) e con che precisione (precision: house_number il numero stesso, interpolated i numeri vicini della stessa via, street la maggioranza della via, locality, municipality), quanti civici lo dicono (house_numbers) e con che accordo (agreement, da 0 a 1). Quando manca un riscontro per quel numero l'esito porta POSTCODE_UNCONFIRMED e confirmed è false: il CAP resta quello indicato, se è fra quelli della città, e va controllato.

→ { "postcode_check": { "source": "osm", "precision": "house_number", "house_numbers": 3, "agreement": 1, "confirmed": true } }

Tornano anche le coordinate in geo (latitudine e longitudine WGS84) e gli identificativi territoriali in territory: in Italia codice ISTAT e codice catastale del comune, CAB e identificativo nazionale della via; nelle altre nazioni country e il codice del comune nel registro nazionale (municipality_code). Il campo precision dice a che livello siamo arrivati: house_number quando il numero è georeferenziato, interpolated quando il numero esatto manca e il punto è stimato, street quando abbiamo il punto della strada, municipality quando abbiamo solo il centro del comune. source dice da dove viene il punto: anncsu è il registro nazionale italiano, inspire il registro nazionale della nazione, osm OpenStreetMap: in quel caso i dati sono © OpenStreetMap contributors, licenza ODbL, e l'attribuzione va riportata se li pubblichi. Dove il registro di una nazione impone un'attribuzione, esce nel messaggio. Nel CSV dei lavori in blocco sono le colonne latitude, longitude, geo_precision, istat_code e cadastral_code.

→ { "geo": { "lat": 45.4762711, "lon": 9.207104, "precision": "house_number", "source": "anncsu" },
  "territory": { "istat_code": "015146", "cadastral_code": "F205", "cab": "01600", "street_id": "1026700" } }

Piano, scala e interno scritti nell'indirizzo tornano anche come dato a sé in sub_address: un elenco di coppie type e value, lette con le regole postali della nazione (in Germania dopo «//», in Francia su una riga a sé, in Portogallo «3º Esq»). I tipi sono unit (interno), staircase (scala), floor (piano), block (palazzina), building (edificio), building_number (palazzo) e block_number (isolato). La riga dell'indirizzo resta nella forma della nazione. Quello che non riconosciamo resta scritto com'era e non entra nell'elenco: non lo indoviniamo. Quando l'unità indicata risulta a quel civico, sub_address_confirmed è true; altrimenti è null, mai false: non trovarla non vuol dire che sia sbagliata.

→ { "sub_address": [ { "type": "floor", "value": "3" }, { "type": "unit", "value": "ESQ" } ], "sub_address_confirmed": true }

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: addresses è un elenco di oggetti con type e i campi di sempre; phones ed emails sono elenchi in cui ogni elemento è il dato solo ("340 7491386") oppure {"type": "work", "value": "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ù type_normalized 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://www.radaraddress.com/api/v1/dedupe \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      { "id": "C1", "last_name": "Rossi", "first_name": "Daniela",
        "address": "Via Leopardi 4", "postcode": "20123", "city": "Milano", "province": "MI" },
      { "id": "C2", "last_name": "Rossi", "first_name": "Daniela",
        "address": "V. Leopardi 4", "postcode": "20100", "city": "milano", "province": "MI" }
    ]
  }'

La risposta raggruppa i doppioni in groups: ogni gruppo elenca gli id dei suoi members, indica quale tenere (main_record) e propone il record consolidato: il nominativo migliore e l'unione di indirizzi e recapiti (addresses, phones, emails), ognuno col tipo, con provenance (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 singles, come oggetti {id, outcome}: con outcome INTERNAL_DUPLICATE 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: generate dai dati anagrafici, validate un codice esistente (formato, carattere di controllo e omocodia), extract le informazioni contenute — data di nascita, età, sesso, comune o stato estero di nascita. In più compare 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 compare 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, si paga il prezzo delle operazioni leggere (vedi prezzi).

curl -X POST https://www.radaraddress.com/api/v1/tax-code \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "generate",
    "last_name": "Rossi", "first_name": "Mario", "gender": "M",
    "birth_date": "1980-01-01", "birth_place": "Roma"
  }'

→ { "ok": true, "tax_code": "RSSMRA80A01H501U", "place": "Roma", "province": "RM" }

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

Ogni risposta porta outcome, reason, notes e comments nella lingua della richiesta: GENERATED per generate, vuoto per un codice valido in validate, MATCH o MISMATCH per compare (con differences: i campi che non tornano). Quando il codice non passa i controlli l'esito è uno dei codici TAX_CODE_* elencati sotto e error ne dà la forma corta (check_digit, length, format, homocode, month, date, place, empty); su generate dice quale dato manca o non si risolve (last_name, first_name, gender, birth_date, birth_place, ambiguous_place con options, last_name_non_latin). suggestion porta il codice corretto quando il controllo lo sa ricostruire.

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 gender 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 profession (la professione) o da education, quando ne danno uno.

curl -X POST https://www.radaraddress.com/api/v1/enrichment \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "last_name": "Rossi", "first_name": "Dott.ssa Maria" }'

→ { "ok": true, "gender": "F", "subject_type": "natural_person", "title": "Dott.ssa",
    "formal_salutation": "Gentile Dott.ssa Rossi", "informal_salutation": "Cara Maria", … }

A lotti: { "items": [ … ] }, fino a 500 per chiamata. L'esito è ENRICHED (sesso e saluti impostati), LEGAL_PERSON (azienda o ente: si tratta come ragione sociale) o PARTIAL (manca il nome, o il sesso non si deduce): reason dice perché, comments cosa aggiungere per completare.

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 items fino a 500; "dns": false salta il lookup del dominio.

Un refuso certo si corregge d'ufficio: quando l'indirizzo com'è scritto non è nemmeno un indirizzo (nome@dominio,it con la virgola) o quando la correzione atterra su un provider noto (gmai.com → gmail.com, anche a una lettera di distanza se il dominio scritto non riceve posta), email esce corretta, corrected_from porta com'era scritta e l'esito è MODIFIED EMAIL_DOMAIN. Un refuso possibile su un dominio qualunque (rossi.con) resta una proposta: EMAIL_TYPO con la correzione in suggestion, e i controlli (domain_exists, domain_checked) fatti su di lei; l'indirizzo com'è scritto non è verificato.

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 class è la lettura che serve a lavorare una lista: mobile (ci mandi un SMS), landline (lo chiami in orario d'ufficio), special (non è il recapito di una persona: emergenze, pubblica utilità, numeri verdi e a tariffa maggiorata), foreign per i numeri con prefisso internazionale. Quando riconosciamo anche il servizio preciso, type 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 phone, phone2, phone3, e phone non è mai vuoto quando almeno un numero c'è. Con "format": "international" il numero italiano esce in forma +39…; il valore predefinito national lo lascia nudo e mette il prefisso solo agli esteri. Per gli esteri torna anche e164, la nazione del prefisso in country_code e lo zero di rete dopo il prefisso viene tolto («+44 (0)20…» e «+44 20…» danno lo stesso numero). Con country_code (o country) nella chiamata o nell'elemento, un numero scritto senza prefisso è letto come numero nazionale di quella nazione: «020 7946 0958» in una scheda del Regno Unito è Londra, non Milano. Senza nazione resta italiano. Lotto items fino a 500.

Il numero della nazione del record non è «estero»: dove conosciamo il piano di numerazione esce con la sua class (mobile, landline, special), con format national resta senza prefisso nella forma del suo paese (zero di rete compreso) e torna anche national_number accanto a e164. PHONE_FOREIGN e class foreign restano per i numeri di una nazione diversa da quella del record.

curl -X POST https://www.radaraddress.com/api/v1/phone \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"phone":"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 website, website2, website3. Con "network": false controlliamo solo la forma, senza contattare il sito. Lotto items fino a 100: ogni verifica apre una connessione, quindi il lotto è più piccolo degli altri endpoint.

curl -X POST https://www.radaraddress.com/api/v1/website \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"website":"www.example.com"}'

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 e provincia; il CAP arriva alla selezione, nelle grandi città zonate quello 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 verifica contatto quando l'utente seleziona e i campi si riempiono (azione select, 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://www.radaraddress.com/api/v1/suggest \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"session":"CLIENT-UUID","q":"via verdi","city":"monz"}'

# when the user picks one: closes the session and charges the selection
curl -X POST https://www.radaraddress.com/api/v1/suggest \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"session":"CLIENT-UUID","action":"select","street_id":1063428,"house_number":"4"}'

Scelta la via, si completa il civico: passando street_id con il civico parziale si ottengono i civici esistenti di quella via, con exists vero/falso per validare quello digitato — e la selezione si può ripetere con il civico senza nuovo addebito: l'addebito è a sessione e per via, non a click; un'altra via nella stessa sessione è un altro addebito. I civici si completano solo nella sessione che ha selezionato quella via. 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 chiamate e vale 10 minuti; le sessioni senza selezione sono gratuite fino a 200 al giorno per token, più cinque per ogni selezione. Widget, proxy pronto e form d'esempio sono nel kit di Il tuo form.

Funziona in ogni nazione in servizio (oggi Francia, Germania, Spagna, Paesi Bassi, Belgio, Finlandia, Cechia, Portogallo, Danimarca, Norvegia, Austria, Svizzera, Slovacchia, Croazia, Romania, Ungheria, Slovenia, Irlanda, Islanda, Lussemburgo, Liechtenstein, San Marino, Monaco, Andorra, Città del Vaticano; l'elenco aggiornato è in Nazioni): con country_code o country i suggerimenti vengono dal registro di quel paese, e il testo si scrive come si scrive lì — via, numero, codice postale e città anche in un campo solo: «kalverstraat 92 amst», «92 rue de rivoli paris», in Olanda «1012PH 92». Ogni risposta porta parsed, cioè come il server ha letto via (street), numero (house_number) e codice postale (postcode): il tuo form sa dove sta il numero senza conoscere le regole del paese. I suggerimenti portano via, città, eventuale località e source (registry, oppure osm dove il registro nazionale non pubblica); il codice postale e i numeri civici non stanno mai nei suggerimenti: arrivano con la selezione, che passa dal motore e torna lo stesso record di /contact (postcode confermato dal registro, geo al civico). Con la selezione si può passare anche postcode, quello scritto nel form. attribution è la dicitura della fonte da mostrare accanto ai suggerimenti: la licenza del registro la richiede. Se la nazione manca si presume IT; per una nazione non in servizio la risposta resta HTTP 200 con supported:false e hints:[], senza creare la sessione né addebitare nulla. Una sessione è di una nazione: se cambia, il client genera un nuovo UUID (altrimenti 409 session_country).

curl -X POST https://www.radaraddress.com/api/v1/suggest \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"session":"CLIENT-UUID","q":"kalverstraat 92 amst","country_code":"NL"}'

{"ok":true,"phase":"streets",
 "hints":[{"type":"street","id":642154,"name":"Kalverstraat","municipality":"Amsterdam","area":"","source":"registry"}],
 "parsed":{"street":"kalverstraat","house_number":"92","postcode":""},
 "attribution":"Bron: Kadaster — BAG"}

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 "async": 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://www.radaraddress.com/api/v1/contact \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"async":true,"items":[ … 100,000 contacts … ]}'

{"ok":true,"job":"369e46e9e7bb…","state":"queued","rows":100000}

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

curl 'https://www.radaraddress.com/api/v1/contact?job=369e46e9e7bb…' \
  -H 'Authorization: Bearer YOUR_TOKEN'

{"ok":true,"state":"completed","rows":100000,"done":100000,
 "outcomes":{"ok":1240,"modified":95300,"to_check":2100,"unresolved":1360}}

curl 'https://www.radaraddress.com/api/v1/contact?job=369e46e9e7bb…&format=csv' \
  -H 'Authorization: Bearer YOUR_TOKEN' -o result.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 outcome: una lista di parole chiave, vuota quando non c'è niente da segnalare. Lo schema è sempre <conditions> [MODIFIED <types>] — le condizioni davanti, le modifiche in coda — e vale per tutti i servizi. Accanto trovi outcome_label (o kind) con ok, modified, warning, error, e reason con la spiegazione in una riga. I codici sono identificativi: si confrontano, non si traducono; con "language": "it" escono i codici italiani (LOCALITA_NON_TROVATA MODIFICATO CAP INDIRIZZO), gli stessi parola per parola.

Indirizzo (verifica contatto)

Codice fiscale

Sull'endpoint /tax-code gli stessi controlli hanno codici propri — TAX_CODE_CHECK_DIGIT_WRONG, TAX_CODE_CHECK_DIGIT_MISSING, TAX_CODE_LENGTH_WRONG, TAX_CODE_FORMAT_WRONG, TAX_CODE_MONTH_WRONG, TAX_CODE_DATE_INVALID, TAX_CODE_PLACE_UNKNOWN, TAX_CODE_EMPTY — perché lì il codice fiscale è l'oggetto della verifica, non un campo del record.

Arricchimento

Email

Telefono

Sito web

Quanto costa ogni chiamata

Ogni chiamata consuma elaborazioni del contatore del servizio: verifica contatto (/contact, /suggest alla selezione), deduplica (/dedupe) ed elaborazioni leggere (/email, /phone, /website, /enrichment, /tax-code 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 credit del JSON (counter, charged, free, subscription e packs con le elaborazioni prelevate e il residuo, available, auto_topup con il numero di pacchetti comprati in automatico, note in italiano) e gli header X-RA-Charged, X-RA-Available e, quando interviene, X-RA-Auto-Topup. 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/credit. Per ciascuno dei tre contatori (contact, dedupe, light) restituisce available, le free rimaste nel mese e la data in cui si azzerano (il 1°), l'subscription (residuo, taglia, rinnovo), i packs attivi uno per uno con quanto resta (non scadono) e quanti ne hai comprati, l'auto_topup (attiva, taglia, tetto e speso del mese in euro), l'uso (used nel mese, totali, ultimo uso) e soprattutto lo state, perché uno zero da solo non dice se hai esaurito o se quel servizio non lo usi: never_used, free (mai comprato, lavori nelle gratuite del mese), free_used_up, active, awaiting_renewal, used_up (hai comprato in passato e non resta nulla: va ricaricato), con un warning in italiano. In cima needs_topup elenca i contatori su cui intervenire ed endpoint dice quale contatore consuma ogni endpoint. Vuole il token di un account.

curl https://www.radaraddress.com/api/v1/credit -H 'Authorization: Bearer YOUR_TOKEN'
→ { "ok": true, "counters": { "contact": { "available": 48250, "free": { "remaining": 50, "month": 50 },
      "subscription": { "left": 23200, "size": 25000, "renews_on": "2026-10-03" }, "packs": { "left": 25000, "active_packs": [ … ] },
      "state": "active", "warning": "" }, "dedupe": { "state": "never_used", "warning": "Counter never used: zero does not mean used up. …", … },
      "light": { … } }, "needs_topup": [], "endpoint": { "contact": "contact", "email": "light", … } }

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.