Dezelfde engine,
in je eigen app.

Eén endpoint per dienst, met dezelfde naam die de dienst op deze site heeft: /contact, /dedupe, /email, /phone, /website, /tax-code, /enrichment. Elk accepteert één element in de body van het verzoek of een lijst in items, tot 500 per aanroep (100 voor websites, die één voor één benaderd moeten worden). Het ontdubbelen is de uitzondering en wil altijd een lijst: het vergelijkt de records met elkaar. Apart staan /suggest, de autocomplete voor formulieren (werkt per sessie terwijl de gebruiker typt, niet in batches), en /credit, dat zegt hoeveel bewerkingen er nog over zijn en in welke staat elke teller is, zonder er een te verbruiken.

Authenticatie

De API-host is www.radaraddress.com. Veldnamen, endpointnamen en waarden zijn Engelse identifiers, in elke taal hetzelfde; labels, redenen en berichten volgen de taal van het verzoek ("language": "de" of ?language=de, of de header Accept-Language, of de taal van het account). De header Content-Language zegt in welke taal het antwoord is gekomen.

De toegang tot de API verloopt via een Bearer-token. Het account is gratis: je maakt het token aan in je account en stuurt het mee in de header van elk verzoek, in deze vorm:

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

Bij het aanmaken kun je het token een optionele vervaldatum geven: na die datum krijgen verzoeken HTTP 401 met code token_expired; zonder vervaldatum blijft het token geldig tot je het intrekt. Je kunt het op elk moment intrekken of opnieuw genereren in je account, waar je ook het laatste gebruik en het aantal afgehandelde verzoeken ziet. Een verzoek zonder token of met een ongeldig token geeft HTTP 401 terug.

De Italiaanse namen, voor wie ze al gebruikt

De API heeft één versie, in het Engels. Wie met de Italiaanse namen heeft geïntegreerd hoeft niets te veranderen: Italiaanse velden worden in elk verzoek geaccepteerd, de endpoints antwoorden ook onder hun Italiaanse naam (/contatto, /deduplica, /codicefiscale, /arricchimento, /telefono, /sito, /suggerisci, /nazioni, /credito), en het antwoord komt met de Italiaanse sleutels en codes voor wie erom vraagt met "language": "it" of www.radaraddress.it aanroept zonder een taal op te geven.

De volledige tabel van de velden: Engels → Italiaans

Engels	Italiaans	Engels	Italiaans
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

Ook de optiewaarden hebben een Italiaanse naam: format nazionale/internazionale, action genera/valida/estrai/confronta/seleziona, foreign dichiarati/rileva, min_level certo/probabile/ambiguo; met "language": "it" komen zo ook level, confidence, state, de codes van outcome en de kolomkoppen van de bestanden. Bij invoer worden ook gangbare synoniemen geaccepteerd (zip, surname, phone_number, date_of_birth…) en dezelfde koppen in de bestanden van bulkopdrachten.

Endpoint contactverificatie

Zet het hele contact recht: het adres volgens de poststandaard van zijn land — in Italië en in de landen waarvan het register in dienst is, worden straat en huisnummer in het nationale adressenregister geverifieerd; elders komt het adres in de postvorm van het land terug —, de naam en — als het verzoek die bevat — de Italiaanse fiscale code, die wordt opgeschoond, aangevuld als alleen het controleteken ontbreekt en vergeleken met achternaam, voornaam, geslacht en geboortedatum. Eén contact per keer, of tot 500 in items: het schema is hetzelfde als bij alle andere endpoints.

Het land geef je op met country_code (ISO 3166-1: IT, DE, FR…) of met country, geschreven zoals het komt: “Germania”, “Germany”, “Deutschland”, “Bondsrepubliek Duitsland”, “UK”, “Holland”. Ontbreekt het, dan wordt Italië verondersteld. In de landen waarvan het register in dienst is — vandaag Frankrijk, Duitsland, Spanje, Nederland, België, Finland, Tsjechië, Portugal, Denemarken, Noorwegen, Oostenrijk, Zwitserland, Slowakije, Kroatië, Roemenië, Hongarije, Slovenië, Ierland, IJsland, Luxemburg, Liechtenstein, San Marino, Monaco, Andorra, Vaticaanstad, de actuele lijst staat onder Landen — worden straat en huisnummer net als in Italië geverifieerd in het nationale adressenregister: postcode bevestigd of aangevuld, coördinaten van het huisnummer in geo, wijk of arrondissement in district waar de stad die heeft (Hamburg-Altstadt, Paris 4e Arrondissement), gemeentecode in territory.municipality_code. In het Italiaans draagt de uitkomst FOREIGN gevolgd door de wijzigingen, in de andere talen alleen de wijzigingen; bestaat de straat maar het nummer niet, dan HOUSE_NUMBER_NOT_FOUND. In de andere landen werken we aan de vorm, en het bericht zegt dat: postcode in het formaat van het land, straatafkortingen uitgeschreven, hoofdletters en plaatsnaam zoals de post van dat land ze schrijft (Hauptstr. 5, München → Hauptstraße 5, MÜNCHEN), met de landregel. In beide gevallen komt address_key terug, de vorm waarmee de ontdubbeling dezelfde straat in twee schrijfwijzen herkent. Met "foreign": "detect" wordt een record zonder land dat in Italië niet gevonden wordt als buitenlands herkend wanneer de tekst dat duidelijk zegt; de standaard declared laat alleen buitenlands wat dat zelf aangeeft. De volledige landencatalogus, met korte en officiële naam, in het Engels en in de taal van het land, is beschikbaar met GET /api/v1/countries en is te bevragen met ?q=Germania, ?q=Deutschland of ?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"}'

Voor de batch: dezelfde velden binnen items; het antwoord is { count, results: [ { id, result } ] } in dezelfde volgorde als verzonden.

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

Hetzelfde endpoint voor een adres in een ander land: country_code volstaat. Hier Hamburg, geverifieerd in het Duitse register, met de wijk en de coördinaten van het huisnummer.

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

Opties die gelden voor de hele aanroep: postal_form (dwingt ook normalized in de postvorm), preserve_original (houdt de naam zoals de gebruiker hem schreef en geeft de canonieke vorm apart), precision 1–5 (standaard 3; boven 3 is de match benaderend en zal de betrouwbaarheid niet high zijn).

Samen met het adres komt city_type, dat zegt of het bezorgadres in een provinciehoofdstad ligt of in een gemeente van de provincie — het verschil dat telt voor wie een campagne per stad opdeelt. provincial_capital is true, false of null als we geen elementen hebben om het te zeggen — en in dat geval gokken we niet.

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

Naast de postcode komt postcode_check: waar hij vandaan komt (source) en hoe precies (precision: house_number het nummer zelf, interpolated de buurnummers van dezelfde straat, street de meerderheid van de straat, locality, municipality), hoeveel huisnummers het zeggen (house_numbers) en met welke overeenstemming (agreement, van 0 tot 1). Ontbreekt een bevestiging voor dat nummer, dan draagt de uitkomst POSTCODE_UNCONFIRMED en is confirmed false: de postcode blijft zoals opgegeven, als hij bij de stad hoort, en moet gecontroleerd worden.

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

Ook de coördinaten komen terug, in geo (breedte- en lengtegraad WGS84), en de territoriale identificatoren in territory: in Italië de ISTAT-code en de kadastrale code van de gemeente, de CAB en de nationale identificator van de straat; in de andere landen country en de gemeentecode uit het nationale register (municipality_code). Het veld precision zegt tot welk niveau we zijn gekomen: house_number als het huisnummer gegeorefereerd is, interpolated als het exacte nummer ontbreekt en het punt geschat is, street als we het punt van de straat hebben, municipality als we alleen het centrum van de gemeente hebben. source zegt waar het punt vandaan komt: anncsu is het Italiaanse nationale register, inspire het nationale register van het land, osm OpenStreetMap: in dat geval zijn de gegevens © OpenStreetMap contributors, ODbL-licentie, en moet de bronvermelding worden overgenomen als je ze publiceert. Waar het register van een land een bronvermelding vereist, staat die in het bericht. In de CSV van bulkopdrachten zijn het de kolommen latitude, longitude, geo_precision, istat_code en 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" } }

Verdieping, trap en woning uit het adres komen ook terug als eigen gegevens in sub_address: een lijst van paren type en value, gelezen volgens de postregels van het land (in Duitsland na “//”, in Frankrijk op een eigen regel, in Portugal “3º Esq”). De typen zijn unit (woning), staircase (trap), floor (verdieping), block, building, building_number en block_number. De adresregel blijft in de vorm van het land. Wat we niet herkennen, blijft staan zoals het geschreven was en komt niet in de lijst: we raden niet. Staat de opgegeven eenheid bekend op dat huisnummer, dan is sub_address_confirmed true; anders null, nooit false: dat we haar niet vinden, betekent niet dat ze fout is.

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

Endpoint ontdubbelen

Herkent de records die naar dezelfde persoon op hetzelfde adres verwijzen, ook als ze anders geschreven zijn: verkleinvormen en gelijkwaardige namen (Dany ≈ Daniela), achternaam en voornaam omgewisseld, afkortingen ("V. Roma" ≈ "Via Roma"), typefouten. De vergelijking van de adressen loopt via de normalisatie-engine: twee schrijfwijzen van dezelfde straat vallen samen op de canonieke vorm vóór de vergelijking. Maximaal 500 contacten per aanroep (records + referentie); voor grotere lijsten gebruik je de bulkopdracht vanuit je account.

Adresboeken. Een contact in een adresboek (Contacten van Apple, Google, Outlook: het vCard-model) heeft meerdere adressen, telefoonnummers en e-mailadressen, elk met een label. Het endpoint accepteert ze zo, zonder limiet: addresses is een lijst van objecten met type en de gebruikelijke velden; phones en emails zijn lijsten waarin elk element alleen het gegeven is ("340 7491386") of {"type": "work", "value": "02 66710423"}, ook gemengd; de gebruikelijke platte velden blijven geldig en gelden als eerste adres en eerste contactgegeven. Twee contacten zijn dezelfde persoon als een willekeurig paar van hun adressen overeenkomt (het kantoor van de een met het enige adres van de ander), of als ze dezelfde naam hebben en een telefoonnummer of e-mailadres gemeen hebben, op welke positie en met welk label dan ook. Het label weegt niet mee in de match: het komt terug zoals het binnenkwam, plus type_normalized in het vCard-vocabulaire (home, work, cell…), zodat de app weet waar ze moet terugschrijven. Eén contact is één bewerking, hoeveel adressen en contactgegevens het ook heeft.

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

Het antwoord groepeert de dubbelen in groups: elke groep somt de id's van haar members op, geeft aan welke je bewaart (main_record) en stelt het geconsolideerde record voor: de beste naam en de vereniging van adressen en contactgegevens (addresses, phones, emails), elk met zijn type, met provenance (uit welke contacten het komt) en ontdubbeld: dezelfde straat in twee schrijfwijzen is één adres, hetzelfde nummer met twee labels één nummer. Contacten zonder overeenkomst staan in singles, als objecten {id, outcome}: met outcome INTERNAL_DUPLICATE heeft het contact geen dubbelen met andere, maar wel binnen zichzelf (adres twee keer geschreven, nummer herhaald), en draagt het zijn samengevoegde record. Het herkent dezelfde straat op verschillende manieren geschreven ("V. Leopardi 4" ≈ "Via Giacomo Leopardi 4"), de automatisch herstelde postcode en achternaam en voornaam omgewisseld.

Endpoint Italiaanse fiscale code

Drie acties op de Italiaanse fiscale code van natuurlijke personen: generate uit de persoonsgegevens, validate een bestaande code (formaat, controleteken en omocodia), extract de informatie die erin zit — geboortedatum, leeftijd, geslacht, gemeente of buitenlands land van geboorte. Daarnaast controleert compare of een code overeenkomt met de opgegeven persoonsgegevens. Dekt de kadastrale codes van alle Italiaanse gemeenten en van de buitenlandse landen. Achternaam en voornaam moeten in Latijnse tekens worden doorgegeven: voor wie een naam in een ander alfabet heeft, wordt de code berekend op de transliteratie op het document, die niet uniek is (Dmitrij/Dmitry); een niet-Latijnse naam geeft cognome_non_latino of nome_non_latino terug, en bij compare krijgt een verschil in de naam van iemand die in het buitenland geboren is een opmerking over een mogelijk andere transliteratie.

De eerste 500 lichte bewerkingen per maand zijn gratis (fiscale code inbegrepen), en het gratis tegoed is één en hetzelfde in elke gebruiksvorm: wat je hier, op de website en in bulkbestanden doet, telt op hetzelfde tegoed. Daarboven betaal je de prijs van de lichte bewerkingen (zie prijzen).

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

Voor volumes: { "action": "validate", "items": [ … ] } verwerkt tot 500 elementen per aanroep, elk met zijn eigen correlatie-id. De extractie markeert met ambiguous_year de gevallen waarin de twee cijfers van het jaar de eeuw niet onderscheiden (1926 of 2026).

Elk antwoord draagt outcome, reason, notes en comments in de taal van het verzoek: GENERATED bij generate, leeg bij een geldige code in validate, MATCH of MISMATCH bij compare (met differences: de afwijkende velden). Als de code de controles niet doorstaat is de uitkomst een van de TAX_CODE_*-codes hieronder en geeft error de korte vorm (check_digit, length, format, homocode, month, date, place, empty); bij generate zegt het welk gegeven ontbreekt of niet oplosbaar is (last_name, first_name, gender, birth_date, birth_place, ambiguous_place met options, last_name_non_latin). suggestion draagt de juiste code als de controle hem kan reconstrueren.

Endpoint verrijking

Verrijkt een naam: geslacht afgeleid uit de voornaam, soort subject (natuurlijke of rechtspersoon), genormaliseerde titel (Dott.ssa, Avv., …) en aanhefvormen klaar voor correspondentie — "Egregio Sig. Rossi", "Gentile Dott.ssa Bianchi", "Spett.le" voor bedrijven, "Gentile Famiglia" voor gezinnen, "Caro/Cara" voor het informele register. Herkent ook de huwelijksvorm in de achternaam ("Rossi in Verdi" → vrouw, met de details van de twee achternamen). Het veld gender accepteert ook geschreven vormen (‘maschio’, ‘donna’, ‘Sig.ra’, ‘male’); X staat voor een organisatie en G voor een gezin of een stel. Ontbreekt de titel, dan leiden we hem af uit profession (het beroep) of uit education, als die zijn opgegeven. De woordenboeken zijn Italiaans.

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

In batches: { "items": [ … ] }, tot 500 per aanroep. De uitkomst is ENRICHED (geslacht en aanhef ingesteld), LEGAL_PERSON (bedrijf of organisatie: behandeld als bedrijfsnaam) of PARTIAL (voornaam ontbreekt, of geslacht niet af te leiden): reason zegt waarom, comments wat toe te voegen om het af te maken.

Endpoint e-mailverificatie

Controleert een e-mailadres: syntaxis, bestaan van het domein (MX/A-records), typefouten in veelgebruikte domeinen met een voorgestelde correctie (gmial.com → gmail.com), wegwerpdomeinen, algemene adressen (info@, administratie@: niet van een persoon). We doen geen SMTP-verificatie van de afzonderlijke mailbox: een opdringerige en onbetrouwbare praktijk. Batch items tot 500; "dns": false slaat de domeinlookup over.

Een zekere typefout wordt meteen gecorrigeerd: als het adres zoals geschreven niet eens een adres is (naam@domein,nl met een komma) of als de correctie bij een bekende provider uitkomt (gmai.com → gmail.com, ook op één letter afstand als het geschreven domein geen mail ontvangt), komt email gecorrigeerd terug, bevat corrected_from wat er stond en is de uitkomst MODIFIED EMAIL_DOMAIN. Een mogelijke typefout op een willekeurig domein (rossi.con) blijft een voorstel: EMAIL_TYPO met de correctie in suggestion, en de controles (domain_exists, domain_checked) worden daarop uitgevoerd; het adres zoals geschreven wordt niet gecontroleerd.

Endpoint telefoonverificatie

Controleert een nummer zonder iemand te bellen: vorm, klasse en type, lengte volgens het nummerplan, netnummergebied van het vaste nummer en de operator aan wie het blok oorspronkelijk is toegewezen. De class is de lezing die je nodig hebt om een lijst te bewerken: mobile (je kunt er een sms naar sturen), landline (je belt het tijdens kantooruren), special (geen nummer van een persoon: noodnummers, openbaar nut, gratis en betaalde servicenummers), foreign voor nummers met een internationale landcode. Als we ook de precieze dienst herkennen, zegt type dat (gratis nummer, betaald servicenummer, gedeelde kosten, openbaar nut). De Italiaanse landcode zonder + (39347…, een klassieke fout in exports) halen we weg als de cijfers geen twijfel laten — 3934567890 blijft het mobiele nummer dat het is. Staan er meerdere nummers in hetzelfde veld (‘347… - 338…’), dan splitsen we ze: ze komen terug als phone, phone2, phone3, en phone is nooit leeg als er minstens één nummer is. Met "format": "international" komt het Italiaanse nummer eruit als +39…; de standaard national laat het kaal en zet de landcode alleen bij buitenlandse nummers. Voor buitenlandse nummers krijg je ook e164, het land van de landcode in country_code, en de netnul na de landcode wordt weggehaald (‘+44 (0)20…’ en ‘+44 20…’ geven hetzelfde nummer). Met country_code (of country) in de aanroep of in het element wordt een nummer zonder landcode gelezen als nationaal nummer van dat land: ‘020 7946 0958’ in een Brits record is Londen, niet Milaan. Zonder land blijft het Italiaans. Batch items tot 500.

Een nummer uit het land van het record is niet „buitenlands”: waar we het nummerplan kennen krijgt het zijn class (mobile, landline, special), met format national blijft het zonder landcode in de vorm van zijn land (netnummer-nul inbegrepen), en naast e164 komt national_number terug. PHONE_FOREIGN en class foreign blijven voor nummers uit een ander land dan dat van het 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 websiteverificatie

Controleert of het adres goed geschreven is en of de site echt reageert: bestaan van het domein, HTTP-verzoek met gevolgde redirects, eindcode, geldigheid van het certificaat. Geen oordeel over de inhoud. Ook hier komen meerdere adressen in hetzelfde veld terug als website, website2, website3. Met "network": false controleren we alleen de vorm, zonder de site te benaderen. Batch items tot 100: elke controle opent een verbinding, dus de batch is kleiner dan bij de andere endpoints.

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 adres-autocomplete

Begin je van nul? De widget ra-suggerisci.js en een kleine proxy op je server zijn genoeg: het token komt nooit in de browser.

Suggesties terwijl de gebruiker typt in het adresveld van je formulier: het hele Italiaanse stratenregister, met de naam aangevuld (‘via verdi’ → ‘Via Giuseppe Verdi’), gemeente en provincie; de postcode komt met de selectie, in de grote steden met postzones de juiste van het huisnummer. Het werkt per sessie: de client genereert een UUID voor elk adres dat wordt ingevuld, de suggestiequery's zijn gratis, en je betaalt één contactverificatie wanneer de gebruiker kiest en de velden gevuld worden (actie select, die het record teruggeeft zoals de engine het al genormaliseerd heeft). De velden die al in het formulier zijn ingevuld — ook gedeeltelijk — reizen mee als context en verfijnen de suggesties.

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

Is de straat gekozen, dan wordt het huisnummer aangevuld: door street_id mee te geven met het gedeeltelijke huisnummer krijg je de bestaande huisnummers van die straat, met exists waar/onwaar om het getypte nummer te valideren — en de selectie kan met het huisnummer herhaald worden zonder nieuwe afschrijving: de afschrijving is per sessie en per straat, niet per klik; een andere straat in dezelfde sessie is een nieuwe afschrijving. Huisnummers worden alleen aangevuld in de sessie die die straat heeft geselecteerd. In steden met postzones bepaalt het huisnummer de exacte postcode.

Het API-token komt nooit in de browser: de kant-en-klare widget (ra-suggerisci.js) roept een kleine proxy op je server aan, die het token toevoegt en doorstuurt. Elke sessie staat tot 30 aanroepen toe en duurt 10 minuten; sessies zonder selectie zijn gratis tot 200 per dag per token, plus vijf per selectie. Widget, kant-en-klare proxy en voorbeeldform staan in de kit van Je eigen form.

Werkt in elk land in dienst (vandaag Frankrijk, Duitsland, Spanje, Nederland, België, Finland, Tsjechië, Portugal, Denemarken, Noorwegen, Oostenrijk, Zwitserland, Slowakije, Kroatië, Roemenië, Hongarije, Slovenië, Ierland, IJsland, Luxemburg, Liechtenstein, San Marino, Monaco, Andorra, Vaticaanstad; de actuele lijst staat onder Landen): met country_code of country komen de suggesties uit het register van dat land, en de tekst schrijf je zoals men het daar schrijft — straat, huisnummer, postcode en plaats desnoods in één veld: «kalverstraat 92 amst», «92 rue de rivoli paris», in Nederland «1012PH 92». Elk antwoord bevat parsed, dus hoe de server straat (street), huisnummer (house_number) en postcode (postcode) heeft gelezen: je formulier weet waar het nummer staat zonder de regels van het land te kennen. Suggesties bevatten straat, plaats, eventueel de woonkern en source (registry, of osm waar het nationale register niets publiceert); postcode en huisnummers staan nooit in de suggesties: die komen met de selectie, die door de engine gaat en hetzelfde record teruggeeft als /contact (postcode bevestigd door het register, geo op huisnummer). Bij de selectie kun je ook postcode meegeven, die in het formulier is ingevuld. attribution is de bronvermelding die naast de suggesties moet staan: de licentie van het register vereist dat. Ontbreekt het land, dan wordt IT aangenomen; voor een land buiten dienst blijft het antwoord HTTP 200 met supported:false en hints:[], zonder sessie en zonder afboeking. Een sessie hoort bij één land: verandert dat, dan maakt de client een nieuwe UUID (anders 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"}

Grote volumes: de asynchrone opdracht

Normale aanroepen antwoorden direct, en daarom hebben ze een limiet op het aantal elementen — aan een HTTP-verzoek dat minuten duurt, heeft niemand iets. De limieten volgen hoe zwaar de bewerking is:

Boven die aantallen hoef je de lijst niet met de hand op te knippen: je voegt "async": true toe en de aanroep komt direct terug met een code, terwijl de verwerking in dezelfde wachtrij gaat als de bestandsuploads. Tot 100.000 elementen per aanroep, en in Mijn opdrachten verschijnt er maar één.

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}

Daarna lees je het terug wanneer je wilt, en het resultaat komt als JSON of 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

Onder de 5.000 rijen komt het resultaat ook terug in results binnen de JSON; daarboven download je het als CSV. De afschrijving gebeurt wanneer de opdracht in de wachtrij komt, en het niet-verwerkte deel gaat terug naar je tegoed als de opdracht stopt. Het token moet aan een account gekoppeld zijn: de opdracht komt in jouw wachtrij terecht.

Uitkomstcodes

Elk antwoord bevat het veld outcome: een lijst van sleutelwoorden, leeg als er niets te melden is. Het patroon is altijd <conditions> [MODIFIED <types>] — de voorwaarden vooraan, de wijzigingen achteraan — en geldt voor alle diensten. Daarnaast vind je outcome_label (of kind) met ok, modified, warning, error, en reason met de uitleg in één regel. De codes zijn identifiers: ze worden vergeleken, niet vertaald; met "language": "it" komen de Italiaanse codes (LOCALITA_NON_TROVATA MODIFICATO CAP INDIRIZZO), woord voor woord dezelfde.

Adres (contactverificatie)

Italiaanse fiscale code

Op het endpoint /tax-code hebben dezelfde controles eigen 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 — omdat de fiscale code daar het onderwerp van de controle is, niet een veld van het record.

Verrijking

E-mail

Telefoon

Website

Wat elke aanroep verbruikt

Elke aanroep verbruikt bewerkingen van de teller van de dienst: contactverificatie (/contact, /suggest bij de selectie), ontdubbelen (/dedupe) en lichte bewerkingen (/email, /phone, /website, /enrichment, /tax-code boven het gratis tegoed). Bewerkingen koop je in bundels die blijven, of met een maandabonnement; de prijs per 1.000 daalt met de grootte en staat op de pagina prijzen. Elke maand zijn 50 contactverificaties, 100 records in het ontdubbelen en 500 lichte bewerkingen gratis.

Elk antwoord zegt wat het heeft verbruikt en waarvan: het veld credit van de JSON (counter, charged, free, subscription en packs met de afgeschreven bewerkingen en het restant, available, auto_topup met het aantal automatisch gekochte bundels, note) en de headers X-RA-Charged, X-RA-Available en, wanneer het in werking treedt, X-RA-Auto-Topup. Als de beschikbare bewerkingen de aanroep niet dekken en het automatisch opwaarderen van de teller niet actief is (of mislukt), is het antwoord 402 payment_required en wordt er niets verwerkt.

Om te weten hoeveel bewerkingen er nog over zijn zonder er een te verbruiken is er GET /api/v1/credit. Voor elk van de drie tellers (contact, dedupe, light) geeft het available terug, de gratis bewerkingen (free) die deze maand nog over zijn en de datum waarop ze op nul gaan (de 1e), het subscription (restant, grootte, verlenging), de actieve packs één voor één met wat er nog over is (ze verlopen niet) en hoeveel je er hebt gekocht, de auto_topup (actief, grootte, plafond en uitgegeven deze maand in euro), het gebruik (used deze maand, totalen, laatste gebruik) en vooral de state, want een nul alleen zegt niet of je tegoed op is of dat je die dienst niet gebruikt: never_used, free (nooit gekocht, je werkt binnen de gratis bewerkingen van de maand), free_used_up, active, awaiting_renewal, used_up (je hebt eerder gekocht en er is niets meer over: opwaarderen), met een warning. Bovenaan somt needs_topup de tellers op waar actie nodig is en zegt endpoint welke teller elk endpoint verbruikt. Vereist het token van een 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", … } }

Je betaalt per gecontroleerd element, niet per aanroep: staan er in een veld twee telefoonnummers of twee e-mailadressen, dan controleren we ze allemaal (tot drie per rij) en betaalt elk zijn eigen prijs. Een batchaanroep verbruikt zoveel als de bewerkingen die hij bevat. Is het tegoed op en heb je automatisch opwaarderen niet actief, dan antwoordt de API HTTP 402 (onvoldoende tegoed); boven de rate limit antwoordt hij HTTP 429 met retry_after. Je koopt een bundel in je account, of activeert een abonnement om minder per bewerking te betalen.