Sama moottori,
omassa sovelluksessasi.

Yksi päätepiste per palvelu, samalla nimellä kuin palvelulla on tällä sivustolla: /contact, /dedupe, /email, /phone, /website, /tax-code, /enrichment. Jokainen ottaa vastaan yhden kohteen pyynnön rungossa tai listan kentässä items, enintään 500 kutsua kohden (100 verkkosivuille, joihin on otettava yhteys yksi kerrallaan). Duplikaattien poisto on poikkeus ja haluaa aina listan: se vertaa tietueita toisiinsa. Erillään ovat /suggest, lomakkeiden automaattitäydennys (toimii istunnoittain käyttäjän kirjoittaessa, ei erissä), ja /credit, joka kertoo, montako käsittelyä on jäljellä ja missä tilassa kukin laskuri on, kuluttamatta yhtään.

Todennus

API:n isäntä on www.radaraddress.com. Kenttien, päätepisteiden ja arvojen nimet ovat englanninkielisiä tunnisteita, samat kaikilla kielillä; otsikot, syyt ja viestit seuraavat pyynnön kieltä ("language": "de" tai ?language=de, tai Accept-Language-otsake, tai tilin kieli). Content-Language-otsake kertoo, millä kielellä vastaus tuli.

API:a käytetään Bearer-tokenilla. Tili on ilmainen: luot tokenin omalla tililläsi ja liität sen jokaisen pyynnön otsakkeeseen tässä muodossa:

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

Luodessasi tokenin voit antaa sille valinnaisen vanhenemispäivän: sen jälkeen pyynnöt saavat vastauksen HTTP 401 koodilla token_expired; ilman vanhenemispäivää token on voimassa, kunnes peruutat sen. Voit peruuttaa tai luoda sen uudelleen milloin tahansa omalla tililläsi, jossa näet myös viimeisimmän käytön ja palveltujen pyyntöjen määrän. Pyyntö ilman tokenia tai virheellisellä tokenilla palauttaa HTTP 401.

Italialaiset nimet niille, jotka jo käyttävät niitä

API:sta on yksi versio, englanniksi. Sen, joka integroi italialaisilla nimillä, ei tarvitse muuttaa mitään: italialaiset kentät hyväksytään jokaisessa pyynnössä, päätepisteet vastaavat myös italialaisella nimellään (/contatto, /deduplica, /codicefiscale, /arricchimento, /telefono, /sito, /suggerisci, /nazioni, /credito), ja vastaus tulee italialaisilla avaimilla ja koodeilla sille, joka pyytää sitä "language": "it"-arvolla tai kutsuu www.radaraddress.it-osoitetta ilmoittamatta kieltä.

Kenttien täydellinen taulukko: englanti → italia

englanti	italia	englanti	italia
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

Myös vaihtoehtojen arvoilla on italialainen nimi: format nazionale/internazionale, action genera/valida/estrai/confronta/seleziona, foreign dichiarati/rileva, min_level certo/probabile/ambiguo; "language": "it"-arvolla samoin tulevat level, confidence, state, outcome-koodit ja tiedostojen sarakeotsikot. Syötteessä hyväksytään myös yleisiä synonyymejä (zip, surname, phone_number, date_of_birth…) ja samat otsikot erätöiden tiedostoissa.

Yhteystiedon tarkistuksen päätepiste

Korjaa koko yhteystiedon: osoitteen maansa postistandardin mukaan — Italiassa ja maissa, joiden rekisteri on käytössä, katu ja talonumero tarkistetaan kansallisesta osoiterekisteristä; muissa maissa osoite palautuu maan postimuodossa —, nimen ja — jos pyyntö sisältää sen — italialaisen verotunnuksen, joka siistitään, täydennetään jos vain tarkistusmerkki puuttuu ja verrataan sukunimeen, etunimeen, sukupuoleen ja syntymäaikaan. Yksi yhteystieto kerrallaan tai enintään 500 kentässä items: rakenne on sama kuin kaikissa muissa päätepisteissä.

Maa annetaan kentällä country_code (ISO 3166-1: IT, DE, FR…) tai kentällä country, kirjoitettuna miten tahansa: ”Germania”, ”Germany”, ”Deutschland”, ”Saksan liittotasavalta”, ”UK”, ”Hollanti”. Jos se puuttuu, oletetaan Italia. Maissa, joiden rekisteri on käytössä — tänään Ranska, Saksa, Espanja, Alankomaat, Belgia, Suomi, Tšekki, Portugali, Tanska, Norja, Itävalta, Sveitsi, Slovakia, Kroatia, Romania, Unkari, Slovenia, Irlanti, Islanti, Luxemburg, Liechtenstein, San Marino, Monaco, Andorra, Vatikaanivaltio, ajantasainen luettelo on sivulla Maat — katu ja talonumero tarkistetaan kansallisesta osoiterekisteristä kuten Italiassa: postinumero vahvistetaan tai täydennetään, talonumeron koordinaatit kentässä geo, kaupunginosa tai arrondissement kentässä district, jos kaupungissa on sellaisia (Hamburg-Altstadt, Paris 4e Arrondissement), kunnan koodi kentässä territory.municipality_code. Italiaksi tuloksessa on FOREIGN, jota seuraavat muutokset, muilla kielillä vain muutokset; jos katu on olemassa mutta numero ei, HOUSE_NUMBER_NOT_FOUND. Muissa maissa työstämme muotoa, ja viesti kertoo sen: postinumero maan muodossa, kadun lyhenteet avattuina, isot kirjaimet ja kaupungin nimi niin kuin sen maan posti ne kirjoittaa (Hauptstr. 5, München → Hauptstraße 5, MÜNCHEN), maarivin kanssa. Molemmissa tapauksissa palautuu address_key, muoto, jolla kaksoiskappaleiden tunnistus tunnistaa saman kadun kahdella tavalla kirjoitettuna. Arvolla "foreign": "detect" tietue ilman maata, jota ei löydy Italiasta, tunnistetaan ulkomaiseksi, kun teksti sanoo sen selvästi; oletusarvo declared jättää ulkomaiseksi vain sen, mikä ilmoittaa sen. Täydellinen maaluettelo lyhyine ja virallisine nimineen, englanniksi ja maan kielellä, on saatavilla osoitteessa GET /api/v1/countries, ja sitä voi hakea parametreilla ?q=Germania, ?q=Deutschland tai ?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"}'

Erässä samat kentät kentän items sisällä; vastaus on { count, results: [ { id, result } ] } samassa järjestyksessä kuin lähetys.

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

Sama päätepiste toisen maan osoitteelle: country_code riittää. Tässä Hampuri, tarkistettu Saksan rekisteristä, kaupunginosan ja talonumeron koordinaattien kanssa.

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

Koko kutsua koskevat asetukset: postal_form (pakottaa myös kentän normalized postimuotoon), preserve_original (säilyttää käyttäjän kirjoittaman nimen ja antaa kanonisen erikseen), precision 1–5 (oletus 3; yli 3:n vastaavuus on likimääräinen eikä luotettavuus ole high).

Osoitteen mukana palautuu city_type, joka kertoo, onko jakelupaikka maakunnan pääkaupungissa vai maakunnan muussa kunnassa — ero, jolla on merkitystä sille, joka jakaa kampanjan kaupungeittain. provincial_capital on true, false tai null, kun meillä ei ole perusteita sanoa — ja silloin emme arvaa.

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

Postinumeron rinnalla tulee postcode_check: mistä se tulee (source) ja millä tarkkuudella (precision: house_number numero itse, interpolated saman kadun naapurinumerot, street kadun enemmistö, locality, municipality), kuinka moni osoitenumero sen sanoo (house_numbers) ja millä yksimielisyydellä (agreement, 0–1). Jos numerolle ei ole vahvistusta, tulos kantaa arvoa POSTCODE_UNCONFIRMED ja confirmed on false: postinumero jää annetuksi, jos se kuuluu kaupungille, ja se kannattaa tarkistaa.

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

Myös koordinaatit palautuvat kentässä geo (leveys- ja pituusaste WGS84) ja aluetunnisteet kentässä territory: Italiassa kunnan ISTAT-koodi ja kiinteistökoodi, CAB ja kadun kansallinen tunniste; muissa maissa country ja kunnan koodi kansallisessa rekisterissä (municipality_code). Kenttä precision kertoo, mille tasolle päästiin: house_number, kun talonumero on paikannettu, interpolated, kun tarkka numero puuttuu ja piste on arvioitu, street, kun meillä on kadun piste, municipality, kun meillä on vain kunnan keskipiste. source kertoo, mistä piste on peräisin: anncsu on Italian kansallinen rekisteri, inspire maan kansallinen rekisteri, osm OpenStreetMap: silloin tiedot ovat © OpenStreetMap contributors, ODbL-lisenssi, ja lähdemaininta on toistettava, jos julkaiset ne. Jos maan rekisteri vaatii lähdemaininnan, se tulee viestiin. Eräajojen CSV-tiedostossa ne ovat sarakkeet latitude, longitude, geo_precision, istat_code ja 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" } }

Osoitteeseen kirjoitettu kerros, porras ja huoneisto palautuvat myös omana tietonaan kentässä sub_address: luettelo type- ja value-pareja, luettuna maan postisääntöjen mukaan (Saksassa merkin ”//” jälkeen, Ranskassa omalla rivillään, Portugalissa ”3º Esq”). Tyypit ovat unit (huoneisto), staircase (porras), floor (kerros), block, building, building_number ja block_number. Osoiterivi pysyy maan muodossa. Mitä emme tunnista, jää sellaiseksi kuin se kirjoitettiin eikä tule luetteloon: emme arvaa. Kun annettu yksikkö löytyy tästä osoitenumerosta, sub_address_confirmed on true, muuten null, ei koskaan false: se, ettemme löydä sitä, ei tarkoita, että se olisi väärä.

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

Duplikaattien poiston päätepiste

Tunnistaa tietueet, jotka viittaavat samaan henkilöön samassa osoitteessa, vaikka ne olisi kirjoitettu eri tavalla: lempinimet ja nimien vastaavuudet (Dany ≈ Daniela), sukunimi ja etunimi vaihtaneet paikkaa, lyhenteet ("V. Roma" ≈ "Via Roma"), kirjoitusvirheet. Osoitteiden vertailu kulkee normalisointimoottorin kautta: saman kadun kaksi kirjoitusasua yhdistyvät kanoniseen muotoon ennen vertailua. Enintään 500 yhteystietoa kutsua kohden (tietueet + vertailulista); suuremmille listoille käytä erätyötä omalta tililtäsi.

Osoitekirjat. Osoitekirjan yhteystiedolla (Applen Yhteystiedot, Google, Outlook: vCard-malli) on useita osoitteita, puhelinnumeroita ja sähköposteja, kullakin oma nimikkeensä. Päätepiste ottaa ne vastaan sellaisinaan, ilman ylärajaa: addresses on lista objekteja, joissa on type ja tavalliset kentät; phones ja emails ovat listoja, joissa kukin alkio on pelkkä arvo ("340 7491386") tai {"type": "work", "value": "02 66710423"}, myös sekaisin; tavalliset litteät kentät pysyvät voimassa ja lasketaan ensimmäiseksi osoitteeksi ja ensimmäiseksi yhteystiedoksi. Kaksi yhteystietoa on sama henkilö, jos mikä tahansa niiden osoitteiden pari täsmää (toisen työpaikka toisen ainoan osoitteen kanssa), tai jos niillä on sama nimi ja yhteinen puhelin tai sähköposti, missä tahansa asemassa ja millä tahansa nimikkeellä. Nimike ei vaikuta täsmäytykseen: se palautuu sellaisena kuin se saapui, lisäksi type_normalized vCard-sanastossa (home, work, cell…), jotta sovellus tietää, mihin kirjoittaa takaisin. Yksi yhteystieto on yksi käsittely riippumatta siitä, montako osoitetta ja yhteystietoa sillä on.

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

Vastaus ryhmittelee duplikaatit kenttään groups: jokainen ryhmä luettelee jäsentensä id-tunnisteet kentässä members, ilmoittaa, mikä säilytetään (main_record), ja ehdottaa yhdistettyä tietuetta record: paras nimi ja osoitteiden ja yhteystietojen yhdiste (addresses, phones, emails), kullakin tyyppinsä, alkuperä kentässä provenance (mistä yhteystiedoista se tulee) ja duplikaatit poistettuina: sama katu kahdella kirjoitusasulla on yksi osoite, sama numero kahdella nimikkeellä yksi numero. Yhteystiedot, joille ei löytynyt vastinetta, ovat kentässä singles objekteina {id, outcome}: tuloksella outcome INTERNAL_DUPLICATE yhteystiedolla ei ole duplikaatteja muiden kanssa, mutta sillä on niitä sisällään (osoite kirjoitettu kahdesti, toistuva numero), ja se sisältää sulautetun tietueensa record. Se tunnistaa saman kadun eri tavoin kirjoitettuna ("V. Leopardi 4" ≈ "Via Giacomo Leopardi 4"), automaattisesti korjatun postinumeron ja paikkaa vaihtaneet sukunimen ja etunimen.

Italialaisen verotunnuksen päätepiste

Kolme toimintoa luonnollisten henkilöiden italialaiselle verotunnukselle (codice fiscale): generate luo sen henkilötiedoista, validate tarkistaa olemassa olevan koodin (muoto, tarkistusmerkki ja omocodia), extract poimii sen sisältämät tiedot — syntymäaika, ikä, sukupuoli, syntymäkunta tai ulkomainen syntymävaltio. Lisäksi compare tarkistaa, että koodi vastaa ilmoitettuja henkilötietoja. Kattaa kaikkien Italian kuntien ja ulkomaisten valtioiden kiinteistörekisterikoodit. Sukunimi ja etunimi on annettava latinalaisin kirjaimin: jos nimi on kirjoitettu muulla kirjaimistolla, koodi lasketaan asiakirjaan merkitystä translitteraatiosta, joka ei ole yksiselitteinen (Dmitrij/Dmitry); ei-latinalainen nimi palauttaa cognome_non_latino tai nome_non_latino, ja compare-toiminnossa ulkomailla syntyneen nimen ero tuo mukanaan huomautuksen mahdollisesti erilaisesta translitteraatiosta.

Ensimmäiset 500 kevyttä käsittelyä kuukaudessa ovat ilmaisia (verotunnus mukaan lukien), ja kiintiö on yksi ja sama kaikissa käyttötavoissa: se, mitä teet täällä, verkkosivulla ja erätiedostoissa, lasketaan samasta kiintiöstä. Sen ylittävältä osalta kevyet käsittelyt maksavat hintansa (ks. hinnat).

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

Suurille määrille: { "action": "validate", "items": [ … ] } käsittelee enintään 500 kohdetta kutsua kohden, kullakin oma korrelaatio-id. Poiminta merkitsee arvolla ambiguous_year tapaukset, joissa vuoden kaksi numeroa eivät erota vuosisataa (1926 vs. 2026).

Jokainen vastaus sisältää kentät outcome, reason, notes ja comments pyynnön kielellä: GENERATED toiminnolle generate, tyhjä kelvolliselle koodille toiminnossa validate, MATCH tai MISMATCH toiminnolle compare (ja differences: poikkeavat kentät). Kun koodi ei läpäise tarkistuksia, tulos on jokin alla luetelluista TAX_CODE_*-koodeista ja error antaa lyhyen muodon (check_digit, length, format, homocode, month, date, place, empty); toiminnossa generate se kertoo, mikä tieto puuttuu tai ei ratkea (last_name, first_name, gender, birth_date, birth_place, ambiguous_place ja options, last_name_non_latin). suggestion sisältää oikean koodin, kun tarkistus osaa rakentaa sen.

Rikastamisen päätepiste

Rikastaa nimen: sukupuoli pääteltynä etunimestä, kohteen tyyppi (luonnollinen henkilö tai oikeushenkilö), normalisoitu titteli (Dott.ssa, Avv., …) ja tervehdysmuodot valmiina kirjeenvaihtoon — "Egregio Sig. Rossi", "Gentile Dott.ssa Bianchi", "Spett.le" yrityksille, "Gentile Famiglia" perheille, "Caro/Cara" tuttavalliseen sävyyn. Tunnistaa myös sukunimen avioliittomuodon ("Rossi in Verdi" → nainen, molempien sukunimien erittelyllä). Kenttä gender hyväksyy myös kirjoitetut muodot (”maschio”, ”donna”, ”Sig.ra”, ”male”); X tarkoittaa organisaatiota ja G perhettä tai pariskuntaa. Jos titteli puuttuu, päättelemme sen kentästä profession (ammatti) tai education, kun jompikumpi on annettu. Sanastot ovat italialaisia.

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

Erissä: { "items": [ … ] }, enintään 500 kutsua kohden. Tulos on ENRICHED (sukupuoli ja tervehdykset asetettu), LEGAL_PERSON (yritys tai yhteisö: käsitellään toiminimenä) tai PARTIAL (etunimi puuttuu tai sukupuolta ei voi päätellä): reason kertoo miksi, comments mitä lisätä.

Sähköpostin tarkistuksen päätepiste

Tarkistaa sähköpostiosoitteen: syntaksi, verkkotunnuksen olemassaolo (MX/A-tietueet), yleisten verkkotunnusten kirjoitusvirheet korjausehdotuksen kanssa (gmial.com → gmail.com), kertakäyttöiset verkkotunnukset, yleisosoitteet (info@, laskutus@: eivät henkilön osoitteita). Emme tee yksittäisen postilaatikon SMTP-tarkistusta, joka on tungetteleva ja epäluotettava käytäntö. Erä items enintään 500; "dns": false ohittaa verkkotunnuksen haun.

Varma kirjoitusvirhe korjataan suoraan: kun osoite sellaisenaan ei ole edes osoite (nimi@verkkotunnus,fi pilkulla) tai kun korjaus osuu tunnettuun palveluntarjoajaan (gmai.com → gmail.com, myös yhden kirjaimen päässä, jos kirjoitettu verkkotunnus ei vastaanota postia), email palautuu korjattuna, corrected_from sisältää kirjoitetun muodon ja tulos on MODIFIED EMAIL_DOMAIN. Mahdollinen kirjoitusvirhe missä tahansa muussa verkkotunnuksessa (rossi.con) jää ehdotukseksi: EMAIL_TYPO ja korjaus kentässä suggestion, ja tarkistukset (domain_exists, domain_checked) tehdään sille; osoitetta sellaisenaan ei tarkisteta.

Puhelinnumeron tarkistuksen päätepiste

Tarkistaa numeron soittamatta kenellekään: muoto, luokka ja tyyppi, pituus numerointisuunnitelman mukaan, lankanumeron suuntanumeroalue ja operaattori, jolle numerolohko alun perin osoitettiin. class on se tulkinta, jota listan työstämiseen tarvitaan: mobile (voit lähettää tekstiviestin), landline (soitat virka-aikana), special (ei henkilön numero: hätänumerot, yleishyödylliset palvelunumerot, maksuttomat ja erikoismaksulliset numerot), foreign numeroille, joissa on kansainvälinen suuntanumero. Kun tunnistamme myös tarkan palvelun, type kertoo sen (maksuton, erikoismaksullinen, jaettu kustannus, yleishyödyllinen palvelu). Ilman plusmerkkiä kirjoitetun Italian suuntanumeron (39347…, klassinen vientitiedostojen virhe) poistamme, kun numerot eivät jätä epäilystä — 3934567890 pysyy matkapuhelinnumerona, joka se on. Jos samassa kentässä on useita numeroita (”347… - 338…”), erotamme ne: ne palautuvat kenttinä phone, phone2, phone3, eikä phone ole koskaan tyhjä, kun vähintään yksi numero on olemassa. Asetuksella "format": "international" italialainen numero tulee muodossa +39…; oletusarvo national jättää sen ilman suuntanumeroa ja lisää suuntanumeron vain ulkomaisiin. Ulkomaisille numeroille palautuu myös e164, suuntanumeron maa kentässä country_code, ja suuntanumeron jälkeinen kotimaan nolla poistetaan (”+44 (0)20…” ja ”+44 20…” antavat saman numeron). Kun kutsussa tai kohteessa on country_code (tai country), ilman suuntanumeroa kirjoitettu numero luetaan kyseisen maan kansalliseksi numeroksi: ”020 7946 0958” Yhdistyneen kuningaskunnan tietueessa on Lontoo, ei Milano. Ilman maata se pysyy italialaisena. Erä items enintään 500.

Tietueen oman maan numero ei ole ”ulkomainen”: siellä missä tunnemme numerointisuunnitelman se saa oman class-arvonsa (mobile, landline, special), format-arvolla national se pysyy ilman maatunnusta maansa muodossa (suuntanumeron nolla mukaan lukien), ja e164-kentän rinnalla palautuu national_number. PHONE_FOREIGN ja class foreign jäävät numeroille, jotka ovat eri maasta kuin tietue.

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

Verkkosivun tarkistuksen päätepiste

Tarkistaa, että osoite on oikein kirjoitettu ja että sivusto todella vastaa: verkkotunnuksen olemassaolo, HTTP-pyyntö uudelleenohjauksia seuraten, lopullinen vastauskoodi, varmenteen kelvollisuus. Sisältöä ei arvioida. Myös tässä useat osoitteet samassa kentässä palautuvat muodossa website, website2, website3. Asetuksella "network": false tarkistamme vain muodon ottamatta yhteyttä sivustoon. Erä items enintään 100: jokainen tarkistus avaa yhteyden, joten erä on pienempi kuin muissa päätepisteissä.

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

Osoitteiden automaattitäydennyksen päätepiste

Aloitatko tyhjästä? Widget ra-suggerisci.js ja pieni välityspalvelin omalla palvelimellasi riittävät: token ei koskaan päädy selaimeen.

Ehdotuksia sitä mukaa kuin käyttäjä kirjoittaa osoitetta lomakkeeseesi: koko Italian katurekisteri nimi täydennettynä (”via verdi” → ”Via Giuseppe Verdi”), kunta ja maakunta; postinumero tulee valinnan mukana, suurissa postinumeroalueisiin jaetuissa kaupungeissa talonumeron oikea. Toimii istunnoittain: asiakasohjelma luo UUID:n jokaiselle täytettävälle osoitteelle, ehdotuskyselyt ovat ilmaisia, ja maksat yhden yhteystiedon tarkistuksen, kun käyttäjä valitsee ja kentät täyttyvät (toiminto select, joka palauttaa moottorin jo normalisoiman tietueen). Lomakkeeseen jo täytetyt kentät — myös osittaiset — kulkevat mukana kontekstina ja rajaavat ehdotuksia.

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

Kun katu on valittu, talonumero täydentyy: antamalla street_id osittaisen numeron kanssa saat kadun olemassa olevat numerot ja arvon exists tosi/epätosi kirjoitetun numeron tarkistamiseen — ja valinnan voi toistaa talonumeron kanssa ilman lisäveloitusta: veloitus on istunto- ja katukohtainen, ei napsautuskohtainen; toinen katu samassa istunnossa on uusi veloitus. Talonumerot täydennetään vain siinä istunnossa, joka valitsi kyseisen kadun. Postinumeroalueisiin jaetuissa kaupungeissa juuri talonumero määrää tarkan postinumeron.

API-token ei koskaan mene selaimeen: valmis widget (ra-suggerisci.js) kutsuu palvelimellasi olevaa pientä välityspalvelinta, joka lisää tokenin ja välittää pyynnön eteenpäin. Jokainen istunto sallii enintään 30 kutsua ja kestää 10 minuuttia; istunnot ilman valintaa ovat ilmaisia 200:aan asti päivässä tokenia kohti, plus viisi jokaista valintaa kohti. Widget, valmis proxy ja esimerkkilomake ovat Oma lomakkeesi -kitissä.

Toimii jokaisessa palvelussa olevassa maassa (tänään Ranska, Saksa, Espanja, Alankomaat, Belgia, Suomi, Tšekki, Portugali, Tanska, Norja, Itävalta, Sveitsi, Slovakia, Kroatia, Romania, Unkari, Slovenia, Irlanti, Islanti, Luxemburg, Liechtenstein, San Marino, Monaco, Andorra, Vatikaanivaltio; ajantasainen luettelo on kohdassa Maat): kun annat country_code tai country, ehdotukset tulevat sen maan rekisteristä, ja teksti kirjoitetaan kuten siellä kirjoitetaan — katu, numero, postinumero ja kaupunki vaikka yhteen kenttään: «kalverstraat 92 amst», «92 rue de rivoli paris», Alankomaissa «1012PH 92». Jokainen vastaus sisältää kentän parsed, eli miten palvelin luki kadun (street), numeron (house_number) ja postinumeron (postcode): lomakkeesi tietää, missä numero on, tuntematta maan sääntöjä. Ehdotukset sisältävät kadun, kaupungin, mahdollisen kylän ja kentän source (registry, tai osm siellä, missä kansallinen rekisteri ei julkaise); postinumero ja talonumerot eivät koskaan ole ehdotuksissa: ne tulevat valinnan mukana, joka kulkee moottorin läpi ja palauttaa saman tietueen kuin /contact (postcode rekisterin vahvistamana, geo talonumeron tarkkuudella). Valinnan mukana voit antaa myös kentän postcode, lomakkeeseen kirjoitetun. attribution on lähdemerkintä, joka näytetään ehdotusten vieressä: rekisterin lisenssi vaatii sen. Jos maa puuttuu, oletetaan IT; maalle, joka ei ole palvelussa, vastaus on edelleen HTTP 200 ja supported:false sekä hints:[], ilman istuntoa ja ilman veloitusta. Istunto kuuluu yhdelle maalle: jos maa vaihtuu, asiakas luo uuden UUID:n (muuten 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"}

Suuret määrät: asynkroninen työ

Tavalliset kutsut vastaavat heti, ja siksi niillä on kohteiden yläraja — minuutteja kestävä HTTP-pyyntö ei hyödytä ketään. Ylärajat seuraavat käsittelyn raskautta:

Näiden lukujen yli listaa ei tarvitse pilkkoa käsin: lisää "async": true, niin kutsu palaa heti koodin kanssa ja käsittely menee samaan jonoon kuin tiedostojen lataukset. Enintään 100 000 kohdetta kutsua kohden, ja sivulla Omat työt näkyy vain yksi työ.

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}

Sen jälkeen tulos luetaan tarvittaessa, ja se saapuu JSON-muodossa tai CSV-tiedostona:

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

Alle 5 000 rivillä tulos palautuu myös kentässä results JSON-vastauksen sisällä; sen yli se ladataan CSV-tiedostona. Veloitus tapahtuu, kun työ laitetaan jonoon, ja käsittelemättä jäänyt osa palautuu saldoosi, jos työ pysähtyy. Tokenin on kuuluttava tilille: työ päätyy sinun jonoosi.

Tuloskoodit

Jokainen vastaus sisältää kentän outcome: luettelo avainsanoja, tyhjä, kun ei ole mitään ilmoitettavaa. Kaava on aina <conditions> [MODIFIED <types>] — ehdot edessä, muutokset lopussa — ja se pätee kaikkiin palveluihin. Vieressä on outcome_label (tai kind) arvoilla ok, modified, warning, error, sekä reason, joka selittää yhdellä rivillä. Koodit ovat tunnisteita: niitä verrataan, ei käännetä; "language": "it"-arvolla tulevat italialaiset koodit (LOCALITA_NON_TROVATA MODIFICATO CAP INDIRIZZO), samat sana sanalta.

Osoite (yhteystiedon tarkistus)

Italian verotunnus (codice fiscale)

Päätepisteessä /tax-code samoilla tarkistuksilla on omat koodinsa — 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 — koska siellä verotunnus on tarkistuksen kohde, ei tietueen kenttä.

Rikastaminen

Sähköposti

Puhelin

Verkkosivu

Mitä kukin kutsu kuluttaa

Jokainen kutsu kuluttaa palvelun laskurin käsittelyjä: yhteystiedon tarkistus (/contact, /suggest valittaessa), duplikaattien poisto (/dedupe) ja kevyet käsittelyt (/email, /phone, /website, /enrichment, /tax-code ilmaiskiintiön yli). Käsittelyjä ostetaan paketteina, jotka säilyvät, tai kuukausitilauksella; hinta 1 000 käsittelyä kohden laskee koon kasvaessa ja löytyy hintasivulta. Joka kuukausi ilmaisia ovat 50 yhteystiedon tarkistusta, 100 tietuetta duplikaattien poistossa ja 500 kevyttä käsittelyä.

Jokainen vastaus kertoo, mitä se kulutti ja mistä: JSON-vastauksen kenttä credit (counter, charged, free, subscription ja packs otettujen käsittelyjen ja jäljellä olevien kanssa, available, auto_topup automaattisesti ostettujen pakettien määrän kanssa, note) sekä otsakkeet X-RA-Charged, X-RA-Available ja, kun se aktivoituu, X-RA-Auto-Topup. Jos käytettävissä olevat käsittelyt eivät kata kutsua eikä laskurin automaattinen täydennys ole käytössä (tai se epäonnistuu), vastaus on 402 payment_required eikä mitään käsitellä.

Jäljellä olevien käsittelyjen määrän saa selville kuluttamatta yhtään kutsulla GET /api/v1/credit. Jokaiselle kolmesta laskurista (contact, dedupe, light) se palauttaa arvon available, kuukauden jäljellä olevat ilmaiset (free) ja päivän, jolloin ne nollautuvat (1. päivä), tilauksen subscription (jäljellä, koko, uusiutuminen), aktiiviset paketit packs yksi kerrallaan jäljellä olevine käsittelyineen (ne eivät vanhene) ja ostettujen määrän, automaattisen täydennyksen auto_topup (käytössä, koko, katto ja kuukauden kulutus euroina), käytön (used tässä kuussa, yhteensä, viimeisin käyttö) ja ennen kaikkea tilan state, koska pelkkä nolla ei kerro, ovatko käsittelyt loppuneet vai etkö käytä kyseistä palvelua: never_used, free (ei koskaan ostettu, työskentelet kuukauden ilmaisilla), free_used_up, active, awaiting_renewal, used_up (olet ostanut aiemmin eikä mitään ole jäljellä: täydennä), sekä huomautuksen warning. Ylimpänä needs_topup luettelee laskurit, jotka vaativat toimia, ja endpoint kertoo, mitä laskuria kukin päätepiste kuluttaa. Vaatii tilin tokenin.

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

Maksat tarkistettua kohdetta kohden, et kutsua kohden: jos kentässä on kaksi puhelinnumeroa tai kaksi sähköpostia, tarkistamme ne kaikki (enintään kolme riviä kohden), ja jokainen maksaa oman hintansa. Eräkutsu kuluttaa yhtä paljon kuin sen sisältämät käsittelyt. Jos krediitit ovat lopussa eikä automaattinen täydennys ole käytössä, API vastaa HTTP 402 (riittämättömät krediitit); kutsurajan ylityttyä se vastaa HTTP 429 arvolla retry_after. Ostat paketin omalta tililtäsi tai aktivoit tilauksen maksaaksesi käsittelystä vähemmän.