Samma motor,
inne i din app.

En endpoint per tjänst, med samma namn som tjänsten har här på webbplatsen: /contact, /dedupe, /email, /phone, /website, /tax-code, /enrichment. Var och en tar emot ett element i anropets body eller en lista i items, upp till 500 per anrop (100 för webbplatser, som måste kontaktas en och en). Dubblettrensningen är undantaget och vill alltid ha en lista: den jämför posterna med varandra. Vid sidan om står /suggest, autokompletteringen för formulär (den arbetar per session medan användaren skriver, inte i partier), och /credit, som säger hur många bearbetningar som återstår och vilket läge varje räknare är i, utan att förbruka några.

Autentisering

API-värden är www.radaraddress.com. Fältnamn, ändpunktsnamn och värden är engelska identifierare, samma på alla språk; etiketter, orsaker och meddelanden följer anropets språk ("language": "de" eller ?language=de, eller headern Accept-Language, eller kontots språk). Headern Content-Language anger på vilket språk svaret kom.

Åtkomsten till API:et sker med Bearer-token. Kontot är gratis: du skapar din token från kontosidan och skickar med den i headern på varje anrop i formatet:

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

När du skapar den kan du ge token ett valfritt utgångsdatum: efter det datumet får anropen HTTP 401 med koden token_expired; utan utgångsdatum gäller token tills du återkallar den. Du kan återkalla eller skapa om den när som helst från kontosidan, där du också ser senaste användning och antal anrop som betjänats. Ett anrop utan token eller med ogiltig token returnerar HTTP 401.

De italienska namnen, för den som redan använder dem

API:et har en enda version, på engelska. Den som integrerade med de italienska namnen behöver inte ändra något: italienska fält accepteras i varje anrop, ändpunkterna svarar även under sitt italienska namn (/contatto, /deduplica, /codicefiscale, /arricchimento, /telefono, /sito, /suggerisci, /nazioni, /credito), och svaret kommer med de italienska nycklarna och koderna till den som begär det med "language": "it" eller anropar www.radaraddress.it utan att ange språk.

Den fullständiga tabellen över fälten: engelska → italienska

engelska	italienska	engelska	italienska
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

Även alternativens värden har ett italienskt namn: format nazionale/internazionale, action genera/valida/estrai/confronta/seleziona, foreign dichiarati/rileva, min_level certo/probabile/ambiguo; med "language": "it" kommer så även level, confidence, state, koderna i outcome och filernas kolumnrubriker. Vid inmatning accepteras även vanliga synonymer (zip, surname, phone_number, date_of_birth…) och samma rubriker i batchjobbens filer.

Endpoint för kontaktverifiering

Rättar hela kontakten: adressen enligt postens standard i dess land — i Italien och i de länder vars register är i drift kontrolleras gata och husnummer i det nationella adressregistret, i övriga länder kommer adressen ut i landets postform —, namnet och — om anropet innehåller den — den italienska skattekoden, som rensas, kompletteras om bara kontrolltecknet saknas och jämförs med efternamn, förnamn, kön och födelsedatum. En kontakt i taget, eller upp till 500 i items: schemat är detsamma som för alla andra endpoints.

Landet anges med country_code (ISO 3166-1: IT, DE, FR…) eller med country, skrivet hur som helst: ”Germania”, ”Germany”, ”Deutschland”, ”Förbundsrepubliken Tyskland”, ”UK”, ”Holland”. Saknas det antas Italien. I länderna vars register är i drift — i dag Frankrike, Tyskland, Spanien, Nederländerna, Belgien, Finland, Tjeckien, Portugal, Danmark, Norge, Österrike, Schweiz, Slovakien, Kroatien, Rumänien, Ungern, Slovenien, Irland, Island, Luxemburg, Liechtenstein, San Marino, Monaco, Andorra, Vatikanstaten, den aktuella listan finns under Länder — kontrolleras gata och husnummer i det nationella adressregistret precis som i Italien: postnummer bekräftat eller ifyllt, husnumrets koordinater i geo, stadsdel eller arrondissement i district där staden har sådana (Hamburg-Altstadt, Paris 4e Arrondissement), kommunkod i territory.municipality_code. På italienska bär resultatet FOREIGN följt av ändringarna, på övriga språk bara ändringarna; finns gatan men inte numret, HOUSE_NUMBER_NOT_FOUND. I övriga länder arbetar vi med formen, och meddelandet säger det: postnummer i landets format, gatuförkortningar utskrivna, versaler och ortnamn som landets post skriver dem (Hauptstr. 5, München → Hauptstraße 5, MÜNCHEN), med landsraden. I båda fallen returneras address_key, formen som dubblettkontrollen använder för att känna igen samma gata skriven på två sätt. Med "foreign": "detect" känns en post utan land som inte hittas i Italien igen som utländsk när texten tydligt säger det; standardvärdet declared låter bara det som anger det vara utländskt. Den fullständiga landskatalogen, med kort och officiellt namn, på engelska och på landets språk, finns via GET /api/v1/countries och kan frågas 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"}'

För partiet, samma fält inuti items; svaret är { count, results: [ { id, result } ] } i samma ordning som det skickades.

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

Samma endpoint för en adress i ett annat land: country_code räcker. Här Hamburg, kontrollerad i det tyska registret, med stadsdel och husnumrets 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" } }

Alternativ som gäller hela anropet: postal_form (tvingar även normalized till postal form), preserve_original (behåller namnet som användaren skrev det och redovisar det kanoniska separat), precision 1–5 (standard 3; över 3 är matchningen ungefärlig och tillförlitligheten blir inte high).

Tillsammans med adressen kommer city_type, som säger om utdelningsstället ligger i en provinshuvudstad eller i en annan kommun i provinsen – skillnaden som spelar roll för den som delar upp en kampanj efter stad. provincial_capital är true, false eller null när vi inte har underlag att säga det – och då gissar vi inte.

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

Bredvid postnumret kommer postcode_check: varifrån det kommer (source) och hur exakt (precision: house_number själva numret, interpolated grannumren på samma gata, street gatans majoritet, locality, municipality), hur många husnummer som säger det (house_numbers) och med vilken samstämmighet (agreement, 0 till 1). Saknas bekräftelse för det numret bär resultatet POSTCODE_UNCONFIRMED och confirmed är false: postnumret behålls som angivet, om det hör till staden, och bör kontrolleras.

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

Även koordinaterna returneras, i geo (latitud och longitud WGS84), och de territoriella identifierarna i territory: i Italien kommunens ISTAT-kod och fastighetskod, CAB och gatans nationella identifierare; i övriga länder country och kommunens kod i det nationella registret (municipality_code). Fältet precision anger vilken nivå vi nådde: house_number när husnumret är georefererat, interpolated när det exakta numret saknas och punkten är uppskattad, street när vi har gatans punkt, municipality när vi bara har kommunens mittpunkt. source anger varifrån punkten kommer: anncsu är det italienska nationella registret, inspire landets nationella register, osm OpenStreetMap: då är uppgifterna © OpenStreetMap contributors, licens ODbL, och källhänvisningen ska återges om du publicerar dem. Där ett lands register kräver en källhänvisning finns den i meddelandet. I CSV-filen för batchjobb är det kolumnerna latitude, longitude, geo_precision, istat_code och 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" } }

Våning, trappuppgång och lägenhet i adressen kommer också tillbaka som egna uppgifter i sub_address: en lista med par av type och value, lästa enligt landets postregler (i Tyskland efter ”//”, i Frankrike på en egen rad, i Portugal ”3º Esq”). Typerna är unit (lägenhet), staircase (trappuppgång), floor (våning), block, building, building_number och block_number. Adressraden står kvar i landets form. Det vi inte känner igen står kvar som det var skrivet och kommer inte med i listan: vi gissar inte. När den angivna enheten finns på gatunumret är sub_address_confirmed true, annars null, aldrig false: att vi inte hittar den betyder inte att den är fel.

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

Endpoint för dubblettrensning

Känner igen poster som avser samma person på samma adress även när de är skrivna på olika sätt: kortformer och likvärdiga namn (Dany ≈ Daniela), efternamn och förnamn i omvänd ordning, förkortningar ("V. Roma" ≈ "Via Roma"), stavfel. Jämförelsen av adresser går genom normaliseringsmotorn: två skrivsätt för samma gata faller samman till den kanoniska formen före jämförelsen. Högst 500 kontakter per anrop (poster + referens); för större listor använder du batchjobbet från kontosidan.

Adressböcker. En kontakt i adressboken (Apples Kontakter, Google, Outlook: vCard-modellen) har flera adresser, flera telefonnummer och flera e-postadresser, var och en med en etikett. Endpointen tar emot dem som de är, utan tak: addresses är en lista med objekt med type och de vanliga fälten; phones och emails är listor där varje element är antingen bara värdet ("340 7491386") eller {"type": "work", "value": "02 66710423"}, även blandat; de vanliga platta fälten gäller fortfarande och räknas som första adress och första kontaktuppgift. Två kontakter är samma person om något par av deras adresser sammanfaller (den enes kontor med den andres enda adress), eller om de har samma namn och ett telefonnummer eller en e-postadress gemensamt, i vilken position som helst och med vilken etikett som helst. Etiketten påverkar inte matchningen: den kommer tillbaka som den kom in, plus type_normalized i vCard-vokabulären (home, work, cell …), så att appen vet var den ska skriva tillbaka. En kontakt är en bearbetning, oavsett hur många adresser och kontaktuppgifter 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 grupperar dubbletterna i groups: varje grupp listar id för sina members, anger vilken som ska behållas (main_record) och föreslår den konsoliderade record: det bästa namnet och unionen av adresser och kontaktuppgifter (addresses, phones, emails), var och en med sin typ, med provenance (vilka kontakter den kommer från) och rensad från dubbletter: samma gata i två skrivsätt är en enda adress, samma nummer med två etiketter ett enda nummer. Kontakter utan träff ligger i singles, som objekt {id, outcome}: med outcome INTERNAL_DUPLICATE har kontakten inga dubbletter med andra men däremot inom sig (adress skriven två gånger, upprepat nummer), och den bär sin sammanslagna record. Den känner igen samma gata skriven på olika sätt ("V. Leopardi 4" ≈ "Via Giacomo Leopardi 4"), postnumret automatiskt rättat och efternamn och förnamn i omvänd ordning.

Endpoint för italienskt skattenummer

Tre åtgärder på fysiska personers italienska skattenummer (codice fiscale): generate ur personuppgifterna, validate en befintlig kod (format, kontrolltecken och omocodia), extract den information som koden innehåller – födelsedatum, ålder, kön, födelsekommun eller födelseland. Dessutom kontrollerar compare att en kod stämmer med de uppgivna personuppgifterna. Den täcker fastighetskoderna för alla italienska kommuner och för utländska stater. Efternamn och förnamn ska skickas med latinska bokstäver: för den som har ett namn i ett annat alfabet beräknas koden på den translitterering som står i dokumentet, och den är inte entydig (Dmitrij/Dmitry); ett icke-latinskt namn returnerar cognome_non_latino eller nome_non_latino, och i compare ger en avvikelse i namnet hos någon född utomlands en anmärkning om möjlig annan translitterering.

De första 500 lätta bearbetningarna per månad är gratis (skattenummer inräknat), och den fria kvoten är en och samma oavsett hur du använder tjänsten: det du gör här, på webbplatsen och i batchfiler räknas mot samma kvot. Därutöver betalar du priset för lätta bearbetningar (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" }

För volymer: { "action": "validate", "items": [ … ] } bearbetar upp till 500 element per anrop, vart och ett med sitt eget korrelations-id. Extraktionen flaggar med ambiguous_year de fall där årets två siffror inte skiljer århundradena åt (1926 mot 2026).

Varje svar bär outcome, reason, notes och comments på förfrågans språk: GENERATED för generate, tomt för en giltig kod i validate, MATCH eller MISMATCH för compare (med differences: fälten som avviker). När koden inte klarar kontrollerna är utfallet en av TAX_CODE_*-koderna nedan och error ger kortformen (check_digit, length, format, homocode, month, date, place, empty); vid generate säger den vilken uppgift som saknas eller inte går att lösa (last_name, first_name, gender, birth_date, birth_place, ambiguous_place med options, last_name_non_latin). suggestion bär den korrekta koden när kontrollen kan återskapa den.

Endpoint för berikning

Berikar ett namn: kön härlett ur förnamnet, typ av subjekt (fysisk eller juridisk person), normaliserad titel (Dott.ssa, Avv., …) och hälsningsfraser klara för korrespondens – "Egregio Sig. Rossi", "Gentile Dott.ssa Bianchi", "Spett.le" för företag, "Gentile Famiglia" för hushåll, "Caro/Cara" för det informella tilltalet. Den känner också igen giftasformen i efternamnet ("Rossi in Verdi" → kvinna, med de två efternamnen redovisade). Fältet gender tar även emot skrivna former (”maschio”, ”donna”, ”Sig.ra”, ”male”); X markerar en organisation och G en familj eller ett par. Saknas titeln härleder vi den ur profession (yrket) eller ur education, när något av dem anges. Ordlistorna är italienska.

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 omgångar: { "items": [ … ] }, upp till 500 per anrop. Utfallet är ENRICHED (kön och hälsningsfraser satta), LEGAL_PERSON (företag eller organisation: behandlas som firmanamn) eller PARTIAL (förnamn saknas, eller könet går inte att härleda): reason säger varför, comments vad som ska läggas till.

Endpoint för e-postkontroll

Kontrollerar en e-postadress: syntax, att domänen finns (MX/A-poster), stavfel i vanliga domäner med föreslagen rättelse (gmial.com → gmail.com), engångsdomäner, generiska adresser (info@, billing@: inte en person). Vi gör ingen SMTP-kontroll av den enskilda brevlådan, en påträngande och otillförlitlig metod. Parti med items upp till 500; "dns": false hoppar över domänuppslaget.

Ett säkert stavfel rättas direkt: när adressen som den är skriven inte ens är en adress (namn@doman,se med kommatecken) eller när korrigeringen landar hos en känd leverantör (gmai.com → gmail.com, även en bokstav ifrån om den skrivna domänen inte tar emot post), kommer email tillbaka rättad, corrected_from innehåller det som skrevs och utfallet är MODIFIED EMAIL_DOMAIN. Ett möjligt stavfel på en godtycklig domän (rossi.con) förblir ett förslag: EMAIL_TYPO med korrigeringen i suggestion, och kontrollerna (domain_exists, domain_checked) görs på den; adressen som den är skriven kontrolleras inte.

Endpoint för telefonkontroll

Kontrollerar ett nummer utan att ringa någon: form, klass och typ, längd enligt nummerplanen, riktnummerområde för fast telefon och den operatör som blocket ursprungligen tilldelades. class är den läsning som behövs för att arbeta med en lista: mobile (du kan skicka sms), landline (du ringer på kontorstid), special (inte en persons nummer: nödnummer, samhällstjänster, frisamtals- och betalnummer), foreign för nummer med utländskt landsnummer. När vi även känner igen den exakta tjänsten säger type det (frisamtal, betalnummer, delad kostnad, samhällstjänst). Det italienska landsnumret skrivet utan + (39347…, ett klassiskt exportfel) tar vi bort när siffrorna inte lämnar något tvivel – 3934567890 förblir den mobil det är. Om samma fält innehåller flera nummer (”347… - 338…”) delar vi upp dem: de kommer tillbaka som phone, phone2, phone3, och phone är aldrig tomt när minst ett nummer finns. Med "format": "international" kommer det italienska numret ut i formen +39…; standardvärdet national lämnar det naket och sätter landsnummer bara på utländska nummer. För utländska nummer får du också e164, landsnumrets land i country_code, och nollan efter landsnumret tas bort (”+44 (0)20…” och ”+44 20…” ger samma nummer). Med country_code (eller country) i anropet eller i elementet läses ett nummer skrivet utan landsnummer som ett nationellt nummer i det landet: ”020 7946 0958” i en brittisk post är London, inte Milano. Utan land förblir det italienskt. Parti med items upp till 500.

Ett nummer från postens eget land är inte ”utländskt”: där vi känner nummerplanen får det sin class (mobile, landline, special), med format national förblir det utan landskod i sitt lands form (riktnummernollan inräknad), och national_number returneras bredvid e164. PHONE_FOREIGN och class foreign gäller fortfarande nummer från ett annat land än 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 för webbplatskontroll

Kontrollerar att adressen är rätt skriven och att webbplatsen verkligen svarar: att domänen finns, HTTP-anrop med omdirigeringarna följda, slutlig statuskod, giltigt certifikat. Ingen bedömning av innehållet. Även här kommer flera adresser i samma fält tillbaka som website, website2, website3. Med "network": false kontrollerar vi bara formen, utan att kontakta webbplatsen. Parti med items upp till 100: varje kontroll öppnar en anslutning, så partiet är mindre än hos övriga 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 för adressautokomplettering

Börjar du från noll? Widgeten ra-suggerisci.js och en liten proxy på din server räcker: token hamnar aldrig i webbläsaren.

Förslag medan användaren skriver en adress i ditt formulär: hela det italienska gaturegistret, med namnet kompletterat (”via verdi” → ”Via Giuseppe Verdi”), kommun och provins; postnumret kommer med valet, i de stora zonindelade städerna det rätta för gatunumret. Det fungerar per session: klienten skapar ett UUID för varje adress som fylls i, förslagsfrågorna är gratis, och du betalar en kontaktverifiering när användaren väljer och fälten fylls i (åtgärden select, som returnerar posten redan normaliserad av motorn). De fält som redan är ifyllda i formuläret – även delvis – skickas med som sammanhang och snävar in förslagen.

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 gatan är vald kompletteras gatunumret: skickar du street_id med det ofullständiga numret får du gatans befintliga nummer, med exists sant/falskt för att validera det som skrivits – och valet kan upprepas med gatunumret utan ny debitering: debiteringen är per session och per gata, inte per klick; en annan gata i samma session är en ny debitering. Gatunummer kompletteras bara i den session som valt den gatan. I zonindelade städer är det gatunumret som avgör det exakta postnumret.

API-token hamnar aldrig i webbläsaren: den färdiga widgeten (ra-suggerisci.js) anropar en liten proxy på din server, som lägger till token och skickar vidare. Varje session tillåter upp till 30 anrop och gäller i 10 minuter; sessioner utan val är gratis upp till 200 per dag och token, plus fem per val. Widget, färdig proxy och exempelformulär finns i kitet Ditt formulär.

Fungerar i varje land i drift (i dag Frankrike, Tyskland, Spanien, Nederländerna, Belgien, Finland, Tjeckien, Portugal, Danmark, Norge, Österrike, Schweiz, Slovakien, Kroatien, Rumänien, Ungern, Slovenien, Irland, Island, Luxemburg, Liechtenstein, San Marino, Monaco, Andorra, Vatikanstaten; den aktuella listan finns under Länder): med country_code eller country kommer förslagen från det landets register, och texten skrivs som man skriver den där — gata, nummer, postnummer och ort även i ett enda fält: «kalverstraat 92 amst», «92 rue de rivoli paris», i Nederländerna «1012PH 92». Varje svar innehåller parsed, alltså hur servern läste gatan (street), numret (house_number) och postnumret (postcode): ditt formulär vet var numret står utan att känna till landets regler. Förslagen innehåller gata, ort, eventuell kommundel och source (registry, eller osm där det nationella registret inte publicerar); postnummer och gatunummer finns aldrig i förslagen: de kommer med valet, som går genom motorn och returnerar samma post som /contact (postcode bekräftat av registret, geo på gatunummer). Med valet kan du också skicka postcode, det som skrivits i formuläret. attribution är källangivelsen som ska visas bredvid förslagen: registrets licens kräver det. Saknas landet antas IT; för ett land utanför drift är svaret fortfarande HTTP 200 med supported:false och hints:[], utan session och utan debitering. En session tillhör ett land: byter det, skapar klienten ett nytt UUID (annars 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"}

Stora volymer: det asynkrona jobbet

Vanliga anrop svarar direkt, och därför har de ett tak för antal element – ett HTTP-anrop som tar minuter är ingen betjänt av. Taken följer hur tung operationen är:

Över de talen behöver du inte dela upp listan för hand: lägg till "async": true så returnerar anropet direkt med en kod, medan bearbetningen går in i samma kö som filuppladdningarna. Upp till 100 000 element per anrop, och i Mina jobb visas ett enda.

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}

Sedan läser du av det när det behövs, och resultatet kommer som JSON eller 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 även i results inuti JSON-svaret; däröver laddas det ner som CSV. Debiteringen sker när jobbet ställs i kö, och den obearbetade delen går tillbaka till saldot om jobbet stannar. Token måste vara knuten till ett konto: jobbet hamnar i din kö.

Utfallskoder

Varje svar innehåller fältet outcome: en lista med nyckelord, tom när det inte finns något att anmärka. Mönstret är alltid <conditions> [MODIFIED <types>] — villkoren först, ändringarna sist — och gäller för alla tjänster. Bredvid hittar du outcome_label (eller kind) med ok, modified, warning, error, och reason med förklaringen på en rad. Koderna är identifierare: de jämförs, de översätts inte; med "language": "it" kommer de italienska koderna (LOCALITA_NON_TROVATA MODIFICATO CAP INDIRIZZO), samma ord för ord.

Adress (kontaktverifiering)

Italienskt skattenummer

På endpointen /tax-code har samma kontroller egna 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 – eftersom skattenumret där är föremålet för kontrollen, inte ett fält i posten.

Berikning

E-post

Telefon

Webbplats

Vad varje anrop förbrukar

Varje anrop förbrukar bearbetningar från tjänstens räknare: kontaktverifiering (/contact, /suggest vid val), dubblettrensning (/dedupe) och lätta bearbetningar (/email, /phone, /website, /enrichment, /tax-code utöver den fria kvoten). Bearbetningar köps i paket som består, eller med ett månadsabonnemang; priset per 1 000 sjunker med storleken och finns på sidan priser. Varje månad är 50 kontaktverifieringar, 100 poster i dubblettrensning och 500 lätta bearbetningar gratis.

Varje svar säger vad det förbrukade och varifrån: fältet credit i JSON-svaret (counter, charged, free, subscription och packs med de bearbetningar som tagits och det som återstår, available, auto_topup med antalet paket som köpts automatiskt, note) och headrarna X-RA-Charged, X-RA-Available och, när den träder in, X-RA-Auto-Topup. Om de tillgängliga bearbetningarna inte täcker anropet och räknarens automatiska påfyllning inte är aktiv (eller misslyckas) blir svaret 402 payment_required och inget bearbetas.

För att veta hur många bearbetningar som återstår utan att förbruka någon finns GET /api/v1/credit. För var och en av de tre räknarna (contact, dedupe, light) returnerar den available, de fria (free) som återstår i månaden och datumet då de nollställs (den 1:a), subscription (återstod, storlek, förnyelse), de aktiva packs ett och ett med vad som återstår (de går inte ut) och hur många du köpt, auto_topup (aktiv, storlek, tak och månadens utgift i euro), användningen (used i månaden, totalt, senaste användning) och framför allt state, eftersom en nolla för sig inte säger om du har förbrukat allt eller om du inte använder tjänsten: never_used, free (aldrig köpt, du arbetar inom månadens fria), free_used_up, active, awaiting_renewal, used_up (du har köpt tidigare och inget återstår: dags att fylla på), med ett warning. Överst listar needs_topup de räknare som behöver åtgärd och endpoint säger vilken räknare varje endpoint förbrukar. Kräver en 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 betalar per verifierat element, inte per anrop: om ett fält innehåller två telefonnummer eller två e-postadresser kontrollerar vi alla (upp till tre per rad) och var och en betalar sitt pris. Ett partianrop förbrukar lika mycket som de bearbetningar det innehåller. Om krediterna är slut och automatisk påfyllning inte är aktiv svarar API:et HTTP 402 (otillräcklig kredit); över hastighetsgränsen svarar det HTTP 429 med retry_after. Du köper ett paket från kontosidan, eller aktiverar ett abonnemang för att betala mindre per bearbetning.