Sama vélin,
inni í þínu appi.

Einn endapunktur fyrir hverja þjónustu, með sama nafni og þjónustan hefur á þessum vef: /contact, /dedupe, /email, /phone, /website, /tax-code, /enrichment. Hver þeirra tekur við einu atriði í meginmáli beiðninnar eða lista í items, allt að 500 í hverju kalli (100 fyrir vefsíður, sem þarf að hafa samband við eina í einu). Tvítakahreinsunin er undantekningin og vill alltaf lista: hún ber spjöldin saman innbyrðis. Til hliðar standa /suggest, sjálfvirka útfyllingin fyrir eyðublöð (hún vinnur á setu meðan notandinn slær inn, ekki í lotum), og /credit, sem segir hve margar vinnslur eru eftir og í hvaða stöðu hver teljari er, án þess að nota neina.

Auðkenning

Hýsill API er www.radaraddress.com. Nöfn reita, endapunkta og gilda eru ensk auðkenni, þau sömu á öllum tungumálum; merkimiðar, ástæður og skilaboð fylgja tungumáli beiðninnar ("language": "de" eða ?language=de, eða hausinn Accept-Language, eða tungumál aðgangsins). Hausinn Content-Language segir á hvaða tungumáli svarið barst.

Aðgangur að API er með Bearer-tákni. Aðgangurinn er ókeypis: þú býrð til táknið á aðgangssvæðinu þínu og setur það í haus hverrar beiðni á þessu formi:

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

Við stofnun getur þú gefið tákninu valfrjálsan gildistíma: eftir þann dag fá beiðnir HTTP 401 með kóðanum token_expired; án gildistíma gildir táknið þar til þú afturkallar það. Þú getur afturkallað það eða endurnýjað hvenær sem er á aðgangssvæðinu þínu, þar sem þú sérð líka síðustu notkun og fjölda afgreiddra beiðna. Beiðni án tákns eða með ógildu tákni skilar HTTP 401.

Ítölsku nöfnin, fyrir þá sem nota þau þegar

API hefur aðeins eina útgáfu, á ensku. Sá sem tengdi með ítölsku nöfnunum þarf engu að breyta: ítölsku reitirnir eru samþykktir í hverri beiðni, endapunktarnir svara líka undir ítölsku nöfnunum (/contatto, /deduplica, /codicefiscale, /arricchimento, /telefono, /sito, /suggerisci, /nazioni, /credito), og svarið kemur út með ítölsku lyklunum og kóðunum fyrir þann sem biður um það með "language": "it" eða kallar á www.radaraddress.it án þess að tilgreina tungumál.

Fulla taflan yfir reitina: enska → ítalska

enska	ítalska	enska	ítalska
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

Gildi valkostanna hafa líka ítalskt nafn: format nazionale/internazionale, action genera/valida/estrai/confronta/seleziona, foreign dichiarati/rileva, min_level certo/probabile/ambiguo; með "language": "it" gera það líka level, confidence, state, kóðar outcome og dálkaheiti skjalanna. Algeng samheiti eru líka samþykkt í inntaki (zip, surname, phone_number, date_of_birth…), og sömu dálkaheiti í skjölum hópvinnslna.

Endapunktur sannprófunar tengiliða

Lagar allan tengiliðinn: heimilisfangið samkvæmt póststaðli lands síns — á Ítalíu og í löndunum þar sem skráin er í notkun eru gata og húsnúmer sannreynd í heimilisfangaskrá landsins; annars staðar kemur heimilisfangið út á póstformi landsins —, nafnið og — ef beiðnin ber það — ítalska skattnúmerið, sem er hreinsað, fyllt inn þegar aðeins vantar vartöluna og borið saman við eftirnafn, fornafn, kyn og fæðingardag. Einn tengiliður í einu, eða allt að 500 í items: skemað er það sama og fyrir alla aðra endapunkta.

Landið er gefið upp með country_code (ISO 3166-1: IT, DE, FR…) eða með country, skrifað hvernig sem er: „Germania“, „Germany“, „Deutschland“, „Sambandslýðveldið Þýskaland“, „UK“, „Holland“. Ef það vantar er gert ráð fyrir Ítalíu. Í löndunum þar sem skráin er í notkun — í dag Frakkland, Þýskaland, Spánn, Holland, Belgía, Finnland, Tékkland, Portúgal, Danmörk, Noregur, Austurríki, Sviss, Slóvakía, Króatía, Rúmenía, Ungverjaland, Slóvenía, Írland, Ísland, Lúxemborg, Liechtenstein, San Marínó, Mónakó, Andorra, Vatíkanið, uppfærði listinn er í Löndum — eru gata og húsnúmer sannreynd í heimilisfangaskrá landsins alveg eins og á Ítalíu: póstnúmer staðfest eða fyllt inn, hnit húsnúmersins í geo, hverfi eða arrondissement í district þar sem borgin hefur slíkt (Hamburg-Altstadt, Paris 4e Arrondissement), kóði sveitarfélagsins í territory.municipality_code. Á ítölsku ber niðurstaðan FOREIGN og svo breytingarnar, á hinum tungumálunum aðeins breytingarnar; ef gatan er til en númerið ekki, HOUSE_NUMBER_NOT_FOUND. Í hinum löndunum vinnum við með formið, og skilaboðin segja frá því: póstnúmer á sniði landsins, skammstafanir götunnar leystar upp, hástafir og borgarnafn eins og póstur þess lands skrifar þau (Hauptstr. 5, Munich → Hauptstraße 5, MÜNCHEN), með landslínunni. Í báðum tilvikum kemur address_key til baka, formið sem tvítakahreinsunin notar til að þekkja sömu götu skrifaða á tvo vegu. Með "foreign": "detect" er færsla án lands, sem finnst ekki á Ítalíu, þekkt sem erlend þegar textinn segir það skýrt; sjálfgefna gildið declared lætur aðeins það vera erlent sem lýsir því yfir. Full skrá yfir löndin, með stuttu og opinberu nafni, á ensku og á tungumáli landsins, er fáanleg með GET /api/v1/countries og má spyrja með ?q=Germania, ?q=Deutschland eða ?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"}'

Fyrir lotuna, sömu reitir inni í items; svarið er { count, results: [ { id, result } ] } í sömu röð og sent var.

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

Sami endapunktur fyrir heimilisfang í öðru landi: country_code nægir. Hér Hamborg, sannreynd í þýsku skránni, með hverfinu og hnitum húsnúmersins.

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

Valkostir sem gilda fyrir allt kallið: postal_form (þvingar líka normalized á póstform), preserve_original (heldur nafninu eins og notandinn skrifaði það og sýnir staðlaða nafnið sér), precision 1–5 (sjálfgefið 3; yfir 3 er samsvörunin nálguð og áreiðanleikinn verður ekki high).

Með heimilisfanginu kemur city_type, sem segir hvort afhendingarstaðurinn er í héraðshöfuðstað eða í bæ í héraðinu — munurinn sem skiptir máli fyrir þann sem skiptir herferð eftir borgum. provincial_capital er true, false eða null þegar við höfum engar forsendur til að segja það — og í því tilviki giskum við ekki.

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

Við hlið póstnúmersins kemur postcode_check: hvaðan það kemur (source) og hve nákvæmlega (precision: house_number númerið sjálft, interpolated nágrannanúmer sömu götu, street meirihluti götunnar, locality, municipality), hve mörg húsnúmer segja það (house_numbers) og með hve mikilli samstöðu (agreement, 0 til 1). Vanti staðfestingu fyrir númerið ber niðurstaðan POSTCODE_UNCONFIRMED og confirmed er false: póstnúmerið helst eins og gefið, ef það tilheyrir borginni, og ætti að athuga.

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

Hnitin koma líka til baka, í geo (breiddar- og lengdargráða WGS84), og landfræðilegu auðkennin í territory: á Ítalíu ISTAT-kóði og fasteignakóði sveitarfélagsins, CAB og landsauðkenni götunnar; í hinum löndunum country og kóði sveitarfélagsins í landsskránni (municipality_code). Reiturinn precision segir hvaða stigi við náðum: house_number þegar húsnúmerið er hnitsett, interpolated þegar nákvæmt númer vantar og punkturinn er áætlaður, street þegar við höfum punkt götunnar, municipality þegar við höfum aðeins miðju sveitarfélagsins. source segir hvaðan punkturinn kemur: anncsu er ítalska landsskráin, inspire landsskrá landsins, osm OpenStreetMap: í því tilviki eru gögnin © OpenStreetMap contributors, ODbL-leyfi, og tilvísunina þarf að birta ef þú gefur þau út. Þar sem skrá lands krefst tilvísunar kemur hún út í skilaboðunum. Í CSV-skrá hópvinnslna eru þetta dálkarnir 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" } }

Hæð, stigagangur og íbúð sem skrifuð eru í heimilisfangið koma líka til baka sem sérstök gögn í sub_address: listi af pörum type og value, lesin eftir póstreglum landsins (í Þýskalandi á eftir „//“, í Frakklandi í sérlínu, í Portúgal „3º Esq“). Tegundirnar eru unit (íbúð), staircase (stigagangur), floor (hæð), block, building, building_number og block_number. Heimilisfangslínan helst á formi landsins. Það sem við þekkjum ekki stendur eins og það var skrifað og fer ekki á listann: við giskum ekki. Þegar uppgefin eining finnst á þessu húsnúmeri er sub_address_confirmed true, annars null, aldrei false: þótt við finnum hana ekki þýðir það ekki að hún sé röng.

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

Endapunktur tvítakahreinsunar

Þekkir færslurnar sem vísa til sömu manneskju á sama heimilisfangi jafnvel þegar þær eru skrifaðar á ólíkan hátt: gælunöfn og jafngildi nafna (Dany ≈ Daniela), eftirnafn og fornafn víxluð, skammstafanir ("V. Roma" ≈ "Via Roma"), innsláttarvillur. Samanburður heimilisfanganna fer í gegnum stöðlunarvélina: tveir rithættir sömu götu falla saman á staðlaða formið fyrir samanburðinn. Að hámarki 500 tengiliðir í hverju kalli (spjöld + viðmið); fyrir stærri lista notarðu hópvinnslu af aðgangssvæðinu þínu.

Tengiliðaskrár. Tengiliður í tengiliðaskrá (Tengiliðir hjá Apple, Google, Outlook: vCard-líkanið) hefur fleiri heimilisföng, símanúmer og netföng, hvert með merkimiða. Endapunkturinn tekur við þeim eins og þau eru, án þaks: addresses er listi hluta með type og venjulegu reitunum; phones og emails eru listar þar sem hvert atriði er bert gildi ("340 7491386") eða {"type": "work", "value": "02 66710423"}, líka blandað; venjulegu flötu reitirnir gilda áfram og teljast sem fyrsta heimilisfang og fyrsta samskiptaupplýsing. Tveir tengiliðir eru sama manneskjan ef eitthvert par heimilisfanga þeirra passar saman (skrifstofa annars við eina heimilisfang hins), eða ef þeir hafa sama nafn og símanúmer eða netfang sameiginlegt, í hvaða stöðu sem er og með hvaða merkimiða sem er. Merkimiðinn vegur ekki í samsvöruninni: hann kemur til baka eins og hann barst, auk type_normalized í vCard-orðaforðanum (home, work, cell…), svo appið viti hvert á að skrifa til baka. Einn tengiliður er ein vinnsla, hve mörg heimilisföng og samskiptaupplýsingar sem hann hefur.

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

Svarið flokkar tvítökin í groups: hver hópur telur upp id hvers members, segir hvaða á að halda (main_record) og leggur til sameinaða record: besta nafnið og sammengi heimilisfanga og samskiptaupplýsinga (addresses, phones, emails), hvert með sinni tegund, með provenance (úr hvaða tengiliðum það kemur) og án tvítaka: sama gatan í tveimur rithættum er eitt heimilisfang, sama númerið með tveimur merkimiðum eitt númer. Tengiliðir án samsvörunar eru í singles, sem hlutir {id, outcome}: með outcome INTERNAL_DUPLICATE hefur tengiliðurinn engin tvítök við aðra en hefur slík innan sín (heimilisfang skrifað tvisvar, endurtekið númer), og ber sína sameinuðu record. Hún þekkir sömu götu skrifaða á ólíkan hátt ("V. Leopardi 4" ≈ "Via Giacomo Leopardi 4"), póstnúmerið lagað sjálfkrafa og eftirnafn og fornafn víxluð.

Endapunktur ítalska skattnúmersins

Þrjár aðgerðir á ítalska skattnúmeri (codice fiscale) einstaklinga: generate út frá persónuupplýsingum, validate fyrirliggjandi kóða (snið, vartala og omocodia), extract upplýsingarnar sem hann inniheldur — fæðingardag, aldur, kyn, sveitarfélag eða erlent fæðingarland. Að auki athugar compare hvort kóði passi við uppgefnar persónuupplýsingar. Hún nær yfir fasteignakóða allra ítalskra sveitarfélaga og erlendra ríkja. Eftirnafn og fornafn þarf að senda með latneskum stöfum: fyrir þann sem ber nafn með öðru stafrófi er kóðinn reiknaður út frá umrituninni sem stendur á skilríkinu, sem er ekki einhlít (Dmitrij/Dmitry); nafn sem er ekki latneskt skilar cognome_non_latino eða nome_non_latino, og í compare ber munur á nafni þess sem fæddist erlendis athugasemd um hugsanlega ólíka umritun.

Fyrstu 500 léttu vinnslurnar á mánuði eru ókeypis (skattnúmer meðtalið), og kvótinn er einn og sami hvernig sem þjónustan er notuð: það sem þú gerir hér, á vefnum og í hópvinnsluskjölum telur á sama kvóta. Umfram það greiðast léttar vinnslur á sínu verði (sjá verð).

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

Fyrir magn: { "action": "validate", "items": [ … ] } vinnur allt að 500 atriði í hverju kalli, hvert með sínu eigin samsvörunar-id. Útdrátturinn merkir með ambiguous_year tilvikin þar sem tveir tölustafir ársins greina ekki öldina (1926 á móti 2026).

Hvert svar ber outcome, reason, notes og comments á tungumáli beiðninnar: GENERATED fyrir generate, tómt fyrir gildan kóða í validate, MATCH eða MISMATCH fyrir compare (með differences: reitirnir sem víkja frá). Standist kóðinn ekki athuganirnar er niðurstaðan einn af TAX_CODE_*-kóðunum hér að neðan og error gefur stutta formið (check_digit, length, format, homocode, month, date, place, empty); í generate segir það hvaða gögn vantar eða leysast ekki (last_name, first_name, gender, birth_date, birth_place, ambiguous_place með options, last_name_non_latin). suggestion ber rétta kóðann þegar athugunin getur endurgert hann.

Endapunktur auðgunar

Auðgar nafn: kyn leitt af fornafninu, tegund aðila (einstaklingur eða lögaðili), staðlaður titill (Dott.ssa, Avv., …) og ávörp tilbúin fyrir bréfaskriftir — "Egregio Sig. Rossi", "Gentile Dott.ssa Bianchi", "Spett.le" fyrir fyrirtæki, "Gentile Famiglia" fyrir heimili, "Caro/Cara" fyrir óformlegt málsnið. Hún þekkir líka giftingarnafnsformið í eftirnafninu ("Rossi in Verdi" → kona, með sundurliðun eftirnafnanna tveggja). Reiturinn gender tekur líka við rituðum formum („maschio“, „donna“, „Sig.ra“, „male“); X merkir stofnun og G fjölskyldu eða par. Ef titilinn vantar leiðum við hann af profession (starfinu) eða af education, þegar annað hvort er gefið upp. Orðasöfnin eru ítölsk.

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

Í bunkum: { "items": [ … ] }, allt að 500 í hverju kalli. Niðurstaðan er ENRICHED (kyn og ávörp sett), LEGAL_PERSON (fyrirtæki eða stofnun: meðhöndlað sem fyrirtækjanafn) eða PARTIAL (fornafn vantar eða kyn verður ekki leitt af nafninu): reason segir hvers vegna, comments hverju á að bæta við.

Endapunktur sannprófunar netfanga

Sannreynir netfang: málskipan, tilvist lénsins (MX/A-færslur), innsláttarvillur í algengum lénum með leiðréttingartillögu (gmial.com → gmail.com), einnota lén, hlutverkanetföng (info@, bokhald@: ekki manneskja). Við gerum ekki SMTP-sannprófun á einstökum pósthólfum, sem er ágeng og óáreiðanleg aðferð. Lota items allt að 500; "dns": false sleppir uppflettingu lénsins.

Örugg innsláttarvilla er leiðrétt umsvifalaust: þegar netfangið eins og það er skrifað er ekki einu sinni netfang (name@domain,com með kommu) eða þegar leiðréttingin lendir á vel þekktri póstþjónustu (gmai.com → gmail.com, líka með einn staf á milli þegar skrifaða lénið tekur ekki við pósti), kemur email út leiðrétt, corrected_from ber það sem skrifað var og niðurstaðan er MODIFIED EMAIL_DOMAIN. Hugsanleg innsláttarvilla á hvaða öðru léni sem er (rossi.con) er áfram tillaga: EMAIL_TYPO með leiðréttinguna í suggestion, og athuganirnar (domain_exists, domain_checked) keyrðar á hana; netfangið eins og það er skrifað er ekki sannreynt.

Endapunktur sannprófunar símanúmera

Athugar númer án þess að hringja í neinn: form, flokkur og tegund, lengd samkvæmt númeraskipulaginu, svæði heimasímans og símafyrirtækið sem blokkinni var upphaflega úthlutað. class er lesturinn sem þú þarft til að vinna lista: mobile (þú getur sent SMS), landline (þú hringir á skrifstofutíma), special (ekki númer manneskju: neyðarnúmer, almannaþjónusta, gjaldfrjáls númer og yfirgjaldsnúmer), foreign fyrir númer með alþjóðlegu forskeyti. Þegar við þekkjum líka nákvæma þjónustu, segir type frá því (gjaldfrjálst, yfirgjald, skipt gjald, almannaþjónusta). Ítalska forskeytið skrifað án + (39347…, klassísk villa í útflutningum) er fjarlægt þegar tölustafirnir skilja engan vafa eftir — 3934567890 helst farsíminn sem það er. Ef sami reitur inniheldur fleiri númer („347… - 338…“) skiptum við þeim: þau koma til baka sem phone, phone2, phone3, og phone er aldrei tómt þegar að minnsta kosti eitt númer er til staðar. Með "format": "international" kemur ítalska númerið út sem +39…; sjálfgefna gildið national skilur það eftir bert og bætir forskeytinu aðeins við erlend númer. Fyrir erlend númer færðu líka e164, land forskeytisins í country_code, og svæðisnúllið á eftir forskeytinu er fjarlægt („+44 (0)20…“ og „+44 20…“ gefa sama númer). Með country_code (eða country) í kallinu eða í atriðinu er númer skrifað án forskeytis lesið sem landsnúmer þess lands: „020 7946 0958“ í bresku spjaldi er London, ekki Mílanó. Án lands helst það ítalskt. Lota items allt að 500.

Númer úr eigin landi færslunnar er ekki „erlent“: þar sem við þekkjum númeraskipulagið fær það sinn class (mobile, landline, special), með format national helst það án landsnúmers á formi lands síns (svæðisnúll meðtalið), og national_number er skilað við hliðina á e164. PHONE_FOREIGN og class foreign gilda áfram fyrir númer frá öðru landi en landi færslunnar.

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

Endapunktur sannprófunar vefsíðna

Athugar hvort vefslóðin sé rétt skrifuð og hvort síðan svari í raun: tilvist lénsins, HTTP-beiðni með áframsendingum fylgt, lokakóði, gildi vottorðsins. Enginn dómur um innihaldið. Hér koma líka fleiri slóðir í sama reit til baka sem website, website2, website3. Með "network": false athugum við aðeins formið, án þess að hafa samband við síðuna. Lota items allt að 100: hver athugun opnar tengingu, svo lotan er minni en á hinum endapunktunum.

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

Endapunktur sjálfvirkrar útfyllingar heimilisfanga

Byrjar þú frá grunni? Smáforritið ra-suggerisci.js og lítill milliþjónn á vefþjóninum þínum er allt sem þarf: táknið fer aldrei í vafrann.

Tillögur meðan notandinn slær inn heimilisfang í eyðublaðið þitt: öll ítalska götuskráin, með nafnið fyllt út („via verdi“ → „Via Giuseppe Verdi“), sveitarfélag og hérað; póstnúmerið kemur með valinu, í stóru svæðisskiptu borgunum það rétta fyrir húsnúmerið. Það vinnur á setu: biðlarinn býr til UUID fyrir hvert heimilisfang sem verið er að fylla út, tillögufyrirspurnirnar eru ókeypis, og þú greiðir eina sannprófun tengiliðar þegar notandinn velur og reitirnir fyllast (aðgerðin select, sem skilar færslunni þegar staðlaðri af vélinni). Reitirnir sem þegar eru útfylltir í eyðublaðinu — jafnvel að hluta — ferðast með sem samhengi og þrengja tillögurnar.

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

Þegar gatan hefur verið valin fyllist húsnúmerið út: með því að senda street_id með númerinu að hluta færðu fyrirliggjandi númer þeirrar götu, með exists satt/ósatt til að sannreyna það sem slegið var inn — og valið má endurtaka með húsnúmerinu án aukagjalds: gjaldið er á setu og á götu, ekki á smell; önnur gata í sömu setu er nýtt gjald. Húsnúmer eru aðeins fyllt út í þeirri setu sem valdi þá götu. Í svæðisskiptum borgum er það húsnúmerið sem ræður nákvæmu póstnúmeri.

API-táknið fer aldrei í vafrann: tilbúna smáforritið (ra-suggerisci.js) kallar á lítinn milliþjón á vefþjóninum þínum, sem bætir tákninu við og sendir áfram. Hver seta leyfir allt að 30 köll og gildir í 10 mínútur; setur án vals eru ókeypis upp að 200 á dag á hvert tákn, auk fimm fyrir hvert val. Widget, tilbúinn proxy og dæmaform eru í pakkanum á Formið þitt.

Virkar í hverju landi í þjónustu (í dag Frakkland, Þýskaland, Spánn, Holland, Belgía, Finnland, Tékkland, Portúgal, Danmörk, Noregur, Austurríki, Sviss, Slóvakía, Króatía, Rúmenía, Ungverjaland, Slóvenía, Írland, Ísland, Lúxemborg, Liechtenstein, San Marínó, Mónakó, Andorra, Vatíkanið; uppfærður listi er undir Lönd): með country_code eða country koma tillögurnar úr skrá þess lands og textinn er skrifaður eins og fólk skrifar hann þar — gata, húsnúmer, póstnúmer og staður jafnvel í einum reit: «kalverstraat 92 amst», «92 rue de rivoli paris», í Hollandi «1012PH 92». Hvert svar ber parsed, þ.e. hvernig þjónninn las götuna (street), númerið (house_number) og póstnúmerið (postcode): eyðublaðið þitt veit hvar númerið stendur án þess að þekkja reglur landsins. Tillögurnar bera götu, stað, hverfi ef til er, og source (registry, eða osm þar sem landsskráin birtir ekkert); póstnúmer og húsnúmer eru aldrei í tillögunum: þau koma með valinu, sem fer í gegnum vélina og skilar sömu færslu og /contact (postcode staðfest af skránni, geo á húsnúmer). Með valinu má einnig senda postcode, það sem skrifað var í eyðublaðið. attribution er heimildartilvísunin sem á að birta við hlið tillagnanna: leyfi skrárinnar krefst þess. Vanti landið er gert ráð fyrir IT; fyrir land utan þjónustu er svarið áfram HTTP 200 með supported:false og hints:[], án lotu og án gjaldfærslu. Lota tilheyrir einu landi: breytist það býr biðlarinn til nýtt 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"}

Mikið magn: ósamstillt verk

Venjuleg köll svara strax, og þess vegna hafa þau þak á atriðum — HTTP-beiðni sem tekur mínútur gagnast engum. Þökin fylgja því hve dýr aðgerðin er:

Umfram þær tölur þarf ekki að skipta listanum upp handvirkt: bættu við "async": true og kallið skilar strax kóða, meðan vinnslan fer í sömu biðröð og skjalaupphleðslur. Allt að 100.000 atriði í hverju kalli, og í Verkin mín birtist eitt eina.

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}

Svo lestu það þegar þarf, og niðurstaðan kemur sem JSON eða sem 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

Undir 5.000 línum kemur niðurstaðan líka til baka í results inni í JSON; yfir, er hún sótt sem CSV. Gjaldfærslan fer fram þegar verkið fer í biðröð, og óunni hlutinn kemur aftur á inneignina ef verkið stöðvast. Táknið verður að tilheyra aðgangi: verkið lendir í þinni biðröð.

Niðurstöðukóðar

Hvert svar inniheldur reitinn outcome: lista af lykilorðum, tóman þegar ekkert er að tilkynna. Mynstrið er alltaf <conditions> [MODIFIED <types>] — skilyrðin fyrst, breytingarnar aftast — og það gildir fyrir allar þjónustur. Við hliðina finnur þú outcome_label (eða kind) með ok, modified, warning, error, og reason með skýringu í einni línu. Kóðarnir eru auðkenni: þeir eru bornir saman, ekki þýddir; með "language": "it" koma ítölsku kóðarnir út (LOCALITA_NON_TROVATA MODIFICATO CAP INDIRIZZO), þeir sömu orð fyrir orð.

Heimilisfang (sannprófun tengiliða)

Ítalskt skattnúmer (codice fiscale)

Á endapunktinum /tax-code hafa sömu athuganir eigin kóða — 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 — því þar er skattnúmerið viðfang athugunarinnar, ekki reitur í færslunni.

Auðgun

Netfang

Sími

Vefsíða

Hvað hvert kall notar

Hvert kall notar vinnslur af teljara þjónustunnar: sannprófun tengiliða (/contact, /suggest við val), tvítakahreinsun (/dedupe) og léttar vinnslur (/email, /phone, /website, /enrichment, /tax-code umfram kvótann). Vinnslur eru keyptar í pökkum sem haldast, eða með mánaðaráskrift; verðið á hverjar 1.000 lækkar með stærðinni og er á síðunni verð. Í hverjum mánuði eru 50 sannprófanir tengiliða, 100 spjöld í tvítakahreinsun og 500 léttar vinnslur ókeypis.

Hvert svar segir hvað það notaði og hvaðan: reiturinn credit í JSON (counter, charged, free, subscription og packs með vinnslunum sem teknar voru og því sem eftir er, available, auto_topup með fjölda pakka sem keyptir voru sjálfkrafa, note) og hausarnir X-RA-Charged, X-RA-Available og, þegar hún grípur inn í, X-RA-Auto-Topup. Ef tiltækar vinnslur dekka ekki kallið og sjálfvirk áfylling teljarans er ekki virk (eða mistekst), er svarið 402 payment_required og ekkert er unnið.

Til að vita hve margar vinnslur eru eftir án þess að nota neina er GET /api/v1/credit. Fyrir hvern teljaranna þriggja (contact, dedupe, light) skilar hann available, ókeypis vinnslunum (free) sem eftir eru í mánuðinum og dagsetningunni sem þær núllstillast (þann 1.), subscription (eftirstöðvar, stærð, endurnýjun), virku packs einum í einu með því sem eftir er (þeir renna ekki út) og hve marga þú keyptir, auto_topup (virk, stærð, þak og eytt í þessum mánuði í evrum), notkunina (used í þessum mánuði, heildartölur, síðasta notkun) og umfram allt state, því núll eitt og sér segir ekki hvort þú kláraðir eða notar ekki þá þjónustu: never_used, free (aldrei keypt, unnið innan ókeypis vinnslna mánaðarins), free_used_up, active, awaiting_renewal, used_up (þú keyptir áður og ekkert er eftir: fylltu á), með warning. Efst telur needs_topup upp teljarana sem þarfnast aðgerða og endpoint segir hvaða teljara hver endapunktur notar. Krefst tákns af aðgangi.

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

Þú greiðir fyrir hvert sannreynt atriði, ekki fyrir hvert kall: ef reitur inniheldur tvö símanúmer eða tvö netföng, sannreynum við þau öll (allt að þrjú í línu) og hvert þeirra greiðir sitt verð. Lotukall notar jafnmikið og vinnslurnar sem það inniheldur. Ef inneignin er uppurin og sjálfvirk áfylling er ekki virk, svarar API með HTTP 402 (ófullnægjandi inneign); umfram hraðatakmörkin svarar það með HTTP 429 með retry_after. Þú kaupir pakka á aðgangssvæðinu þínu, eða virkjar áskrift til að greiða minna fyrir hverja vinnslu.