Samme motor,
inde i din app.

Ét endpoint pr. tjeneste, med samme navn, som tjenesten har på dette site: /contact, /dedupe, /email, /phone, /website, /tax-code, /enrichment. Hvert accepterer ét element i forespørgslens body eller en liste i items, op til 500 pr. kald (100 for websites, som skal kontaktes ét ad gangen). Deduplikeringen er undtagelsen og vil altid have en liste: den sammenligner posterne med hinanden. For sig står /suggest, autofuldførelsen til formularer (den arbejder pr. session, mens brugeren skriver, ikke i partier), og /credit, som fortæller, hvor mange behandlinger der er tilbage, og hvilken tilstand hver tæller er i, uden at bruge nogen.

Autentificering

API'ets host er www.radaraddress.com. Felt-, endpoint- og værdinavne er engelske identifikatorer, de samme på alle sprog; etiketter, årsager og meddelelser følger forespørgslens sprog ("language": "de" eller ?language=de, eller headeren Accept-Language, eller kontoens sprog). Headeren Content-Language siger, hvilket sprog svaret kom på.

Adgang til API'et sker med Bearer-token. Kontoen er gratis: du opretter tokenet i dit kontoområde og medsender det i headeren på hver forespørgsel i denne form:

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

Når du opretter det, kan du give tokenet en valgfri udløbsdato: efter den dato får forespørgsler HTTP 401 med koden token_expired; uden udløb gælder tokenet, indtil du tilbagekalder det. Du kan tilbagekalde eller genskabe det når som helst fra dit kontoområde, hvor du også ser seneste brug og antallet af besvarede forespørgsler. En forespørgsel uden token eller med et ugyldigt token returnerer HTTP 401.

De italienske navne, for dem, der allerede bruger dem

API'et har én version, på engelsk. Den, der har integreret med de italienske navne, behøver ikke ændre noget: italienske felter accepteres i hver forespørgsel, endpoints svarer også under deres italienske navne (/contatto, /deduplica, /codicefiscale, /arricchimento, /telefono, /sito, /suggerisci, /nazioni, /credito), og svaret kommer ud med de italienske nøgler og koder til den, der beder om det med "language": "it" eller kalder www.radaraddress.it uden at angive et sprog.

Den fulde felttabel: engelsk → italiensk

engelsk	italiensk	engelsk	italiensk
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

Også valgmulighedernes værdier har et italiensk navn: format nazionale/internazionale, action genera/valida/estrai/confronta/seleziona, foreign dichiarati/rileva, min_level certo/probabile/ambiguo; med "language": "it" gælder det også level, confidence, state, koderne i outcome og filoverskrifterne. Almindelige synonymer accepteres også som input (zip, surname, phone_number, date_of_birth…), og de samme overskrifter i batchjobbenes filer.

Endpoint for kontaktverificering

Retter hele kontakten: adressen i landets poststandard — i Italien og i landene med registret i drift verificeres vej og husnummer i det nationale adresseregister; andre steder kommer adressen ud i landets postform —, navnet og — hvis forespørgslen indeholder det — det italienske skattenummer (codice fiscale), som renses, fuldføres, når kun kontroltegnet mangler, og sammenholdes med efternavn, fornavn, køn og fødselsdato. Én kontakt ad gangen, eller op til 500 i items: skemaet er det samme som for alle andre endpoints.

Landet angives med country_code (ISO 3166-1: IT, DE, FR…) eller med country, skrevet på enhver måde: »Germania«, »Germany«, »Deutschland«, »Forbundsrepublikken Tyskland«, »UK«, »Holland«. Mangler det, antages Italien. I landene med registret i drift — i dag Frankrig, Tyskland, Spanien, Nederlandene, Belgien, Finland, Tjekkiet, Portugal, Danmark, Norge, Østrig, Schweiz, Slovakiet, Kroatien, Rumænien, Ungarn, Slovenien, Irland, Island, Luxembourg, Liechtenstein, San Marino, Monaco, Andorra, Vatikanstaten, den opdaterede liste står under Lande — verificeres vej og husnummer i det nationale adresseregister præcis som i Italien: postnummer bekræftet eller udfyldt, husnummerets koordinater i geo, bydel eller arrondissement i district, hvor byen har dem (Hamburg-Altstadt, Paris 4e Arrondissement), kommunekode i territory.municipality_code. På italiensk indeholder resultatet FOREIGN efterfulgt af ændringerne, på de andre sprog kun ændringerne; findes vejen, men ikke nummeret, HOUSE_NUMBER_NOT_FOUND. I de andre lande arbejder vi på formen, og det siger meddelelsen: postnummer i landets format, vejforkortelser skrevet ud, store bogstaver og bynavn, som postvæsenet i det land skriver dem (Hauptstr. 5, Munich → Hauptstraße 5, MÜNCHEN), med landelinjen. I begge tilfælde kommer address_key tilbage, den form, som deduplikeringen bruger til at genkende samme vej skrevet på to måder. Med "foreign": "detect" genkendes en post uden land, som ikke findes i Italien, som udenlandsk, når teksten siger det tydeligt; standarden declared lader kun det være udenlandsk, som selv erklærer det. Det fulde landekatalog, med kort og officielt navn, på engelsk og på landets sprog, fås med GET /api/v1/countries og kan forespørges med ?q=Germania, ?q=Deutschland eller ?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"}'

Til partiet de samme felter inde i items; svaret er { count, results: [ { id, result } ] } i samme rækkefølge som sendt.

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

Samme endpoint til en adresse i et andet land: country_code er nok. Her Hamborg, verificeret i det tyske register, med bydelen og husnummerets koordinater.

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

Valgmuligheder, der gælder for hele kaldet: postal_form (tvinger også normalized i postform), preserve_original (beholder navnet, som brugeren skrev det, og viser det kanoniske for sig), precision 1–5 (standard 3; over 3 er matchet omtrentligt, og pålideligheden bliver ikke high).

Sammen med adressen kommer city_type, som siger, om leveringsstedet ligger i en provinshovedstad eller i en by i provinsen — forskellen, der betyder noget for den, der segmenterer en kampagne efter by. provincial_capital er true, false eller null, når vi ikke har grundlag for at sige det — og i så fald gætter vi ikke.

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

Ved siden af postnummeret kommer postcode_check: hvor det kommer fra (source) og hvor præcist (precision: house_number selve nummeret, interpolated nabonumrene i samme gade, street gadens flertal, locality, municipality), hvor mange husnumre der siger det (house_numbers) og med hvilken enighed (agreement, 0 til 1). Mangler bekræftelse for det nummer, bærer resultatet POSTCODE_UNCONFIRMED og confirmed er false: postnummeret beholdes som angivet, hvis det hører til byen, og bør tjekkes.

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

Koordinaterne kommer også tilbage, i geo (WGS84 bredde- og længdegrad), og de territoriale identifikatorer i territory: i Italien kommunens ISTAT-kode og matrikelkode, CAB og vejens nationale identifikator; i de andre lande country og kommunens kode i det nationale register (municipality_code). Feltet precision siger, hvilket niveau vi nåede: house_number, når husnummeret er georefereret, interpolated, når det præcise nummer mangler og punktet er anslået, street, når vi har vejens punkt, municipality, når vi kun har kommunens centrum. source siger, hvor punktet kommer fra: anncsu er det italienske nationale register, inspire landets nationale register, osm OpenStreetMap: i så fald er dataene © OpenStreetMap contributors, ODbL-licens, og krediteringen skal gengives, hvis du offentliggør dem. Hvor et lands register kræver en kreditering, kommer den ud i meddelelsen. I CSV-filen fra batchjob er det kolonnerne latitude, longitude, geo_precision, istat_code og 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, opgang og lejlighed i adressen kommer også tilbage som egne data i sub_address: en liste med par af type og value, læst efter landets postregler (i Tyskland efter »//«, i Frankrig på sin egen linje, i Portugal »3º Esq«). Typerne er unit (lejlighed), staircase (opgang), floor (etage), block, building, building_number og block_number. Adresselinjen står i landets form. Det, vi ikke genkender, står, som det var skrevet, og kommer ikke med i listen: vi gætter ikke. Når den angivne enhed findes på husnummeret, er sub_address_confirmed true, ellers null, aldrig false: at vi ikke finder den, betyder ikke, at den er forkert.

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

Endpoint for deduplikering

Genkender de poster, der vedrører samme person på samme adresse, også når de er skrevet forskelligt: kælenavne og navneækvivalenser (Dany ≈ Daniela), efternavn og fornavn byttet om, forkortelser ("V. Roma" ≈ "Via Roma"), tastefejl. Sammenligningen af adresser går gennem normaliseringsmotoren: to stavemåder af samme vej falder sammen til den kanoniske form før sammenligningen. Højst 500 kontakter pr. kald (poster + reference); til større lister bruger du batchjobbet fra dit kontoområde.

Adressebøger. En kontakt i en adressebog (Apple Kontakter, Google, Outlook: vCard-modellen) har flere adresser, telefonnumre og e-mails, hver med en etiket. Endpointet accepterer dem, som de er, uden loft: addresses er en liste af objekter med type og de sædvanlige felter; phones og emails er lister, hvor hvert element er den rene værdi ("340 7491386") eller {"type": "work", "value": "02 66710423"}, også blandet; de sædvanlige flade felter er stadig gyldige og tæller som første adresse og første kontaktoplysning. To kontakter er samme person, hvis et hvilket som helst par af deres adresser matcher (den enes kontor med den andens eneste adresse), eller hvis de har samme navn og et telefonnummer eller en e-mail til fælles, uanset placering og etiket. Etiketten vejer ikke i matchet: den kommer tilbage, som den kom ind, plus type_normalized i vCard-ordforrådet (home, work, cell…), så appen ved, hvor den skal skrive tilbage. Én kontakt er én behandling, uanset hvor mange adresser og kontaktoplysninger den har.

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

Svaret grupperer dubletterne i groups: hver gruppe oplister id'erne på sine members, siger, hvilken der skal beholdes (main_record), og foreslår den konsoliderede record: det bedste navn og foreningen af adresser og kontaktoplysninger (addresses, phones, emails), hver med sin type, med provenance (hvilke kontakter den kommer fra) og deduplikeret: samme vej i to stavemåder er én adresse, samme nummer med to etiketter ét nummer. Kontakter uden match står i singles, som objekter {id, outcome}: med outcome INTERNAL_DUPLICATE har kontakten ingen dubletter med andre, men nogle i sig selv (adresse skrevet to gange, gentaget nummer), og indeholder sin flettede record. Den genkender samme vej skrevet på forskellige måder ("V. Leopardi 4" ≈ "Via Giacomo Leopardi 4"), postnummeret rettet automatisk og efternavn og fornavn byttet om.

Endpoint for italiensk skattenummer

Tre handlinger på fysiske personers italienske skattenummer (codice fiscale): generate ud fra persondataene, validate en eksisterende kode (format, kontroltegn og omocodia), extract de oplysninger, den indeholder — fødselsdato, alder, køn, fødekommune eller fødeland i udlandet. Dertil tjekker compare, at en kode passer til de oplyste persondata. Den dækker matrikelkoderne for alle italienske kommuner og for udlandet. Efternavn og fornavn skal sendes med latinske bogstaver: for en person med navn i et andet alfabet beregnes koden på den translitteration, der står i dokumentet, og som ikke er entydig (Dmitrij/Dmitry); et ikke-latinsk navn returnerer cognome_non_latino eller nome_non_latino, og i compare giver en forskel i navnet på en person født i udlandet en note om en muligvis anden translitteration.

De første 500 lette behandlinger om måneden er gratis (skattenummer inklusive), og kvoten er én og samme på tværs af alle måder at bruge tjenesten på: det, du gør her, på websitet og i batchfiler, tæller på samme kvote. Derudover betales lette behandlinger til deres pris (se priser).

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

Til volumener: { "action": "validate", "items": [ … ] } behandler op til 500 elementer pr. kald, hvert med sit eget korrelations-id. Udtrækket markerer med ambiguous_year de tilfælde, hvor årets to cifre ikke afgør århundredet (1926 mod 2026).

Hvert svar bærer outcome, reason, notes og comments på forespørgslens sprog: GENERATED for generate, tomt for en gyldig kode i validate, MATCH eller MISMATCH for compare (med differences: felterne, der afviger). Når koden ikke består kontrollerne, er udfaldet en af TAX_CODE_*-koderne nedenfor, og error giver kortformen (check_digit, length, format, homocode, month, date, place, empty); ved generate siger den, hvilken oplysning der mangler eller ikke kan løses (last_name, first_name, gender, birth_date, birth_place, ambiguous_place med options, last_name_non_latin). suggestion bærer den korrekte kode, når kontrollen kan genopbygge den.

Endpoint for berigelse

Beriger et navn: køn udledt af fornavnet, type af subjekt (fysisk eller juridisk person), normaliseret titel (Dott.ssa, Avv., …) og tiltaleformer klar til korrespondance — "Egregio Sig. Rossi", "Gentile Dott.ssa Bianchi", "Spett.le" til virksomheder, "Gentile Famiglia" til husstande, "Caro/Cara" til den uformelle tone. Den genkender også gift-navneformen i efternavnet ("Rossi in Verdi" → kvinde, med de to efternavne specificeret). Feltet gender accepterer også skrevne former (»maschio«, »donna«, »Sig.ra«, »male«); X markerer en organisation og G en familie eller et par. Mangler titlen, udleder vi den fra profession (erhvervet) eller fra education, når der er angivet en. Ordbøgerne er italienske.

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

I bundter: { "items": [ … ] }, op til 500 pr. kald. Udfaldet er ENRICHED (køn og hilsner sat), LEGAL_PERSON (virksomhed eller organisation: behandles som firmanavn) eller PARTIAL (fornavn mangler, eller kønnet kan ikke udledes): reason siger hvorfor, comments hvad der skal tilføjes.

Endpoint for e-mailverificering

Verificerer en e-mailadresse: syntaks, domænets eksistens (MX/A-records), tastefejl i almindelige domæner med foreslået rettelse (gmial.com → gmail.com), engangsdomæner, rollebaserede adresser (info@, regnskab@: ikke en person). Vi laver ikke SMTP-verificering af den enkelte postkasse, en påtrængende og upålidelig praksis. Batch items op til 500; "dns": false springer domæneopslaget over.

En sikker tastefejl rettes uden videre: når adressen, som den er skrevet, ikke engang er en adresse (name@domain,com med komma), eller når rettelsen lander på en velkendt udbyder (gmai.com → gmail.com, også ét bogstav fra, når domænet, som det er skrevet, ikke modtager post), kommer email ud rettet, corrected_from indeholder det skrevne, og resultatet er MODIFIED EMAIL_DOMAIN. En mulig tastefejl på et hvilket som helst andet domæne (rossi.con) forbliver et forslag: EMAIL_TYPO med rettelsen i suggestion, og kontrollerne (domain_exists, domain_checked) køres på den; adressen, som den er skrevet, er ikke verificeret.

Endpoint for telefonverificering

Tjekker et nummer uden at ringe til nogen: form, klasse og type, længde efter nummerplanen, fastnettets område og den operatør, blokken oprindeligt blev tildelt. class er den læsning, du skal bruge for at arbejde med en liste: mobile (du kan sende en sms), landline (du ringer i kontortiden), special (ikke en persons nummer: nød-, offentlige, gratis- og overtaksterede numre), foreign for numre med landekode. Når vi også genkender den præcise tjeneste, siger type det (gratisnummer, overtakst, delt takst, offentlig tjeneste). Den italienske landekode skrevet uden + (39347…, en klassisk eksportfejl) fjernes, når cifrene ikke efterlader tvivl — 3934567890 forbliver den mobil, det er. Står der flere numre i samme felt (»347… - 338…«), deler vi dem op: de kommer tilbage som phone, phone2, phone3, og phone er aldrig tom, når der er mindst ét nummer. Med "format": "international" kommer det italienske nummer ud som +39…; standarden national lader det stå nøgent og sætter kun landekode på udenlandske numre. For udenlandske numre får du også e164, landekodens land i country_code, og nullet efter landekoden fjernes (»+44 (0)20…« og »+44 20…« giver samme nummer). Med country_code (eller country) i kaldet eller i elementet læses et nummer skrevet uden landekode som et nationalt nummer i det land: »020 7946 0958« i en britisk post er London, ikke Milano. Uden land forbliver det italiensk. Batch items op til 500.

Et nummer fra postens eget land er ikke »udenlandsk«: hvor vi kender nummerplanen, får det sin class (mobile, landline, special), med format national forbliver det uden landekode i sit lands form (nullet foran inklusive), og national_number returneres ved siden af e164. PHONE_FOREIGN og class foreign gælder fortsat for numre fra et andet land end postens.

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 for websiteverificering

Tjekker, at adressen er skrevet korrekt, og at sitet rent faktisk svarer: domænets eksistens, HTTP-forespørgsel med omdirigeringer fulgt, slutkode, certifikatets gyldighed. Ingen vurdering af indholdet. Også her kommer flere adresser i samme felt tilbage som website, website2, website3. Med "network": false tjekker vi kun formen, uden at kontakte sitet. Batch items op til 100: hvert tjek åbner en forbindelse, så partiet er mindre end på de andre 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 for adresse-autofuldførelse

Starter du fra bunden? Widgetten ra-suggerisci.js og en lille proxy på din server er alt, hvad der skal til: tokenet kommer aldrig ud i browseren.

Forslag, mens brugeren skriver en adresse i din formular: hele det italienske vejregister, med navnet fuldført (»via verdi« → »Via Giuseppe Verdi«), kommune og provins; postnummeret kommer med valget, i de store zoneinddelte byer det rigtige for husnummeret. Det virker pr. session: klienten genererer et UUID for hver adresse, der udfyldes, forslagsforespørgslerne er gratis, og du betaler én kontaktverificering, når brugeren vælger, og felterne udfyldes (handlingen select, som returnerer posten allerede normaliseret af motoren). De felter, der allerede er udfyldt i formularen — også delvist — sendes med som kontekst og indsnævrer forslagene.

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

Når vejen er valgt, fuldføres husnummeret: ved at sende street_id med det delvise nummer får du de eksisterende numre på den vej, med exists sand/falsk til at validere det indtastede — og valget kan gentages med husnummeret uden ekstra opkrævning: opkrævningen er pr. session og pr. vej, ikke pr. klik; en anden vej i samme session er en ny opkrævning. Husnumre fuldføres kun i den session, der valgte den vej. I zoneinddelte byer er det husnummeret, der afgør det præcise postnummer.

API-tokenet kommer aldrig ud i browseren: den færdige widget (ra-suggerisci.js) kalder en lille proxy på din server, som tilføjer tokenet og sender videre. Hver session tillader op til 30 kald og varer 10 minutter; sessioner uden valg er gratis op til 200 om dagen pr. token, plus fem for hvert valg. Widget, færdig proxy og eksempelformular findes i kittet Din formular.

Virker i hvert land i drift (i dag Frankrig, Tyskland, Spanien, Nederlandene, Belgien, Finland, Tjekkiet, Portugal, Danmark, Norge, Østrig, Schweiz, Slovakiet, Kroatien, Rumænien, Ungarn, Slovenien, Irland, Island, Luxembourg, Liechtenstein, San Marino, Monaco, Andorra, Vatikanstaten; den opdaterede liste står under Lande): med country_code eller country kommer forslagene fra det lands register, og teksten skrives, som man skriver den dér — vej, husnummer, postnummer og by også i ét enkelt felt: «kalverstraat 92 amst», «92 rue de rivoli paris», i Nederlandene «1012PH 92». Hvert svar har parsed, altså hvordan serveren læste vejen (street), nummeret (house_number) og postnummeret (postcode): din formular ved, hvor nummeret står, uden at kende landets regler. Forslagene har vej, by, eventuelt bynavn og source (registry, eller osm hvor det nationale register ikke offentliggør); postnummer og husnumre står aldrig i forslagene: de kommer med valget, som går gennem motoren og returnerer samme post som /contact (postcode bekræftet af registret, geo på husnummer). Med valget kan du også sende postcode, det der er skrevet i formularen. attribution er kildeangivelsen, der skal vises ved siden af forslagene: registrets licens kræver det. Mangler landet, antages IT; for et land uden for drift er svaret stadig HTTP 200 med supported:false og hints:[], uden session og uden opkrævning. En session hører til ét land: skifter det, laver klienten et nyt UUID (ellers 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"}

Store volumener: det asynkrone job

Almindelige kald svarer med det samme, og derfor har de et loft over antallet af elementer — en HTTP-forespørgsel, der varer minutter, gavner ingen. Lofterne følger, hvor dyr behandlingen er:

Over de tal behøver du ikke dele listen op i hånden: tilføj "async": true, så vender kaldet straks tilbage med en kode, mens behandlingen går i samme kø som filuploads. Op til 100.000 elementer pr. kald, og i Mine job vises ét enkelt.

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}

Derefter læser du det, når du har brug for det, og resultatet kommer som JSON eller som 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

Under 5.000 rækker kommer resultatet også tilbage i results inde i JSON'en; derover downloades det som CSV. Opkrævningen sker, når jobbet sættes i kø, og den ubehandlede del går tilbage til din saldo, hvis jobbet stopper. Tokenet skal tilhøre en konto: jobbet havner i din kø.

Resultatkoder

Hvert svar indeholder feltet outcome: en liste af nøgleord, tom, når der intet er at melde. Mønstret er altid <conditions> [MODIFIED <types>] — betingelserne først, ændringerne til sidst — og det gælder for alle tjenester. Ved siden af finder du outcome_label (eller kind) med ok, modified, warning, error, og reason med forklaringen på én linje. Koderne er identifikatorer: de sammenlignes, ikke oversættes; med "language": "it" kommer de italienske koder ud (LOCALITA_NON_TROVATA MODIFICATO CAP INDIRIZZO), de samme ord for ord.

Adresse (kontaktverificering)

Italiensk skattenummer (codice fiscale)

På endpointet /tax-code har de samme kontroller deres egne koder — 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 — fordi skattenummeret dér er genstand for kontrollen, ikke et felt i posten.

Berigelse

E-mail

Telefon

Website

Hvad hvert kald bruger

Hvert kald bruger behandlinger fra tjenestens tæller: kontaktverificering (/contact, /suggest ved valg), deduplikering (/dedupe) og lette behandlinger (/email, /phone, /website, /enrichment, /tax-code ud over kvoten). Behandlinger købes som pakker, der bliver, eller med et månedligt abonnement; prisen pr. 1.000 falder med størrelsen og står på siden priser. Hver måned er 50 kontaktverificeringer, 100 poster i deduplikering og 500 lette behandlinger gratis.

Hvert svar siger, hvad det brugte, og hvorfra: feltet credit i JSON'en (counter, charged, free, subscription og packs med de trukne behandlinger og resten, available, auto_topup med antallet af automatisk købte pakker, note) og headerne X-RA-Charged, X-RA-Available og, når den træder til, X-RA-Auto-Topup. Dækker de tilgængelige behandlinger ikke kaldet, og tællerens automatiske optankning ikke er aktiv (eller mislykkes), er svaret 402 payment_required, og intet behandles.

For at vide, hvor mange behandlinger der er tilbage, uden at bruge nogen, findes GET /api/v1/credit. For hver af de tre tællere (contact, dedupe, light) returnerer det available, de gratis (free), der er tilbage i måneden, og datoen, hvor de nulstilles (den 1.), subscription (rest, størrelse, fornyelse), de aktive packs én for én med det, der er tilbage (de udløber ikke), og hvor mange du har købt, auto_topup (aktiv, størrelse, loft og brugt denne måned i euro), forbruget (used denne måned, totaler, seneste brug) og frem for alt state, fordi et nul alene ikke siger, om du har opbrugt det, eller om du ikke bruger den tjeneste: never_used, free (aldrig købt, arbejder inden for månedens gratis), free_used_up, active, awaiting_renewal, used_up (du har købt tidligere, og der er intet tilbage: fyld op), med en warning. Øverst oplister needs_topup de tællere, der kræver handling, og endpoint siger, hvilken tæller hvert endpoint bruger. Kræver et kontotoken.

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

Du betaler pr. verificeret element, ikke pr. kald: står der to telefonnumre eller to e-mails i et felt, verificerer vi dem alle (op til tre pr. række), og hvert betaler sin pris. Et batchkald bruger lige så meget som de behandlinger, det indeholder. Er kreditten opbrugt, og automatisk optankning ikke aktiv, svarer API'et HTTP 402 (utilstrækkelig kredit); over rate limit svarer det HTTP 429 med retry_after. Du køber en pakke fra dit kontoområde eller aktiverer et abonnement for at betale mindre pr. behandling.