Dasselbe System,
in Ihrer App.

Ein Endpunkt pro Dienst, mit demselben Namen, den der Dienst auf dieser Website hat: /contact, /dedupe, /email, /phone, /website, /tax-code, /enrichment. Jeder akzeptiert ein Element im Anfragetext oder eine Liste in items, bis zu 500 pro Aufruf (100 bei Websites, die einzeln kontaktiert werden müssen). Die Dublettenbereinigung ist die Ausnahme und verlangt immer eine Liste: Sie vergleicht die Datensätze untereinander. Gesondert stehen /suggest, die Autovervollständigung für Formulare (sie arbeitet sitzungsweise, während der Nutzer tippt, nicht in Stapeln), und /credit, das sagt, wie viele Vorgänge übrig sind und in welchem Zustand jeder Zähler ist, ohne welche zu verbrauchen.

Authentifizierung

Der API-Host ist www.radaraddress.com. Feldnamen, Endpunktnamen und Werte sind englische Bezeichner, in jeder Sprache gleich; Etiketten, Begründungen und Meldungen folgen der Sprache der Anfrage ("language": "de" oder ?language=de, oder der Header Accept-Language, oder die Sprache des Kontos). Der Header Content-Language sagt, in welcher Sprache die Antwort gekommen ist.

Der Zugang zur API erfolgt über einen Bearer-Token. Das Konto ist kostenlos: Sie erzeugen den Token in Ihrem Konto und übergeben ihn im Header jeder Anfrage in dieser Form:

# Every request needs the Authorization header
Authorization: Bearer {your-token}

Beim Erstellen können Sie dem Token ein optionales Ablaufdatum geben: Nach diesem Datum erhalten Anfragen HTTP 401 mit dem Code token_expired; ohne Ablaufdatum gilt der Token, bis Sie ihn widerrufen. Sie können ihn jederzeit in Ihrem Konto widerrufen oder neu erzeugen; dort sehen Sie auch die letzte Verwendung und die Zahl der bedienten Anfragen. Eine Anfrage ohne Token oder mit ungültigem Token liefert HTTP 401.

Die italienischen Namen, für wer sie schon verwendet

Die API hat eine einzige Version, auf Englisch. Wer mit den italienischen Namen integriert hat, muss nichts ändern: italienische Felder werden in jeder Anfrage akzeptiert, die Endpunkte antworten auch unter ihrem italienischen Namen (/contatto, /deduplica, /codicefiscale, /arricchimento, /telefono, /sito, /suggerisci, /nazioni, /credito), und die Antwort kommt mit den italienischen Schlüsseln und Codes für wer es mit "language": "it" verlangt oder www.radaraddress.it ohne Sprachangabe aufruft.

Die vollständige Tabelle der Felder: Englisch → Italienisch

Englisch	Italienisch	Englisch	Italienisch
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

Auch die Optionswerte haben einen italienischen Namen: format nazionale/internazionale, action genera/valida/estrai/confronta/seleziona, foreign dichiarati/rileva, min_level certo/probabile/ambiguo; mit "language": "it" kommen so auch level, confidence, state, die Codes von outcome und die Spaltenüberschriften der Dateien. Bei der Eingabe werden auch gängige Synonyme akzeptiert (zip, surname, phone_number, date_of_birth…) und dieselben Überschriften in den Dateien der Stapelverarbeitung.

Endpunkt Kontaktprüfung

Bringt den ganzen Kontakt in Ordnung: die Adresse nach dem Poststandard ihres Landes — in Italien und in den Ländern mit Register im Dienst werden Straße und Hausnummer im nationalen Adressregister geprüft, in den übrigen erscheint die Adresse in der Postform des Landes —, den Namen und — wenn die Anfrage ihn enthält — die italienische Steuernummer, die bereinigt, bei fehlendem Prüfzeichen ergänzt und mit Nachname, Vorname, Geschlecht und Geburtsdatum abgeglichen wird. Ein Kontakt je Aufruf oder bis zu 500 in items: das Schema ist bei allen anderen Endpunkten dasselbe.

Das Land wird mit country_code (ISO 3166-1: IT, DE, FR…) oder mit country angegeben, geschrieben wie es kommt: „Germania“, „Germany“, „Deutschland“, „Bundesrepublik Deutschland“, „UK“, „Holland“. Fehlt es, wird Italien angenommen. In den Ländern mit Register im Dienst — heute Frankreich, Deutschland, Spanien, Niederlande, Belgien, Finnland, Tschechien, Portugal, Dänemark, Norwegen, Österreich, Schweiz, Slowakei, Kroatien, Rumänien, Ungarn, Slowenien, Irland, Island, Luxemburg, Liechtenstein, San Marino, Monaco, Andorra, Vatikanstadt, die aktuelle Liste steht unter Länder — werden Straße und Hausnummer wie in Italien im nationalen Adressregister geprüft: Postleitzahl bestätigt oder ergänzt, Koordinaten der Hausnummer in geo, Stadtteil oder Arrondissement in district, wo die Stadt welche hat (Hamburg-Altstadt, Paris 4e Arrondissement), Gemeindecode des Registers in territory.municipality_code. Auf Italienisch trägt das Ergebnis FOREIGN, gefolgt von den Änderungen, in den anderen Sprachen nur die Änderungen; gibt es die Straße, aber nicht die Nummer, HOUSE_NUMBER_NOT_FOUND. In den übrigen Ländern arbeiten wir an der Form, und die Meldung sagt es: Postleitzahl im Format des Landes, Straßenabkürzungen aufgelöst, Großschreibung und Ortsname, wie die Post dieses Landes sie schreibt (Hauptstr. 5, Monaco di Baviera → Hauptstraße 5, MÜNCHEN), mit der Länderzeile. In beiden Fällen kommt address_key zurück, die Form, mit der die Dublettenprüfung dieselbe Straße in zwei Schreibweisen erkennt. Mit "foreign": "detect" wird ein Datensatz ohne Land, der in Italien nicht gefunden wird, als ausländisch erkannt, wenn der Text es klar sagt; der Standard declared lässt nur das ausländisch, was es angibt. Der vollständige Länderkatalog, mit Kurz- und amtlichem Namen, auf Englisch und in der Sprache des Landes, steht unter GET /api/v1/countries und lässt sich mit ?q=Germania, ?q=Deutschland oder ?q=DE abfragen.

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"}'

Für den Stapel dieselben Felder in items; die Antwort ist { count, results: [ { id, result } ] } in derselben Reihenfolge wie gesendet.

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"}]}'

Derselbe Endpunkt für eine Adresse in einem anderen Land: country_code genügt. Hier Hamburg, geprüft im deutschen Register, mit Stadtteil und Koordinaten der Hausnummer.

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" } }

Optionen, die für den ganzen Aufruf gelten: postal_form (erzwingt auch normalized in der postalischen Form), preserve_original (behält den vom Nutzer geschriebenen Namen und gibt den kanonischen gesondert aus), precision 1–5 (Standard 3; über 3 ist der Abgleich näherungsweise, und die Zuverlässigkeit wird nicht high sein).

Zusammen mit der Adresse kommt city_type, das sagt, ob der Zustellpunkt in einer Provinzhauptstadt oder in einem Ort der Provinz liegt – der Unterschied, der zählt, wenn eine Kampagne nach Städten aufgeteilt wird. provincial_capital ist true, false oder null, wenn wir keine Anhaltspunkte dafür haben – und in diesem Fall raten wir nicht.

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

Neben der PLZ kommt postcode_check: woher sie stammt (source) und wie genau (precision: house_number die Nummer selbst, interpolated die Nachbarnummern derselben Straße, street die Mehrheit der Straße, locality, municipality), wie viele Hausnummern das belegen (house_numbers) und mit welcher Übereinstimmung (agreement, 0 bis 1). Fehlt für diese Nummer eine Bestätigung, trägt das Ergebnis POSTCODE_UNCONFIRMED und confirmed ist false: die PLZ bleibt wie angegeben, sofern sie zur Stadt gehört, und sollte geprüft werden.

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

Zurück kommen auch die Koordinaten in geo (Breite und Länge WGS84) und die Gebietskennungen in territory: in Italien ISTAT-Code und Katastercode der Gemeinde, CAB und nationale Straßenkennung; in den übrigen Ländern country und der Gemeindecode des nationalen Registers (municipality_code). Das Feld precision sagt, welche Stufe erreicht wurde: house_number, wenn die Hausnummer georeferenziert ist, interpolated, wenn die genaue Nummer fehlt und der Punkt geschätzt ist, street, wenn wir den Punkt der Straße haben, municipality, wenn nur der Gemeindemittelpunkt vorliegt. source sagt, woher der Punkt stammt: anncsu ist das italienische nationale Register, inspire das nationale Register des Landes, osm OpenStreetMap: dann sind die Daten © OpenStreetMap contributors, Lizenz ODbL, und die Quellenangabe ist zu übernehmen, wenn Sie sie veröffentlichen. Wo das Register eines Landes eine Quellenangabe verlangt, steht sie in der Meldung. In der CSV der Stapelaufträge sind es die Spalten latitude, longitude, geo_precision, istat_code und 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" } }

Etage, Treppe und Wohnung aus der Anschrift kommen zusätzlich als eigene Daten in sub_address zurück: eine Liste von Paaren aus type und value, gelesen nach den Postregeln des jeweiligen Landes (in Deutschland nach „//“, in Frankreich in einer eigenen Zeile, in Portugal „3º Esq“). Die Typen sind unit (Wohnung), staircase (Treppe), floor (Etage), block, building, building_number und block_number. Die Adresszeile bleibt in der Form des Landes. Was wir nicht erkennen, bleibt so, wie es geschrieben war, und steht nicht in der Liste: Wir raten nicht. Ist die angegebene Einheit unter dieser Hausnummer verzeichnet, ist sub_address_confirmed true, sonst null, nie false: Dass wir sie nicht finden, heißt nicht, dass sie falsch ist.

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

Endpunkt Dublettenbereinigung

Erkennt die Datensätze, die sich auf dieselbe Person an derselben Adresse beziehen, auch wenn sie unterschiedlich geschrieben sind: Kurzformen und Entsprechungen von Vornamen (Dany ≈ Daniela), Nachname und Vorname vertauscht, Abkürzungen ("V. Roma" ≈ "Via Roma"), Tippfehler. Der Adressvergleich läuft über die Normalisierung: Zwei Schreibweisen derselben Straße fallen vor dem Vergleich auf die kanonische Form zusammen. Höchstens 500 Kontakte pro Aufruf (Datensätze + Referenz); für größere Listen nutzen Sie die Stapelverarbeitung in Ihrem Konto.

Adressbücher. Ein Kontakt im Adressbuch (Apple Kontakte, Google, Outlook: das vCard-Modell) hat mehrere Adressen, mehrere Telefonnummern und mehrere E-Mail-Adressen, jede mit einer Bezeichnung. Der Endpunkt nimmt sie so entgegen, ohne Obergrenze: addresses ist eine Liste von Objekten mit type und den üblichen Feldern; phones und emails sind Listen, in denen jedes Element der bloße Wert ist ("340 7491386") oder {"type": "work", "value": "02 66710423"}, auch gemischt; die üblichen flachen Felder bleiben gültig und gelten als erste Adresse und erste Kontaktangabe. Zwei Kontakte sind dieselbe Person, wenn irgendein Paar ihrer Adressen übereinstimmt (das Büro des einen mit der einzigen Adresse des anderen) oder wenn sie denselben Namen und eine Telefonnummer oder E-Mail gemeinsam haben, an beliebiger Stelle und mit beliebiger Bezeichnung. Die Bezeichnung hat kein Gewicht beim Abgleich: Sie kommt zurück, wie sie angekommen ist, plus type_normalized im vCard-Vokabular (home, work, cell …), damit die App weiß, wohin sie zurückschreiben soll. Ein Kontakt ist ein Vorgang, egal wie viele Adressen und Kontaktangaben er hat.

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" }
    ]
  }'

Die Antwort gruppiert die Dubletten in groups: Jede Gruppe listet die ids ihrer members auf, sagt, welcher zu behalten ist (main_record), und schlägt den konsolidierten record vor: den besten Namen und die Vereinigung von Adressen und Kontaktangaben (addresses, phones, emails), jede mit ihrem Typ, mit provenance (aus welchen Kontakten sie stammt) und dublettenfrei: Dieselbe Straße in zwei Schreibweisen ist eine Adresse, dieselbe Nummer mit zwei Bezeichnungen eine Nummer. Kontakte ohne Treffer stehen in singles, als Objekte {id, outcome}: Mit outcome INTERNAL_DUPLICATE hat der Kontakt keine Dubletten mit anderen, aber welche in sich selbst (Adresse zweimal geschrieben, Nummer wiederholt), und bringt seinen zusammengeführten record mit. Es erkennt dieselbe Straße in verschiedenen Schreibweisen ("V. Leopardi 4" ≈ "Via Giacomo Leopardi 4"), die automatisch berichtigte Postleitzahl und vertauschte Nach- und Vornamen.

Endpunkt italienische Steuernummer

Drei Aktionen auf der italienischen Steuernummer natürlicher Personen: generate aus den Personendaten, validate einen vorhandenen Code (Format, Prüfzeichen und Omocodia), extract die enthaltenen Informationen – Geburtsdatum, Alter, Geschlecht, Geburtsgemeinde oder Geburtsland. Zusätzlich prüft compare, ob ein Code zu den angegebenen Personendaten passt. Abgedeckt sind die Katastercodes aller italienischen Gemeinden und der ausländischen Staaten. Nachname und Vorname sind in lateinischen Buchstaben zu übergeben: Bei einem Namen in einem anderen Alphabet wird der Code auf der im Dokument angegebenen Transliteration berechnet, die nicht eindeutig ist (Dmitrij/Dmitry); ein nicht lateinischer Name liefert cognome_non_latino oder nome_non_latino, und bei compare trägt eine Abweichung im Namen einer im Ausland geborenen Person einen Hinweis auf eine möglicherweise andere Transliteration.

Die ersten 500 einfachen Prüfungen im Monat sind kostenlos (Steuernummer eingeschlossen), und das Freikontingent ist ein einziges über alle Nutzungsarten hinweg: Was Sie hier, auf der Website und in Stapeldateien tun, zählt auf dasselbe Kontingent. Darüber hinaus werden einfache Prüfungen zu ihrem Preis berechnet (siehe Preise).

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" }

Für Volumen: { "action": "validate", "items": [ … ] } verarbeitet bis zu 500 Elemente pro Aufruf, jedes mit seiner eigenen Korrelations-id. Die Extraktion kennzeichnet mit ambiguous_year die Fälle, in denen die zwei Ziffern des Jahres das Jahrhundert nicht unterscheiden (1926 vs. 2026).

Jede Antwort trägt outcome, reason, notes und comments in der Sprache der Anfrage: GENERATED bei generate, leer bei gültigem Code in validate, MATCH oder MISMATCH bei compare (mit differences: die abweichenden Felder). Besteht der Code die Prüfungen nicht, ist das Ergebnis einer der unten aufgeführten TAX_CODE_*-Codes und error gibt die Kurzform (check_digit, length, format, homocode, month, date, place, empty); bei generate sagt es, welche Angabe fehlt oder sich nicht auflösen lässt (last_name, first_name, gender, birth_date, birth_place, ambiguous_place mit options, last_name_non_latin). suggestion trägt den korrekten Code, wenn die Prüfung ihn rekonstruieren kann.

Endpunkt Anreicherung

Reichert einen Namen an: Geschlecht aus dem Vornamen abgeleitet, Art des Subjekts (natürliche oder juristische Person), normalisierter Titel (Dott.ssa, Avv., …) und Anredeformen fertig für die Korrespondenz – "Egregio Sig. Rossi", "Gentile Dott.ssa Bianchi", "Spett.le" für Unternehmen, "Gentile Famiglia" für Haushalte, "Caro/Cara" für die informelle Anrede. Erkennt auch die Ehenamensform im Nachnamen ("Rossi in Verdi" → Frau, mit beiden Nachnamen im Detail). Das Feld gender akzeptiert auch ausgeschriebene Formen („maschio“, „donna“, „Sig.ra“, „male“); X kennzeichnet eine Organisation und G eine Familie oder ein Paar. Fehlt der Titel, leiten wir ihn aus profession (dem Beruf) oder aus education ab, wenn eines davon angegeben ist. Die Verzeichnisse sind italienisch.

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", … }

Stapelweise: { "items": [ … ] }, bis zu 500 pro Aufruf. Das Ergebnis ist ENRICHED (Geschlecht und Anreden gesetzt), LEGAL_PERSON (Firma oder Einrichtung: als Firmenname behandelt) oder PARTIAL (Vorname fehlt oder Geschlecht nicht ableitbar): reason sagt warum, comments was zur Vervollständigung fehlt.

Endpunkt E-Mail-Prüfung

Prüft eine E-Mail-Adresse: Syntax, Existenz der Domain (MX-/A-Einträge), Tippfehler bei gängigen Domains mit Korrekturvorschlag (gmial.com → gmail.com), Wegwerf-Domains, unpersönliche Adressen (info@, buchhaltung@: keine Person). Eine SMTP-Prüfung des einzelnen Postfachs machen wir nicht – eine aufdringliche und unzuverlässige Praxis. Stapel items bis zu 500; "dns": false überspringt die Domain-Abfrage.

Ein sicherer Tippfehler wird direkt korrigiert: wenn die Adresse in der geschriebenen Form gar keine Adresse ist (name@domain,de mit Komma) oder wenn die Korrektur bei einem bekannten Anbieter landet (gmai.com → gmail.com, auch mit einem Buchstaben Abstand, wenn die geschriebene Domain keine Post empfängt), kommt email korrigiert zurück, corrected_from enthält die geschriebene Form und das Ergebnis ist MODIFIED EMAIL_DOMAIN. Ein möglicher Tippfehler bei einer beliebigen Domain (rossi.con) bleibt ein Vorschlag: EMAIL_TYPO mit der Korrektur in suggestion, und die Prüfungen (domain_exists, domain_checked) laufen an ihr; die Adresse in der geschriebenen Form wird nicht geprüft.

Endpunkt Telefonprüfung

Prüft eine Nummer, ohne jemanden anzurufen: Form, Klasse und Typ, Länge nach dem Nummerierungsplan, Ortsnetz des Festnetzanschlusses und Anbieter, dem der Block ursprünglich zugeteilt wurde. Die class ist die Lesart, die man braucht, um eine Liste zu bearbeiten: mobile (Sie können eine SMS schicken), landline (Sie rufen zu Bürozeiten an), special (nicht die Nummer einer Person: Notruf, öffentliche Dienste, kostenlose und Sondertarifnummern), foreign für Nummern mit internationaler Vorwahl. Erkennen wir auch den genauen Dienst, sagt type es (kostenlose Nummer, Sondertarif, geteilte Kosten, öffentlicher Dienst). Die italienische Vorwahl ohne + (39347…, ein klassischer Exportfehler) entfernen wir, wenn die Ziffern keinen Zweifel lassen – 3934567890 bleibt die Mobilnummer, die sie ist. Stehen im selben Feld mehrere Nummern („347… - 338…“), trennen wir sie: Sie kommen als phone, phone2, phone3 zurück, und phone ist nie leer, wenn mindestens eine Nummer vorhanden ist. Mit "format": "international" kommt die italienische Nummer in der Form +39… heraus; der Standardwert national lässt sie ohne Vorwahl und setzt die Vorwahl nur bei ausländischen Nummern. Für ausländische Nummern kommt auch e164 zurück, das Land der Vorwahl in country_code, und die führende Null nach der Vorwahl wird entfernt („+44 (0)20…“ und „+44 20…“ ergeben dieselbe Nummer). Mit country_code (oder country) im Aufruf oder im Element wird eine Nummer ohne Vorwahl als nationale Nummer dieses Landes gelesen: „020 7946 0958“ in einem britischen Datensatz ist London, nicht Mailand. Ohne Land bleibt sie italienisch. Stapel items bis zu 500.

Eine Nummer aus dem Land des Datensatzes ist nicht „ausländisch“: Wo wir den Nummernplan kennen, erhält sie ihre class (mobile, landline, special), mit format national bleibt sie ohne Ländervorwahl in der Form ihres Landes (Verkehrsausscheidungsziffer eingeschlossen), und neben e164 kommt national_number zurück. PHONE_FOREIGN und class foreign bleiben für Nummern aus einem anderen Land als dem des Datensatzes.

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"}'

Endpunkt Website-Prüfung

Prüft, dass die Adresse richtig geschrieben ist und dass die Website wirklich antwortet: Existenz der Domain, HTTP-Anfrage mit verfolgten Weiterleitungen, Endcode, Gültigkeit des Zertifikats. Kein Urteil über den Inhalt. Auch hier kommen mehrere Adressen im selben Feld als website, website2, website3 zurück. Mit "network": false prüfen wir nur die Form, ohne die Website zu kontaktieren. Stapel items bis zu 100: Jede Prüfung öffnet eine Verbindung, deshalb ist der Stapel kleiner als bei den anderen Endpunkten.

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"}'

Endpunkt Adress-Autovervollständigung

Sie fangen bei null an? Das Widget ra-suggerisci.js und ein kleiner Proxy auf Ihrem Server genügen: der Token gelangt nie in den Browser.

Vorschläge während der Eingabe einer Adresse in Ihrem Formular: das gesamte italienische Straßenverzeichnis, mit vervollständigtem Namen („via verdi“ → „Via Giuseppe Verdi“), Gemeinde und Provinz; die Postleitzahl kommt mit der Auswahl, in den großen Städten mit Postzonen die richtige zur Hausnummer. Es arbeitet sitzungsweise: Der Client erzeugt für jede Adresse, die gerade ausgefüllt wird, eine UUID, die Vorschlagsabfragen sind kostenlos, und Sie zahlen eine Kontaktprüfung, wenn der Nutzer auswählt und die Felder gefüllt werden (Aktion select, die den bereits vom System normalisierten Datensatz zurückgibt). Die im Formular schon ausgefüllten Felder – auch teilweise – reisen als Kontext mit und grenzen die Vorschläge ein.

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"}'

Ist die Straße gewählt, wird die Hausnummer vervollständigt: Übergibt man street_id mit der angefangenen Nummer, erhält man die vorhandenen Hausnummern dieser Straße, mit exists wahr/falsch zur Validierung der eingegebenen – und die Auswahl lässt sich mit der Hausnummer ohne neue Berechnung wiederholen: Berechnet wird pro Sitzung und pro Straße, nicht pro Klick; eine andere Straße in derselben Sitzung ist eine neue Berechnung. Hausnummern werden nur in der Sitzung vervollständigt, die diese Straße ausgewählt hat. In Städten mit Postzonen bestimmt die Hausnummer die genaue Postleitzahl.

Der API-Token gelangt nie in den Browser: Das fertige Widget (ra-suggerisci.js) ruft einen kleinen Proxy auf Ihrem Server auf, der den Token hinzufügt und weiterleitet. Jede Sitzung erlaubt bis zu 30 Aufrufe und gilt 10 Minuten; Sitzungen ohne Auswahl sind bis zu 200 pro Tag und Token kostenlos, plus fünf je Auswahl. Widget, fertiger Proxy und Beispielformular finden Sie im Kit von Ihr eigenes Formular.

Funktioniert in jedem Land im Dienst (heute Frankreich, Deutschland, Spanien, Niederlande, Belgien, Finnland, Tschechien, Portugal, Dänemark, Norwegen, Österreich, Schweiz, Slowakei, Kroatien, Rumänien, Ungarn, Slowenien, Irland, Island, Luxemburg, Liechtenstein, San Marino, Monaco, Andorra, Vatikanstadt; die aktuelle Liste steht unter Länder): Mit country_code oder country kommen die Vorschläge aus dem Register dieses Landes, und der Text wird so geschrieben, wie man ihn dort schreibt — Straße, Hausnummer, Postleitzahl und Stadt auch in einem einzigen Feld: «kalverstraat 92 amst», «92 rue de rivoli paris», in den Niederlanden «1012PH 92». Jede Antwort enthält parsed, also wie der Server Straße (street), Hausnummer (house_number) und Postleitzahl (postcode) gelesen hat: Ihr Formular weiß, wo die Nummer steht, ohne die Regeln des Landes zu kennen. Die Vorschläge enthalten Straße, Stadt, gegebenenfalls Ortsteil und source (registry, oder osm, wo das nationale Register nichts veröffentlicht); Postleitzahl und Hausnummern stehen nie in den Vorschlägen: Sie kommen mit der Auswahl, die durch die Engine läuft und denselben Datensatz wie /contact zurückgibt (postcode vom Register bestätigt, geo auf Hausnummernebene). Mit der Auswahl können Sie auch postcode übergeben, die im Formular geschriebene. attribution ist der Quellenhinweis, der neben den Vorschlägen anzuzeigen ist: Die Lizenz des Registers verlangt ihn. Fehlt das Land, wird IT angenommen; für ein Land außerhalb des Dienstes bleibt die Antwort HTTP 200 mit supported:false und hints:[], ohne Sitzung und ohne Abbuchung. Eine Sitzung gehört zu einem Land: Ändert es sich, erzeugt der Client eine neue UUID (sonst 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"}

Große Volumen: der asynchrone Auftrag

Normale Aufrufe antworten sofort, und deshalb haben sie eine Obergrenze an Elementen – eine HTTP-Anfrage, die Minuten dauert, nützt niemandem. Die Obergrenzen folgen dem Aufwand des Vorgangs:

Über diese Zahlen hinaus muss die Liste nicht von Hand aufgeteilt werden: Fügen Sie "async": true hinzu, und der Aufruf kommt sofort mit einem Code zurück, während die Verarbeitung in dieselbe Warteschlange wie der Datei-Upload geht. Bis zu 100.000 Elemente pro Aufruf, und in Meine Aufträge erscheint ein einziger.

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}

Dann lesen Sie ihn ab, wenn Sie ihn brauchen, und das Ergebnis kommt als JSON oder als 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

Unter 5.000 Zeilen kommt das Ergebnis auch in results innerhalb des JSON zurück; darüber wird es als CSV heruntergeladen. Berechnet wird, wenn der Auftrag in die Warteschlange gestellt wird, und der nicht verarbeitete Teil geht an Ihr Guthaben zurück, wenn der Auftrag abbricht. Der Token muss zu einem Konto gehören: Der Auftrag landet in Ihrer Warteschlange.

Ergebniscodes

Jede Antwort enthält das Feld outcome: eine Liste von Schlüsselwörtern, leer, wenn es nichts zu melden gibt. Das Schema ist immer <conditions> [MODIFIED <types>] — die Bedingungen vorne, die Änderungen am Ende — und gilt für alle Dienste. Daneben finden Sie outcome_label (oder kind) mit ok, modified, warning, error, und reason mit der Erklärung in einer Zeile. Die Codes sind Bezeichner: sie werden verglichen, nicht übersetzt; mit "language": "it" kommen die italienischen Codes (LOCALITA_NON_TROVATA MODIFICATO CAP INDIRIZZO), Wort für Wort dieselben.

Adresse (Kontaktprüfung)

Italienische Steuernummer

Am Endpunkt /tax-code haben dieselben Prüfungen eigene Codes – 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 –, weil dort die Steuernummer der Gegenstand der Prüfung ist und nicht ein Feld des Datensatzes.

Anreicherung

E-Mail

Telefon

Website

Was jeder Aufruf verbraucht

Jeder Aufruf verbraucht Vorgänge vom Zähler des Dienstes: Kontaktprüfung (/contact, /suggest bei der Auswahl), Dublettenbereinigung (/dedupe) und einfache Prüfungen (/email, /phone, /website, /enrichment, /tax-code über das Freikontingent hinaus). Vorgänge kauft man als Pakete, die bleiben, oder mit einem Monatsabonnement; der Preis pro 1.000 sinkt mit der Größe und steht auf der Seite Preise. Jeden Monat sind 50 Kontaktprüfungen, 100 Datensätze in der Dublettenbereinigung und 500 einfache Prüfungen kostenlos.

Jede Antwort sagt, was sie verbraucht hat und woher: das Feld credit im JSON (counter, charged, free, subscription und packs mit den entnommenen Vorgängen und dem Rest, available, auto_topup mit der Zahl der automatisch gekauften Pakete, note) und die Header X-RA-Charged, X-RA-Available und, wenn sie eingreift, X-RA-Auto-Topup. Decken die verfügbaren Vorgänge den Aufruf nicht und ist die automatische Aufladung des Zählers nicht aktiv (oder schlägt fehl), lautet die Antwort 402 payment_required, und es wird nichts verarbeitet.

Um zu erfahren, wie viele Vorgänge übrig sind, ohne einen zu verbrauchen, gibt es GET /api/v1/credit. Für jeden der drei Zähler (contact, dedupe, light) liefert er available, die im Monat verbliebenen kostenlosen (free) und das Datum, an dem sie zurückgesetzt werden (der 1.), das subscription (Rest, Größe, Verlängerung), die aktiven packs einzeln mit dem, was übrig ist (sie verfallen nicht), und wie viele Sie gekauft haben, die auto_topup (aktiv, Größe, Limit und Ausgaben des Monats in Euro), die Nutzung (used im Monat, Gesamtwerte, letzte Nutzung) und vor allem den state, denn eine Null allein sagt nicht, ob Sie alles aufgebraucht haben oder diesen Dienst nicht nutzen: never_used, free (nie gekauft, Sie arbeiten im kostenlosen Monatskontingent), free_used_up, active, awaiting_renewal, used_up (Sie haben früher gekauft, und es ist nichts mehr übrig: nachladen), mit einem warning. Ganz oben listet needs_topup die Zähler auf, bei denen Handlungsbedarf besteht, und endpoint sagt, welchen Zähler jeder Endpunkt verbraucht. Erfordert den Token eines Kontos.

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", … } }

Bezahlt wird pro geprüftem Element, nicht pro Aufruf: Stehen in einem Feld zwei Telefonnummern oder zwei E-Mail-Adressen, prüfen wir alle (bis zu drei pro Zeile), und jede zahlt ihren Preis. Ein Stapelaufruf verbraucht so viel wie die Vorgänge, die er enthält. Ist das Guthaben aufgebraucht und die automatische Aufladung nicht aktiv, antwortet die API mit HTTP 402 (Guthaben nicht ausreichend); nach Überschreiten des Rate-Limits antwortet sie mit HTTP 429 und retry_after. Ein Paket kaufen Sie in Ihrem Konto, oder Sie aktivieren ein Abonnement, um pro Vorgang weniger zu zahlen.