Samme motor,
inne i appen din.

Ett endepunkt per tjeneste, med samme navn som tjenesten har her på nettstedet: /contact, /dedupe, /email, /phone, /website, /tax-code, /enrichment. Hvert av dem godtar ett element i forespørselskroppen eller en liste i items, opptil 500 per kall (100 for nettsteder, som må kontaktes ett og ett). Dedupliseringen er unntaket og vil alltid ha en liste: den sammenligner oppføringene med hverandre. For seg selv står /suggest, autofullføringen for skjemaer (den jobber per økt mens brukeren skriver, ikke i partier), og /credit, som sier hvor mange operasjoner som er igjen og hvilken tilstand hver teller er i, uten å bruke noen.

Autentisering

API-verten er www.radaraddress.com. Feltnavn, endepunktnavn og verdier er engelske identifikatorer, like på alle språk; etiketter, årsaker og meldinger følger språket i forespørselen ("language": "de" eller ?language=de, eller headeren Accept-Language, eller kontoens språk). Headeren Content-Language sier hvilket språk svaret kom på.

Tilgang til API-et skjer med Bearer-token. Kontoen er gratis: du oppretter tokenet fra Min side og tar det med i headeren på hver forespørsel i dette formatet:

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

Når du oppretter tokenet, kan du gi det en valgfri utløpsdato: etter den datoen får forespørslene HTTP 401 med koden token_expired; uten utløpsdato gjelder tokenet til du trekker det tilbake. Du kan trekke det tilbake eller lage et nytt når som helst fra Min side, der du også ser siste bruk og antall forespørsler som er besvart. En forespørsel uten token eller med ugyldig token returnerer HTTP 401.

De italienske navnene, for den som allerede bruker dem

API-et har én versjon, på engelsk. Den som integrerte med de italienske navnene trenger ikke endre noe: italienske felt godtas i hver forespørsel, endepunktene svarer også under sitt italienske navn (/contatto, /deduplica, /codicefiscale, /arricchimento, /telefono, /sito, /suggerisci, /nazioni, /credito), og svaret kommer med de italienske nøklene og kodene til den som ber om det med "language": "it" eller kaller www.radaraddress.it uten å oppgi språk.

Den fullstendige tabellen over feltene: 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å verdiene for alternativene har et italiensk navn: format nazionale/internazionale, action genera/valida/estrai/confronta/seleziona, foreign dichiarati/rileva, min_level certo/probabile/ambiguo; med "language": "it" kommer slik også level, confidence, state, kodene i outcome og filenes kolonneoverskrifter. Ved inndata godtas også vanlige synonymer (zip, surname, phone_number, date_of_birth…) og de samme overskriftene i filene til jobber i blokk.

Endepunkt for kontaktverifisering

Retter opp hele kontakten: adressen etter poststandarden i landet sitt — i Italia og i landene med register i drift kontrolleres gate og husnummer i det nasjonale adresseregisteret, i de andre kommer adressen ut i landets postform —, navnet og — hvis forespørselen inneholder den — den italienske skattekoden, som ryddes, fullføres hvis bare kontrolltegnet mangler og sammenlignes med etternavn, fornavn, kjønn og fødselsdato. Én kontakt om gangen, eller opptil 500 i items: skjemaet er det samme som for alle andre endepunkter.

Landet angis med country_code (ISO 3166-1: IT, DE, FR…) eller med country, skrevet som det faller seg: «Germania», «Germany», «Deutschland», «Forbundsrepublikken Tyskland», «UK», «Holland». Mangler det, antas Italia. I landene med register i drift — i dag Frankrike, Tyskland, Spania, Nederland, Belgia, Finnland, Tsjekkia, Portugal, Danmark, Norge, Østerrike, Sveits, Slovakia, Kroatia, Romania, Ungarn, Slovenia, Irland, Island, Luxembourg, Liechtenstein, San Marino, Monaco, Andorra, Vatikanstaten, den oppdaterte listen finnes under Land — kontrolleres gate og husnummer i det nasjonale adresseregisteret som i Italia: postnummer bekreftet eller fylt ut, husnummerets koordinater i geo, bydel eller arrondissement i district der byen har slike (Hamburg-Altstadt, Paris 4e Arrondissement), kommunekode i territory.municipality_code. På italiensk bærer resultatet FOREIGN fulgt av endringene, på de andre språkene bare endringene; finnes gaten, men ikke nummeret, HOUSE_NUMBER_NOT_FOUND. I de andre landene arbeider vi med formen, og meldingen sier det: postnummer i landets format, gateforkortelser skrevet ut, store bokstaver og stedsnavn slik landets post skriver dem (Hauptstr. 5, München → Hauptstraße 5, MÜNCHEN), med landlinjen. I begge tilfeller returneres address_key, formen dublettkontrollen bruker for å kjenne igjen samme gate skrevet på to måter. Med "foreign": "detect" gjenkjennes en post uten land som ikke finnes i Italia som utenlandsk når teksten sier det tydelig; standardverdien declared lar bare det som oppgir det være utenlandsk. Den fullstendige landkatalogen, med kort og offisielt navn, på engelsk og på landets språk, er tilgjengelig med GET /api/v1/countries og kan spørres 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"}'

For partiet, de samme feltene inne i items; svaret er { count, results: [ { id, result } ] } i samme rekkefø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 endepunkt for en adresse i et annet land: country_code er nok. Her Hamburg, kontrollert i det tyske registeret, med bydel 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" } }

Alternativer som gjelder hele kallet: postal_form (tvinger også normalized over i postformen), preserve_original (beholder navnet slik brukeren skrev det, og viser det kanoniske separat), precision 1–5 (standard 3; over 3 er treffet omtrentlig, og påliteligheten blir ikke high).

Sammen med adressen kommer city_type, som sier om leveringspunktet ligger i en provinshovedstad eller i en annen kommune i provinsen — forskjellen som betyr noe for den som segmenterer en kampanje etter by. provincial_capital er true, false eller null når vi ikke har grunnlag for å si det — og da gjetter vi ikke.

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

Ved siden av postnummeret kommer postcode_check: hvor det kommer fra (source) og hvor presist (precision: house_number selve nummeret, interpolated nabonumrene i samme gate, street gatens flertall, locality, municipality), hvor mange husnumre som sier det (house_numbers) og med hvilken enighet (agreement, 0 til 1). Mangler bekreftelse for det nummeret, bærer resultatet POSTCODE_UNCONFIRMED og confirmed er false: postnummeret beholdes som oppgitt, hvis det hører til byen, og bør kontrolleres.

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

Også koordinatene returneres, i geo (bredde- og lengdegrad WGS84), og de territorielle identifikatorene i territory: i Italia kommunens ISTAT-kode og matrikkelkode, CAB og gatens nasjonale identifikator; i de andre landene country og kommunens kode i det nasjonale registeret (municipality_code). Feltet precision sier hvilket nivå vi nådde: house_number når husnummeret er georeferert, interpolated når det nøyaktige nummeret mangler og punktet er anslått, street når vi har gatens punkt, municipality når vi bare har kommunens sentrum. source sier hvor punktet kommer fra: anncsu er det italienske nasjonale registeret, inspire landets nasjonale register, osm OpenStreetMap: da er dataene © OpenStreetMap contributors, ODbL-lisens, og kildehenvisningen må gjengis hvis du publiserer dem. Der et lands register krever en kildehenvisning, kommer den i meldingen. I CSV-filen for jobber i bulk er det kolonnene 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" } }

Etasje, oppgang og leilighet i adressen kommer også tilbake som egne data i sub_address: en liste med par av type og value, lest etter landets postregler (i Tyskland etter «//», i Frankrike på egen linje, i Portugal «3º Esq»). Typene er unit (leilighet), staircase (oppgang), floor (etasje), block, building, building_number og block_number. Adresselinjen blir stående i landets form. Det vi ikke kjenner igjen, står som det var skrevet og kommer ikke med i listen: vi gjetter ikke. Når den oppgitte enheten finnes på husnummeret, er sub_address_confirmed true, ellers null, aldri false: at vi ikke finner den, betyr ikke at den er feil.

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

Endepunkt for deduplisering

Gjenkjenner oppføringer som gjelder samme person på samme adresse selv når de er skrevet forskjellig: kortformer og likeverdige navn (Dany ≈ Daniela), etternavn og fornavn byttet om, forkortelser ("V. Roma" ≈ "Via Roma"), skrivefeil. Sammenligningen av adresser går gjennom normaliseringsmotoren: to skrivemåter for samme gate faller sammen til den kanoniske formen før sammenligningen. Høyst 500 kontakter per kall (oppføringer + referanse); for større lister bruker du jobb i blokk fra Min side.

Adressebøker. En kontakt i en adressebok (Apple Kontakter, Google, Outlook: vCard-modellen) har flere adresser, flere telefonnumre og flere e-postadresser, hver med en etikett. Endepunktet godtar dem slik, uten tak: addresses er en liste med objekter med type og de vanlige feltene; phones og emails er lister der hvert element er bare verdien ("340 7491386") eller {"type": "work", "value": "02 66710423"}, også blandet; de vanlige flate feltene er fortsatt gyldige og gjelder som første adresse og første kontaktopplysning. To kontakter er samme person hvis et hvilket som helst par av adressene deres stemmer overens (kontoret til den ene med den eneste adressen til den andre), eller hvis de har samme navn og et telefonnummer eller en e-postadresse felles, uansett posisjon og uansett etikett. Etiketten veier ikke i matchingen: den kommer tilbake slik den kom inn, pluss type_normalized i vCard-vokabularet (home, work, cell …), så appen vet hvor den skal skrive tilbake. Én kontakt er én operasjon, uansett hvor mange adresser og kontaktopplysninger 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 dublettene i groups: hver gruppe lister opp id-ene til sine members, sier hvilken som skal beholdes (main_record) og foreslår den konsoliderte record: det beste navnet og unionen av adresser og kontaktopplysninger (addresses, phones, emails), hver med sin type, med provenance (hvilke kontakter den kommer fra) og deduplisert: samme gate i to skrivemåter er én adresse, samme nummer med to etiketter ett nummer. Kontakter uten treff ligger i singles, som objekter {id, outcome}: med outcome INTERNAL_DUPLICATE har kontakten ingen dubletter mot andre, men har noen i seg selv (adresse skrevet to ganger, gjentatt nummer), og bærer sin sammenslåtte record. Den gjenkjenner samme gate skrevet på forskjellige måter ("V. Leopardi 4" ≈ "Via Giacomo Leopardi 4"), postnummeret rettet automatisk og etternavn og fornavn byttet om.

Endepunkt for italiensk skattekode

Tre handlinger på den italienske skattekoden for fysiske personer: generate fra persondataene, validate en eksisterende kode (format, kontrolltegn og omocodia), extract informasjonen den inneholder — fødselsdato, alder, kjønn, fødekommune eller fødeland. I tillegg kontrollerer compare at en kode stemmer med de oppgitte persondataene. Den dekker matrikkelkodene til alle italienske kommuner og til utlandet. Etternavn og fornavn må sendes med latinske tegn: for den som har et navn i et annet alfabet, beregnes koden på translitterasjonen som står i dokumentet, og den er ikke entydig (Dmitrij/Dmitry); et ikke-latinsk navn gir cognome_non_latino eller nome_non_latino, og i compare gir en forskjell i navnet til en som er født i utlandet, en merknad om mulig avvikende translitterasjon.

De første 500 lette operasjonene i måneden er gratis (skattekode inkludert), og gratiskvoten er én og samme uansett hvordan du bruker tjenesten: det du gjør her, på nettstedet og i filer i blokk, teller på samme kvote. Utover det betales lette operasjoner til sin 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" }

For volumer: { "action": "validate", "items": [ … ] } behandler opptil 500 elementer per kall, hvert med sin egen korrelasjons-id. Uttrekket flagger med ambiguous_year tilfellene der de to sifrene i årstallet ikke skiller århundrene (1926 mot 2026).

Hvert svar bærer outcome, reason, notes og comments på forespørselens språk: GENERATED for generate, tomt for en gyldig kode i validate, MATCH eller MISMATCH for compare (med differences: feltene som avviker). Når koden ikke består kontrollene er utfallet en av TAX_CODE_*-kodene nedenfor og error gir kortformen (check_digit, length, format, homocode, month, date, place, empty); ved generate sier den hvilken opplysning som mangler eller ikke lar seg løse (last_name, first_name, gender, birth_date, birth_place, ambiguous_place med options, last_name_non_latin). suggestion bærer den riktige koden når kontrollen kan gjenoppbygge den.

Endepunkt for berikelse

Beriker et navn: kjønn utledet fra fornavnet, type subjekt (fysisk eller juridisk person), normalisert tittel (Dott.ssa, Avv., …) og hilsningsformer klare til korrespondanse — "Egregio Sig. Rossi", "Gentile Dott.ssa Bianchi", "Spett.le" for bedrifter, "Gentile Famiglia" for husstander, "Caro/Cara" for den uformelle tonen. Den gjenkjenner også giftenavnformen i etternavnet ("Rossi in Verdi" → kvinne, med detaljer om de to etternavnene). Feltet gender godtar også skriftlige former («maschio», «donna», «Sig.ra», «male»); X angir en organisasjon og G en familie eller et par. Mangler tittelen, utleder vi den fra profession (yrket) eller fra education, når en av dem er oppgitt. Ordbøkene 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 bunter: { "items": [ … ] }, opptil 500 per kall. Utfallet er ENRICHED (kjønn og hilsener satt), LEGAL_PERSON (firma eller organisasjon: behandles som firmanavn) eller PARTIAL (fornavn mangler, eller kjønnet kan ikke utledes): reason sier hvorfor, comments hva som må legges til.

Endepunkt for e-postverifisering

Verifiserer en e-postadresse: syntaks, at domenet finnes (MX-/A-poster), skrivefeil i vanlige domener med foreslått rettelse (gmial.com → gmail.com), engangsdomener, generiske adresser (info@, regnskap@: ikke en person). Vi gjør ikke SMTP-verifisering av den enkelte postkassen, en påtrengende og upålitelig praksis. Parti items opptil 500; "dns": false hopper over domeneoppslaget.

En sikker skrivefeil rettes direkte: når adressen slik den er skrevet ikke engang er en adresse (navn@domene,no med komma) eller når rettelsen lander hos en kjent leverandør (gmai.com → gmail.com, også én bokstav unna hvis det skrevne domenet ikke mottar post), kommer email tilbake rettet, corrected_from inneholder det som ble skrevet og resultatet er MODIFIED EMAIL_DOMAIN. En mulig skrivefeil på et vilkårlig domene (rossi.con) forblir et forslag: EMAIL_TYPO med rettelsen i suggestion, og kontrollene (domain_exists, domain_checked) gjøres på den; adressen slik den er skrevet kontrolleres ikke.

Endepunkt for telefonverifisering

Kontrollerer et nummer uten å ringe noen: form, klasse og type, lengde etter nummerplanen, fasttelefonens område og operatøren blokken opprinnelig ble tildelt. class er lesningen du trenger for å jobbe med en liste: mobile (du kan sende SMS), landline (du ringer i kontortiden), special (ikke en persons nummer: nødnumre, offentlige tjenester, grønne numre og spesialtakst), foreign for numre med landskode. Når vi også gjenkjenner den nøyaktige tjenesten, sier type det (grønt nummer, spesialtakst, delt kostnad, offentlig tjeneste). Den italienske landskoden skrevet uten + (39347…, en klassisk eksportfeil) fjernes når sifrene ikke etterlater tvil — 3934567890 forblir mobilnummeret det er. Står det flere numre i samme felt («347… - 338…»), deler vi dem opp: de kommer tilbake som phone, phone2, phone3, og phone er aldri tomt når minst ett nummer finnes. Med "format": "international" kommer det italienske nummeret ut som +39…; standardverdien national lar det stå nakent og setter landskode bare på utenlandske numre. For utenlandske numre får du også e164, landskodens land i country_code, og retningsnullen etter landskoden fjernes («+44 (0)20…» og «+44 20…» gir samme nummer). Med country_code (eller country) i kallet eller i elementet leses et nummer skrevet uten landskode som et nasjonalt nummer i det landet: «020 7946 0958» i en britisk oppføring er London, ikke Milano. Uten land forblir det italiensk. Parti items opptil 500.

Et nummer fra oppføringens eget land er ikke «utenlandsk»: der vi kjenner nummerplanen får det sin class (mobile, landline, special), med format national blir det stående uten landskode i landets form (nullen inkludert), og national_number returneres ved siden av e164. PHONE_FOREIGN og class foreign gjelder fortsatt numre fra et annet land enn oppføringens.

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

Endepunkt for nettstedsverifisering

Kontrollerer at adressen er riktig skrevet, og at nettstedet faktisk svarer: at domenet finnes, HTTP-forespørsel med omdirigeringer fulgt, sluttkode, gyldig sertifikat. Ingen vurdering av innholdet. Også her kommer flere adresser i samme felt tilbake som website, website2, website3. Med "network": false kontrollerer vi bare formen, uten å kontakte nettstedet. Parti items opptil 100: hver kontroll åpner en tilkobling, så partiet er mindre enn for de andre endepunktene.

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

Endepunkt for adresseautofullføring

Starter du fra null? Widgeten ra-suggerisci.js og en liten proxy på serveren din er alt som trengs: tokenet havner aldri i nettleseren.

Forslag mens brukeren skriver en adresse i skjemaet ditt: hele det italienske gateregisteret, med navnet fullført («via verdi» → «Via Giuseppe Verdi»), kommune og provins; postnummeret kommer med valget, i de store byene med postsoner det riktige for husnummeret. Det fungerer per økt: klienten genererer en UUID for hver adresse som fylles ut, forslagsspørringene er gratis, og du betaler én kontaktverifisering når brukeren velger og feltene fylles ut (handlingen select, som returnerer oppføringen allerede normalisert av motoren). Feltene som allerede er fylt ut i skjemaet — også delvis — sendes med som kontekst og snevrer inn 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 gaten er valgt, fullføres husnummeret: sender du street_id med det delvise nummeret, får du de eksisterende numrene i den gaten, med exists sann/usann for å validere det som er skrevet — og valget kan gjentas med husnummeret uten ny belastning: belastningen er per økt og per gate, ikke per klikk; en annen gate i samme økt er en ny belastning. Husnumre fullføres bare i den økten som valgte den gaten. I byer med postsoner er det husnummeret som avgjør det nøyaktige postnummeret.

API-tokenet skal aldri inn i nettleseren: den ferdige widgeten (ra-suggerisci.js) kaller en liten proxy på serveren din, som legger til tokenet og sender videre. Hver økt tillater opptil 30 kall og varer i 10 minutter; økter uten valg er gratis opptil 200 per dag per token, pluss fem for hvert valg. Widget, ferdig proxy og eksempelskjema finner du i kittet Skjemaet ditt.

Fungerer i hvert land i drift (i dag Frankrike, Tyskland, Spania, Nederland, Belgia, Finnland, Tsjekkia, Portugal, Danmark, Norge, Østerrike, Sveits, Slovakia, Kroatia, Romania, Ungarn, Slovenia, Irland, Island, Luxembourg, Liechtenstein, San Marino, Monaco, Andorra, Vatikanstaten; den oppdaterte listen står under Land): med country_code eller country kommer forslagene fra registeret til det landet, og teksten skrives slik man skriver den der — gate, husnummer, postnummer og sted også i ett enkelt felt: «kalverstraat 92 amst», «92 rue de rivoli paris», i Nederland «1012PH 92». Hvert svar har parsed, altså hvordan serveren leste gaten (street), nummeret (house_number) og postnummeret (postcode): skjemaet ditt vet hvor nummeret står uten å kjenne landets regler. Forslagene har gate, sted, eventuelt grend og source (registry, eller osm der det nasjonale registeret ikke publiserer); postnummer og husnummer står aldri i forslagene: de kommer med valget, som går gjennom motoren og returnerer samme post som /contact (postcode bekreftet av registeret, geo på husnummer). Med valget kan du også sende postcode, det som er skrevet i skjemaet. attribution er kildehenvisningen som skal vises ved siden av forslagene: registerets lisens krever det. Mangler landet, antas IT; for et land utenfor drift er svaret fortsatt HTTP 200 med supported:false og hints:[], uten økt og uten belastning. En økt tilhører ett land: endres det, lager klienten en ny 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 volumer: den asynkrone jobben

Vanlige kall svarer med en gang, og derfor har de et tak på antall elementer — en HTTP-forespørsel som varer i minutter, er ikke til nytte for noen. Takene følger hvor kostbar operasjonen er:

Over disse tallene trenger du ikke dele opp listen for hånd: legg til "async": true, så svarer kallet med en gang med en kode, mens behandlingen går inn i samme kø som filopplastingene. Opptil 100 000 elementer per kall, og i Mine jobber vises bare é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}

Så leser du det når du trenger 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 rader kommer resultatet også tilbake i results inne i JSON-en; over det lastes det ned som CSV. Belastningen skjer når jobben settes i kø, og den delen som ikke er behandlet, går tilbake til saldoen din hvis jobben stopper. Tokenet må tilhøre en konto: jobben havner i din kø.

Utfallskoder

Hvert svar inneholder feltet outcome: en liste med nøkkelord, tom når det ikke er noe å melde. Mønsteret er alltid <conditions> [MODIFIED <types>] — betingelsene først, endringene til slutt — og gjelder for alle tjenester. Ved siden av finner du outcome_label (eller kind) med ok, modified, warning, error, og reason med forklaringen på én linje. Kodene er identifikatorer: de sammenlignes, de oversettes ikke; med "language": "it" kommer de italienske kodene (LOCALITA_NON_TROVATA MODIFICATO CAP INDIRIZZO), de samme ord for ord.

Adresse (kontaktverifisering)

Italiensk skattekode

På endepunktet /tax-code har de samme kontrollene 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 skattekoden der er gjenstand for kontrollen, ikke et felt i oppføringen.

Berikelse

E-post

Telefon

Nettsted

Hva hvert kall bruker

Hvert kall bruker operasjoner fra tjenestens teller: kontaktverifisering (/contact, /suggest ved valg), deduplisering (/dedupe) og lette operasjoner (/email, /phone, /website, /enrichment, /tax-code utover gratiskvoten). Operasjoner kjøpes som pakker som blir stående, eller med et månedsabonnement; prisen per 1 000 synker med størrelsen og står på siden priser. Hver måned er 50 kontaktverifiseringer, 100 oppføringer i deduplisering og 500 lette operasjoner gratis.

Hvert svar sier hva det brukte, og hvor det kom fra: feltet credit i JSON-en (counter, charged, free, subscription og packs med operasjonene som ble trukket og resten, available, auto_topup med antall pakker kjøpt automatisk, note) og headerne X-RA-Charged, X-RA-Available og, når den griper inn, X-RA-Auto-Topup. Hvis de tilgjengelige operasjonene ikke dekker kallet og tellerens automatiske påfylling ikke er aktiv (eller mislykkes), er svaret 402 payment_required, og ingenting behandles.

For å vite hvor mange operasjoner som er igjen uten å bruke noen, finnes GET /api/v1/credit. For hver av de tre tellerne (contact, dedupe, light) returnerer den available, de gratis (free) som er igjen i måneden og datoen de nullstilles (den 1.), subscription (rest, størrelse, fornyelse), de aktive packs én for én med hva som er igjen (de utløper ikke) og hvor mange du har kjøpt, auto_topup (aktiv, størrelse, tak og brukt denne måneden i euro), bruken (used denne måneden, totalt, siste bruk) og fremfor alt state, fordi en null alene ikke sier om du har brukt opp alt eller om du ikke bruker tjenesten: never_used, free (aldri kjøpt, jobber innenfor månedens gratiskvote), free_used_up, active, awaiting_renewal, used_up (du har kjøpt tidligere, og ingenting er igjen: må fylles på), med et warning. Øverst lister needs_topup opp tellerne som trenger handling, og endpoint sier hvilken teller hvert endepunkt bruker. Krever tokenet til en konto.

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 per verifisert element, ikke per kall: står det to telefonnumre eller to e-postadresser i ett felt, verifiserer vi alle (opptil tre per rad), og hvert av dem betaler sin pris. Et partikall bruker like mye som operasjonene det inneholder. Er kreditten brukt opp og automatisk påfylling ikke aktiv, svarer API-et HTTP 402 (utilstrekkelig kreditt); over ratebegrensningen svarer det HTTP 429 med retry_after. Du kjøper en pakke fra Min side, eller aktiverer et abonnement for å betale mindre per operasjon.