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.

Optional: Wenn Sie die API aus einem Formular aufrufen, können Sie mit zwei Headern angeben, wo es sich befindet: X-RadarAddress-Form-Page (die Adresse der Seite mit dem Formular) und X-RadarAddress-Form (welches Formular und an welcher Stelle, zum Beispiel checkout/billing). So lässt sich jede Verarbeitung dem Formular zuordnen, aus dem sie kam. Von der Seite speichern wir nur Domain und Pfad, ohne den Teil nach dem Fragezeichen.

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.

Jede HTTP-Methode tut, was ihr Name sagt: GET liest und verbraucht keine Vorgänge (/credit, /countries, das erneute Abrufen eines Auftrags), POST verarbeitet, DELETE löscht einen Auftrag. Eine Methode, die der Endpoint nicht annimmt, erhält HTTP 405 mit dem Header Allow, der die richtigen auflistet.

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.

Die vollständige Tabelle der Felder: Englisch → Italienisch

Englisch	Italienisch	Englisch	Italienisch
account	account	metric	metrico
action	azione	min_level	livello_minimo
activated_on	attivato_il	missing	mancano
active	attiva	modified	modificati
active_packs	attivi	module_version	versione_modulo
address	indirizzo	month	mese
address_key	indirizzo_confronto	monthly_cap_eur	tetto_mese_eur
addresses	indirizzi	moved_fields	campi_spostati
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	order	ordine
changed	modificato	order_date	data_ordine
changes	modifiche	origin	origine
charged	consumate	other	altro
check	controlla	outcome	esito
check_digit	controllo	outcome_label	esito_label
city	localita	outcomes	esiti
city_key	localita_confronto	overall_cap_eur	tetto_globale_eur
city_passes	cicli_localita	packs	pacchetti
city_type	localita_tipo	parsed	letto
class	classe	phase	fase
code	codice	phone	telefono
colour	colore	phone2	telefono2
comments	commenti	phone3	telefono3
conditions	condizioni	phone_outcome	telefono_esito
confidence	confidenza	phones	telefoni
confirmed	confermato	place	luogo
consolidate	consolida	position	posizione
contact	contatto	postcode	cap
contact_person	referente	postcode_check	cap_verifica
corrected_from	corretta_da	precision	precisione
counter	contatore	preserve_original	preserva_originale
counters	contatori	presumed	presunto
countries	nazioni	privacy_consent	consenso_privacy
country	nazione	processed	lavorato
country_code	nazione_iso2	processed_at	datalav
country_original	nazione_originale	profession	qualifica
country_prefix	prefisso_paese	provenance	provenienza
created	creato	province	provincia
credit	credito	provincial_capital	capoluogo
dedupe	deduplica	purchase_url	acquisto
default_country	nazione_predefinita	reachable	raggiungibile
detail	dettaglio	reason	motivo
differences	differenze	record_outcome	esito_record
discarded	scartati	records	anagrafiche
disposable	usa_e_getta	redirects	redirect
district	quartiere	reference	riferimento
domain_checked	dominio_verificato	reference_id	riferimento_id
domain_exists	dominio_esiste	remaining	rimaste
done	fatte	renews_on	si_rinnova_il
duration_ms	durata_ms	reset_on	si_azzerano_il
e164	formato_e164	rows	righe
education	titolo_studio	salutation	saluto
email_outcome	email_esito	save	salva
enrichment	arricchimento	segment_passes	cicli_arcostradale
entries	schede	session	sessione
error	errore	shop_domain	dominio
existing_account	account_esistente	short	breve
exists	esiste	similar_to	simile_a
expiry	scadenza	singles	singoli
explanations	spiegazioni	size	taglia
extension	estensione	source	fonte
field	campo	specificity	specificita
final_url	url_finale	spent_month_eur	speso_mese_eur
first_name	nome	spent_overall_month_eur	speso_globale_mese_eur
fix_typos	correggi_refusi	state	stato
foreign	esteri	states	stati
foreign_address	estero	street	strada
formal_salutation	saluto_formale	street_id	via_id
format	formato	street_name	toponimo
found	trovato	street_passes	cicli_toponimo
free	gratuite	street_proper_name	duf
free_forever	gratis_per_sempre	street_type	dug
full_name	nominativo	sub_address	subindirizzo
gender	sesso	sub_address_confirmed	subindirizzo_confermato
gender_source	fonte_sesso	subject_type	tipo_soggetto
generic	generica	subscription	abbonamento
group	gruppo	suffix	esponente
groups	gruppi	suggestion	suggerimento
hamlet	frazione	summary	riepilogo
hints	suggerimenti	supported	supportato
homocode	omocodo	syntax	sintassi
house_number	civico	tax_code	codice_fiscale
house_number_label	civico_label	tax_code_outcome	codice_fiscale_esito
house_number_verified	civico_verificato	territory	territorio
house_numbers	civici	text	testo
informal_salutation	saluto_informale	time_ms	tempo_ms
iso2	codice_iso2	title	titolo
iso3	codice_iso3	to_check	da_controllare
istat_code	istat	total	totali
items	elementi	town	citta
job	lavoro	truncated	troncato
language	lingua	type	tipo
languages	lingue	type_normalized	tipo_norm
last_name	cognome	types	tipi
last_on	ultimo_il	typo_level	livello_refuso
last_used	ultimo_uso	unresolved	non_risolti
left	residuo	url_normalized	url_normalizzato
legacy_default	default_storico	used	usate
letter_name	nome_lettera	valid	valida
level	livello	value	valore
light	leggere	warning	avviso
long	lungo	warnings	avvisi
long_name	nome_esteso	website	sito
main_record	principale	website2	sito2
match	corrisponde	website3	sito3
matches	abbinamenti	website_outcome	sito_esito
members	membri	websites	siti
method	metodo	zoned	zonato

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 Adressprü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.

Im selben Datensatz können Sie email, phone und website übergeben: Wir prüfen sie im selben Vorgang, zusammen mit dem Namen und dem tax_code. Die Antwort enthält email_outcome, phone_outcome, website_outcome und enrichment (Geschlecht, Titel, Anrede). Deren Ergebnisse fließen nicht in outcome ein, das weiterhin das Ergebnis von Adresse und Steuernummer ist. In einer Liste werden Websites bis zu 100 pro Aufruf kontaktiert: Bei allen weiteren wird nur die Form geprüft.

Zwei Schalter, die eingeschaltet sind, wenn Sie sie nicht senden: network:false kontaktiert die Websites nicht und dns:false prüft nicht, ob die E-Mail-Domain Post empfängt. Dann bleibt nur die Prüfung der Form, und es geht schneller. Sie gelten für den gesamten Aufruf, auch mit async, und sind dieselben wie bei /website und /email.

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, Schweiz, Tschechien, Portugal, Dänemark, Norwegen, Österreich, Slowakei, Kroatien, Griechenland, 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.

Bei einem Stapel aus einem einzigen Land müssen Sie das Land nicht in jedem Element wiederholen: default_country ("DE", "Germany") gilt für die Elemente, die es nicht angeben, bei Adressprüfung, Dublettenbereinigung, Anreicherung (es wählt das Wörterbuch der Vornamen) und Telefonprüfung, auch bei asynchronen Aufträgen. Das im Element angegebene Land hat immer Vorrang; ohne beides ist das Element italienisch.

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).

Die Stufen von precision: Jede tut auch das, was die vorherigen tun.

• 1 Streng: Der Ort, wie er geschrieben ist; in der Straße nur Korrekturen, die die Daten zweifelsfrei bestätigen.
• 2 Eng: Korrigiert zusätzlich falsche Postleitzahlen und Provinzen und erkennt abgekürzte Ortsnamen.
• 3 Normal (Standard): Findet zusätzlich unvollständig geschriebene Namen und verlegt die Adresse in die Gemeinde, in der es die Straße wirklich gibt.
• 4 Weit: Akzeptiert zusätzlich gleich klingende Namen und wählt unter gleichnamigen Straßen die bekannteste. Die Zuverlässigkeit ist nie hoch.
• 5 Maximal: Alles, was sich wiederfinden lässt. Die Zuverlässigkeit ist nie hoch.

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 (Dr.ssa, Avv., …) und Anredeformen fertig für die Korrespondenz – "Egregio Sig. Rossi", "Gentile Dr.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": "Dr.ssa",
    "formal_salutation": "Gentile Dr.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.

Eine Domain, die einen Tastenanschlag von einem bekannten Anbieter entfernt ist, wird je nach precision korrigiert (1-5, Standard 3; 4 und 5 gelten als 3). Bei 1 nur, wenn die geschriebene Domain nicht existiert (gmail.cob, hotmial.ocm); bei 2 auch, wenn sie existiert, aber keine Post empfängt (libreo.it); bei 3 auch, wenn sie E-Mails empfängt: geparkte Domains, echte Organisationen (libera.it, lice.it) und Schreibweisen nach Gehör (gemail.com, jmail.com). Eine falsche Endung bei einer beliebigen Domain (studiorossi.con) wird korrigiert, wenn die richtige Domain E-Mails empfängt. Unterhalb der Stufe des Tippfehlers, die in typo_level zurückkommt, bleibt die Adresse wie geschrieben, und similar_to enthält die vermutlich gemeinte Adresse, mit einem Hinweis. Mit "fix_typos": false, für den ganzen Aufruf oder für ein einzelnes Element, wird kein Tippfehler korrigiert: Die Adresse bleibt wie geschrieben, und die Korrektur erscheint in similar_to. Das dient, wenn die Person bestätigt hat, genau diese Adresse zu wollen.

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":"3790328959 - 011 0000000"}'

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 Adressprü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, Schweiz, Tschechien, Portugal, Dänemark, Norwegen, Österreich, Slowakei, Kroatien, Griechenland, 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 … ]}'

HTTP/1.1 202 Accepted
Location: /api/v1/contact?job=369e46e9e7bb…

{"ok":true,"job":"369e46e9e7bb…","state":"queued","rows":100000,"check":"/api/v1/contact?job=369e46e9e7bb…"}

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

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

Mit format=zip laden Sie stattdessen alle Dateien des Auftrags in einem Zip herunter: die bereinigte Datei, mit Ihren Spalten und den Korrekturen dort eingetragen, wo sie bestätigt sind; die zu prüfenden Zeilen; was sich ändert, Zelle für Zelle; das vollständige Ergebnis; eine README, die sie erklärt. Mit format=zip_xlsx sind dieselben Dateien im Excel-Format.

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.

Der Aufruf, der den Auftrag in die Warteschlange stellt, antwortet mit HTTP 202 und dem Header Location, der auf den Auftrag zeigt. Wenn Sie das Ergebnis nicht mehr brauchen, löschen Sie es mit DELETE unter derselben Adresse: Die Antwort ist HTTP 204, und Dateien und Daten sind weg. Ein Auftrag, der noch in der Warteschlange steht oder verarbeitet wird, antwortet mit 409 job_running: Löschen Sie ihn, sobald er abgeschlossen ist. Wenn Sie ihn nicht löschen, wird der Auftrag nach 30 Tagen von selbst gelöscht. Das gilt auch für das gespeicherte Ergebnis von /dedupe.

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

HTTP/1.1 204 No Content

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 (Adressprü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: Adressprü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 Adressprü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.

Die 402-Antwort enthält außerdem credit.purchase_url: die Seite „Credits“ Ihres Kontos mit dem kleinsten Paket, das den Fehlbetrag deckt, direkt zum Öffnen.

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 verbraucht einen Vorgang. 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.