Η ίδια μηχανή,
μέσα στην εφαρμογή σας.

Ένα endpoint ανά υπηρεσία, με το ίδιο όνομα που έχει η υπηρεσία σε αυτόν τον ιστότοπο: /contact, /dedupe, /email, /phone, /website, /tax-code, /enrichment. Καθένα δέχεται ένα στοιχείο στο σώμα του αιτήματος ή μια λίστα στο items, έως 500 ανά κλήση (100 για τους ιστότοπους, που πρέπει να προσπελαστούν ένας προς έναν). Η αφαίρεση διπλοεγγραφών είναι η εξαίρεση και θέλει πάντα λίστα: συγκρίνει τις εγγραφές μεταξύ τους. Χωριστά στέκουν το /suggest, η αυτόματη συμπλήρωση για φόρμες (δουλεύει ανά συνεδρία όσο ο χρήστης πληκτρολογεί, όχι σε παρτίδες), και το /credit, που λέει πόσες επεξεργασίες απομένουν και σε τι κατάσταση είναι κάθε μετρητής, χωρίς να καταναλώνει καμία.

Πιστοποίηση ταυτότητας

Ο host του API είναι www.radaraddress.com. Τα ονόματα των πεδίων, των endpoint και των τιμών είναι αγγλικά αναγνωριστικά, ίδια σε κάθε γλώσσα· οι ετικέτες, οι αιτίες και τα μηνύματα ακολουθούν τη γλώσσα του αιτήματος ("language": "de" ή ?language=de, ή η κεφαλίδα Accept-Language, ή η γλώσσα του λογαριασμού). Η κεφαλίδα Content-Language λέει σε ποια γλώσσα ήρθε η απάντηση.

Προαιρετικό: αν καλείτε το API από μια φόρμα, μπορείτε να πείτε πού βρίσκεται με δύο κεφαλίδες, X-RadarAddress-Form-Page (η διεύθυνση της σελίδας με τη φόρμα) και X-RadarAddress-Form (ποια φόρμα και σε ποιο σημείο, για παράδειγμα checkout/billing). Έτσι κάθε επεξεργασία συνδέεται με τη φόρμα από την οποία ήρθε. Από τη σελίδα κρατάμε μόνο τον τομέα και τη διαδρομή, χωρίς το τμήμα μετά το ερωτηματικό.

Η πρόσβαση στο API γίνεται με token Bearer. Ο λογαριασμός είναι δωρεάν: δημιουργείτε το token από τον λογαριασμό σας και το συμπεριλαμβάνετε στην κεφαλίδα κάθε αιτήματος με αυτή τη μορφή:

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

Κατά τη δημιουργία μπορείτε να δώσετε στο token μια προαιρετική λήξη: μετά την ημερομηνία αυτή τα αιτήματα λαμβάνουν HTTP 401 με κωδικό token_expired· χωρίς λήξη το token ισχύει μέχρι να το ανακαλέσετε. Μπορείτε να το ανακαλέσετε ή να το αναδημιουργήσετε ανά πάσα στιγμή από τον λογαριασμό σας, όπου βλέπετε επίσης την τελευταία χρήση και τον αριθμό των αιτημάτων που εξυπηρετήθηκαν. Ένα αίτημα χωρίς token ή με μη έγκυρο token επιστρέφει HTTP 401.

Κάθε μέθοδος HTTP κάνει ό,τι λέει το όνομά της: η GET διαβάζει και δεν καταναλώνει επεξεργασίες (/credit, /countries, η εκ νέου ανάγνωση μιας εργασίας), η POST επεξεργάζεται, η DELETE διαγράφει μια εργασία. Μια μέθοδος που το endpoint δεν δέχεται λαμβάνει HTTP 405 με την κεφαλίδα Allow, που απαριθμεί τις σωστές.

Τα ιταλικά ονόματα, για όσους τα χρησιμοποιούν ήδη

Το API έχει μία μόνο έκδοση, στα αγγλικά. Όποιος ενσωμάτωσε με τα ιταλικά ονόματα δεν χρειάζεται να αλλάξει τίποτα: τα ιταλικά πεδία γίνονται δεκτά σε κάθε αίτημα, τα endpoint απαντούν και με το ιταλικό τους όνομα (/contatto, /deduplica, /codicefiscale, /arricchimento, /telefono, /sito, /suggerisci, /nazioni, /credito), και η απάντηση βγαίνει με τα ιταλικά κλειδιά και κωδικούς σε όποιον το ζητά με "language": "it".

Ο πλήρης πίνακας των πεδίων: αγγλικά → ιταλικά

αγγλικά	ιταλικά	αγγλικά	ιταλικά
account	account	metric	metrico
action	azione	min_level	livello_minimo
activated_on	attivato_il	missing	mancano
active	attiva	modified	modificati
active_packs	attivi	module_version	versione_modulo
address	indirizzo	month	mese
address_key	indirizzo_confronto	monthly_cap_eur	tetto_mese_eur
addresses	indirizzi	moved_fields	campi_spostati
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	order	ordine
changed	modificato	order_date	data_ordine
changes	modifiche	origin	origine
charged	consumate	other	altro
check	controlla	outcome	esito
check_digit	controllo	outcome_label	esito_label
city	localita	outcomes	esiti
city_key	localita_confronto	overall_cap_eur	tetto_globale_eur
city_passes	cicli_localita	packs	pacchetti
city_type	localita_tipo	parsed	letto
class	classe	phase	fase
code	codice	phone	telefono
colour	colore	phone2	telefono2
comments	commenti	phone3	telefono3
conditions	condizioni	phone_outcome	telefono_esito
confidence	confidenza	phones	telefoni
confirmed	confermato	place	luogo
consolidate	consolida	position	posizione
contact	contatto	postcode	cap
contact_person	referente	postcode_check	cap_verifica
corrected_from	corretta_da	precision	precisione
counter	contatore	preserve_original	preserva_originale
counters	contatori	presumed	presunto
countries	nazioni	privacy_consent	consenso_privacy
country	nazione	processed	lavorato
country_code	nazione_iso2	processed_at	datalav
country_original	nazione_originale	profession	qualifica
country_prefix	prefisso_paese	provenance	provenienza
created	creato	province	provincia
credit	credito	provincial_capital	capoluogo
dedupe	deduplica	purchase_url	acquisto
default_country	nazione_predefinita	reachable	raggiungibile
detail	dettaglio	reason	motivo
differences	differenze	record_outcome	esito_record
discarded	scartati	records	anagrafiche
disposable	usa_e_getta	redirects	redirect
district	quartiere	reference	riferimento
domain_checked	dominio_verificato	reference_id	riferimento_id
domain_exists	dominio_esiste	remaining	rimaste
done	fatte	renews_on	si_rinnova_il
duration_ms	durata_ms	reset_on	si_azzerano_il
e164	formato_e164	rows	righe
education	titolo_studio	salutation	saluto
email_outcome	email_esito	save	salva
enrichment	arricchimento	segment_passes	cicli_arcostradale
entries	schede	session	sessione
error	errore	shop_domain	dominio
existing_account	account_esistente	short	breve
exists	esiste	similar_to	simile_a
expiry	scadenza	singles	singoli
explanations	spiegazioni	size	taglia
extension	estensione	source	fonte
field	campo	specificity	specificita
final_url	url_finale	spent_month_eur	speso_mese_eur
first_name	nome	spent_overall_month_eur	speso_globale_mese_eur
fix_typos	correggi_refusi	state	stato
foreign	esteri	states	stati
foreign_address	estero	street	strada
formal_salutation	saluto_formale	street_id	via_id
format	formato	street_name	toponimo
found	trovato	street_passes	cicli_toponimo
free	gratuite	street_proper_name	duf
free_forever	gratis_per_sempre	street_type	dug
full_name	nominativo	sub_address	subindirizzo
gender	sesso	sub_address_confirmed	subindirizzo_confermato
gender_source	fonte_sesso	subject_type	tipo_soggetto
generic	generica	subscription	abbonamento
group	gruppo	suffix	esponente
groups	gruppi	suggestion	suggerimento
hamlet	frazione	summary	riepilogo
hints	suggerimenti	supported	supportato
homocode	omocodo	syntax	sintassi
house_number	civico	tax_code	codice_fiscale
house_number_label	civico_label	tax_code_outcome	codice_fiscale_esito
house_number_verified	civico_verificato	territory	territorio
house_numbers	civici	text	testo
informal_salutation	saluto_informale	time_ms	tempo_ms
iso2	codice_iso2	title	titolo
iso3	codice_iso3	to_check	da_controllare
istat_code	istat	total	totali
items	elementi	town	citta
job	lavoro	truncated	troncato
language	lingua	type	tipo
languages	lingue	type_normalized	tipo_norm
last_name	cognome	types	tipi
last_on	ultimo_il	typo_level	livello_refuso
last_used	ultimo_uso	unresolved	non_risolti
left	residuo	url_normalized	url_normalizzato
legacy_default	default_storico	used	usate
letter_name	nome_lettera	valid	valida
level	livello	value	valore
light	leggere	warning	avviso
long	lungo	warnings	avvisi
long_name	nome_esteso	website	sito
main_record	principale	website2	sito2
match	corrisponde	website3	sito3
matches	abbinamenti	website_outcome	sito_esito
members	membri	websites	siti
method	metodo	zoned	zonato

Και οι τιμές των επιλογών έχουν ιταλικό όνομα: format nazionale/internazionale, action genera/valida/estrai/confronta/seleziona, foreign dichiarati/rileva, min_level certo/probabile/ambiguo· με "language": "it" βγαίνουν έτσι και τα level, confidence, state, οι κωδικοί του outcome και οι επικεφαλίδες των αρχείων. Στην είσοδο γίνονται δεκτά και συνηθισμένα συνώνυμα (zip, surname, phone_number, date_of_birth…), και οι ίδιες επικεφαλίδες στα αρχεία των μαζικών εργασιών.

Endpoint επαλήθευσης διευθύνσεων

Τακτοποιεί ολόκληρη την επαφή: τη διεύθυνση στο ταχυδρομικό πρότυπο της χώρας της — στην Ιταλία και στις χώρες με το μητρώο σε λειτουργία, οδός και αριθμός επαληθεύονται στο εθνικό μητρώο διευθύνσεων· αλλού η διεύθυνση βγαίνει στην ταχυδρομική μορφή της χώρας —, το ονοματεπώνυμο και — αν το αίτημα τον περιέχει — τον ιταλικό φορολογικό κωδικό, που καθαρίζεται, συμπληρώνεται όταν λείπει μόνο ο χαρακτήρας ελέγχου και συγκρίνεται με επώνυμο, όνομα, φύλο και ημερομηνία γέννησης. Μία επαφή τη φορά, ή έως 500 στο items: το σχήμα είναι το ίδιο με κάθε άλλο endpoint.

Στην ίδια εγγραφή μπορείτε να στείλετε email, phone και website: τα ελέγχουμε στην ίδια επεξεργασία, μαζί με το ονοματεπώνυμο και το tax_code. Η απάντηση περιέχει email_outcome, phone_outcome, website_outcome και enrichment (φύλο, τίτλος, προσφώνηση). Τα αποτελέσματά τους δεν περιλαμβάνονται στο outcome, που παραμένει το αποτέλεσμα της διεύθυνσης και του φορολογικού κωδικού. Σε μια λίστα γίνεται επικοινωνία με έως 100 ιστότοπους ανά κλήση: στους υπόλοιπους ελέγχεται μόνο η μορφή.

Δύο διακόπτες, ενεργοί αν δεν τους στείλετε: το network:false δεν επικοινωνεί με τους ιστότοπους και το dns:false δεν ελέγχει αν ο τομέας των email δέχεται αλληλογραφία. Έτσι μένει μόνο ο έλεγχος της μορφής και είναι πιο γρήγορο. Ισχύουν για όλη την κλήση, και με async, και είναι οι ίδιοι με αυτούς των /website και /email.

Η χώρα δίνεται με country_code (ISO 3166-1: IT, DE, FR…) ή με country, γραμμένη όπως να 'ναι: «Germania», «Germany», «Deutschland», «Ομοσπονδιακή Δημοκρατία της Γερμανίας», «UK», «Ολλανδία». Αν λείπει, θεωρείται Ιταλία. Στις χώρες με το μητρώο σε λειτουργία — σήμερα Γαλλία, Γερμανία, Ισπανία, Κάτω Χώρες, Βέλγιο, Φινλανδία, Ελβετία, Τσεχία, Πορτογαλία, Δανία, Νορβηγία, Αυστρία, Σλοβακία, Κροατία, Ελλάδα, Ρουμανία, Ουγγαρία, Σλοβενία, Ιρλανδία, Ισλανδία, Λουξεμβούργο, Λιχτενστάιν, Άγιος Μαρίνος, Μονακό, Ανδόρα, Βατικανό, ο ενημερωμένος κατάλογος βρίσκεται στις Χώρες — οδός και αριθμός επαληθεύονται στο εθνικό μητρώο διευθύνσεων ακριβώς όπως στην Ιταλία: ταχυδρομικός κώδικας επιβεβαιωμένος ή συμπληρωμένος, συντεταγμένες του αριθμού στο geo, συνοικία ή arrondissement στο district όπου η πόλη τα έχει (Hamburg-Altstadt, Paris 4e Arrondissement), κωδικός δήμου στο territory.municipality_code. Στα ιταλικά το αποτέλεσμα φέρει FOREIGN ακολουθούμενο από τις αλλαγές, στις άλλες γλώσσες μόνο τις αλλαγές· αν η οδός υπάρχει και ο αριθμός όχι, HOUSE_NUMBER_NOT_FOUND. Στις άλλες χώρες δουλεύουμε στη μορφή, και το μήνυμα το λέει: ταχυδρομικός κώδικας στη μορφή της χώρας, συντομογραφίες της οδού ολογράφως, κεφαλαία και όνομα πόλης όπως τα γράφει το ταχυδρομείο εκείνης της χώρας (Hauptstr. 5, Munich → Hauptstraße 5, MÜNCHEN), με τη γραμμή της χώρας. Και στις δύο περιπτώσεις επιστρέφει το address_key, η μορφή με την οποία η αφαίρεση διπλοεγγραφών αναγνωρίζει την ίδια οδό γραμμένη με δύο τρόπους. Με "foreign": "detect" μια εγγραφή χωρίς χώρα που δεν βρίσκεται στην Ιταλία αναγνωρίζεται ως ξένη όταν το κείμενο το λέει ξεκάθαρα· η προεπιλογή declared αφήνει ως ξένη μόνο όποια το δηλώνει. Ο πλήρης κατάλογος των χωρών, με σύντομο και επίσημο όνομα, στα αγγλικά και στη γλώσσα της χώρας, είναι διαθέσιμος με GET /api/v1/countries και μπορεί να ερωτηθεί με ?q=Germania, ?q=Deutschland ή ?q=DE.

Για μια παρτίδα από μία μόνο χώρα δεν χρειάζεται να επαναλαμβάνετε τη χώρα σε κάθε στοιχείο: το default_country ("DE", "Germany") ισχύει για τα στοιχεία που δεν τη δηλώνουν, στην επαλήθευση διευθύνσεων, στην αφαίρεση διπλοεγγραφών, στον εμπλουτισμό (επιλέγει το λεξικό των ονομάτων) και στην επαλήθευση τηλεφώνου, και στις ασύγχρονες εργασίες. Η χώρα που είναι γραμμένη στο στοιχείο υπερισχύει πάντα· χωρίς καμία από τις δύο, το στοιχείο είναι ιταλικό.

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

Για την παρτίδα, τα ίδια πεδία μέσα στο items· η απάντηση είναι { count, results: [ { id, result } ] } με την ίδια σειρά που στάλθηκαν.

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

Το ίδιο endpoint για μια διεύθυνση σε άλλη χώρα: αρκεί το country_code. Εδώ το Αμβούργο, επαληθευμένο στο γερμανικό μητρώο, με τη συνοικία και τις συντεταγμένες του αριθμού.

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

Επιλογές που ισχύουν για ολόκληρη την κλήση: postal_form (φέρνει και το normalized στην ταχυδρομική μορφή), preserve_original (κρατά το όνομα όπως το έγραψε ο χρήστης και εκθέτει χωριστά το κανονικό), precision 1–5 (προεπιλογή 3· πάνω από 3 η αντιστοίχιση είναι προσεγγιστική και η αξιοπιστία δεν θα είναι high).

Τα επίπεδα του precision: το καθένα κάνει και ό,τι κάνουν τα προηγούμενα.

• 1 Αυστηρή: Η τοποθεσία όπως είναι γραμμένη· στην οδό μόνο οι διορθώσεις που τα δεδομένα επιβεβαιώνουν χωρίς αμφιβολία.
• 2 Στενή: Επιπλέον διορθώνει λάθος ταχυδρομικούς κώδικες και επαρχίες και αναγνωρίζει τις συντομευμένες τοποθεσίες.
• 3 Κανονική (προεπιλογή): Επιπλέον βρίσκει τα μισογραμμένα ονόματα και μεταφέρει τη διεύθυνση στον δήμο όπου πράγματι βρίσκεται η οδός.
• 4 Ευρεία: Επιπλέον δέχεται ονόματα που ακούγονται ίδια και, ανάμεσα σε οδούς με το ίδιο όνομα, επιλέγει την πιο γνωστή. Η αξιοπιστία δεν είναι ποτέ υψηλή.
• 5 Μέγιστη: Ό,τι μπορεί να βρεθεί. Η αξιοπιστία δεν είναι ποτέ υψηλή.

Μαζί με τη διεύθυνση έρχεται το city_type, που λέει αν το σημείο παράδοσης βρίσκεται σε πρωτεύουσα επαρχίας ή σε πόλη της επαρχίας — η διαφορά που μετράει για όποιον τμηματοποιεί μια καμπάνια ανά πόλη. Το provincial_capital είναι true, false ή null όταν δεν έχουμε στοιχεία για να το πούμε — και στην περίπτωση αυτή δεν μαντεύουμε.

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

Δίπλα στον ταχυδρομικό κώδικα έρχεται το postcode_check: από πού προέρχεται (source) και με ποια ακρίβεια (precision: house_number ο ίδιος ο αριθμός, interpolated οι γειτονικοί αριθμοί της ίδιας οδού, street η πλειοψηφία της οδού, locality, municipality), πόσοι αριθμοί το λένε (house_numbers) και με ποια συμφωνία (agreement, από 0 έως 1). Αν λείπει επιβεβαίωση για τον αριθμό, το αποτέλεσμα φέρει POSTCODE_UNCONFIRMED και το confirmed είναι false: ο ταχυδρομικός κώδικας μένει όπως δηλώθηκε, εφόσον ανήκει στην πόλη, και πρέπει να ελεγχθεί.

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

Επιστρέφουν επίσης οι συντεταγμένες στο geo (γεωγραφικό πλάτος και μήκος WGS84) και τα εδαφικά αναγνωριστικά στο territory: στην Ιταλία ο κωδικός ISTAT και ο κτηματολογικός κωδικός του δήμου, το CAB και το εθνικό αναγνωριστικό της οδού· στις άλλες χώρες το country και ο κωδικός του δήμου στο εθνικό μητρώο (municipality_code). Το πεδίο precision λέει σε ποιο επίπεδο φτάσαμε: house_number όταν ο αριθμός είναι γεωαναφερμένος, interpolated όταν ο ακριβής αριθμός λείπει και το σημείο εκτιμάται, street όταν έχουμε το σημείο της οδού, municipality όταν έχουμε μόνο το κέντρο του δήμου. Το source λέει από πού προέρχεται το σημείο: anncsu είναι το ιταλικό εθνικό μητρώο, inspire το εθνικό μητρώο της χώρας, osm το OpenStreetMap: στην περίπτωση αυτή τα δεδομένα είναι © OpenStreetMap contributors, άδεια ODbL, και η αναφορά προέλευσης πρέπει να αναπαράγεται αν τα δημοσιεύσετε. Όπου το μητρώο μιας χώρας απαιτεί αναφορά προέλευσης, βγαίνει στο μήνυμα. Στο CSV των μαζικών εργασιών είναι οι στήλες latitude, longitude, geo_precision, istat_code και 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" } }

Ο όροφος, η σκάλα και το διαμέρισμα που γράφονται στη διεύθυνση επιστρέφουν και ως χωριστό στοιχείο στο sub_address: μια λίστα ζευγών type και value, που διαβάζονται με τους ταχυδρομικούς κανόνες της χώρας (στη Γερμανία μετά το «//», στη Γαλλία σε δική τους γραμμή, στην Πορτογαλία «3º Esq»). Οι τύποι είναι unit (διαμέρισμα), staircase (σκάλα), floor (όροφος), block, building, building_number και block_number. Η γραμμή της διεύθυνσης μένει στη μορφή της χώρας. Ό,τι δεν αναγνωρίζουμε μένει όπως γράφτηκε και δεν μπαίνει στη λίστα: δεν το μαντεύουμε. Όταν η μονάδα που δηλώθηκε υπάρχει σε αυτόν τον αριθμό, το sub_address_confirmed είναι true· αλλιώς null, ποτέ false: το ότι δεν τη βρίσκουμε δεν σημαίνει ότι είναι λάθος.

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

Endpoint αφαίρεσης διπλοεγγραφών

Αναγνωρίζει τις εγγραφές που αναφέρονται στο ίδιο πρόσωπο στην ίδια διεύθυνση ακόμη κι όταν είναι γραμμένες διαφορετικά: υποκοριστικά και ισοδυναμίες ονομάτων (Dany ≈ Daniela), επώνυμο και όνομα αντεστραμμένα, συντομογραφίες ("V. Roma" ≈ "Via Roma"), τυπογραφικά λάθη. Η σύγκριση των διευθύνσεων περνά από τη μηχανή κανονικοποίησης: δύο γραφές της ίδιας οδού συμπίπτουν στην κανονική μορφή πριν από τη σύγκριση. Το πολύ 500 επαφές ανά κλήση (εγγραφές + αναφορά)· για μεγαλύτερες λίστες χρησιμοποιήστε τη μαζική εργασία από τον λογαριασμό σας.

Βιβλία επαφών. Μια επαφή σε ένα βιβλίο επαφών (Επαφές της Apple, Google, Outlook: το μοντέλο vCard) έχει περισσότερες διευθύνσεις, τηλέφωνα και email, καθένα με μια ετικέτα. Το endpoint τα δέχεται όπως είναι, χωρίς όριο: το addresses είναι λίστα αντικειμένων με type και τα συνηθισμένα πεδία· τα phones και emails είναι λίστες όπου κάθε στοιχείο είναι η γυμνή τιμή ("340 7491386") ή {"type": "work", "value": "02 66710423"}, και ανάμεικτα· τα συνηθισμένα επίπεδα πεδία παραμένουν έγκυρα και μετρούν ως πρώτη διεύθυνση και πρώτο στοιχείο επικοινωνίας. Δύο επαφές είναι το ίδιο πρόσωπο αν οποιοδήποτε ζεύγος των διευθύνσεών τους ταιριάζει (το γραφείο της μιας με τη μοναδική διεύθυνση της άλλης), ή αν έχουν το ίδιο ονοματεπώνυμο και κοινό τηλέφωνο ή email, σε οποιαδήποτε θέση και με οποιαδήποτε ετικέτα. Η ετικέτα δεν βαραίνει στην αντιστοίχιση: επιστρέφει όπως έφτασε, συν το type_normalized στο λεξιλόγιο vCard (home, work, cell…), ώστε η εφαρμογή να ξέρει πού να γράψει πίσω. Μία επαφή είναι μία επεξεργασία, όσες διευθύνσεις και στοιχεία επικοινωνίας κι αν έχει.

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

Η απάντηση ομαδοποιεί τις διπλοεγγραφές στο groups: κάθε ομάδα απαριθμεί τα id των members της, λέει ποια να κρατηθεί (main_record) και προτείνει την ενοποιημένη record: το καλύτερο ονοματεπώνυμο και την ένωση διευθύνσεων και στοιχείων επικοινωνίας (addresses, phones, emails), καθένα με τον τύπο του, με provenance (από ποιες επαφές προέρχεται) και χωρίς διπλά: η ίδια οδός σε δύο γραφές είναι μία διεύθυνση, ο ίδιος αριθμός με δύο ετικέτες ένας αριθμός. Οι επαφές χωρίς αντιστοιχία βρίσκονται στο singles, ως αντικείμενα {id, outcome}: με outcome INTERNAL_DUPLICATE η επαφή δεν έχει διπλοεγγραφές με άλλες αλλά έχει διπλά στοιχεία στο εσωτερικό της (διεύθυνση γραμμένη δύο φορές, επαναλαμβανόμενος αριθμός), και φέρει τη συγχωνευμένη της record. Αναγνωρίζει την ίδια οδό γραμμένη με διαφορετικούς τρόπους ("V. Leopardi 4" ≈ "Via Giacomo Leopardi 4"), τον ταχυδρομικό κώδικα που διορθώθηκε αυτόματα και επώνυμο και όνομα αντεστραμμένα.

Endpoint ιταλικού φορολογικού κωδικού

Τρεις ενέργειες στον ιταλικό φορολογικό κωδικό (codice fiscale) των φυσικών προσώπων: generate από τα προσωπικά στοιχεία, validate έναν υπάρχοντα κωδικό (μορφή, χαρακτήρας ελέγχου και omocodia), extract τις πληροφορίες που περιέχει — ημερομηνία γέννησης, ηλικία, φύλο, δήμος ή ξένη χώρα γέννησης. Επιπλέον το compare ελέγχει ότι ένας κωδικός ταιριάζει με τα δηλωμένα προσωπικά στοιχεία. Καλύπτει τους κτηματολογικούς κωδικούς κάθε ιταλικού δήμου και των ξένων χωρών. Επώνυμο και όνομα πρέπει να δίνονται με λατινικούς χαρακτήρες: για όποιον έχει όνομα σε άλλο αλφάβητο, ο κωδικός υπολογίζεται με τη μεταγραφή που αναγράφεται στο έγγραφο, η οποία δεν είναι μοναδική (Dmitrij/Dmitry)· ένα μη λατινικό όνομα επιστρέφει cognome_non_latino ή nome_non_latino, και στο compare μια διαφορά στο ονοματεπώνυμο κάποιου που γεννήθηκε στο εξωτερικό φέρει σημείωση για πιθανή διαφορετική μεταγραφή.

Οι πρώτες 500 ελαφριές επεξεργασίες τον μήνα είναι δωρεάν (μαζί με τον φορολογικό κωδικό), και η ποσόστωση είναι ενιαία για κάθε τρόπο χρήσης της υπηρεσίας: ό,τι κάνετε εδώ, στον ιστότοπο και στα μαζικά αρχεία μετράει στην ίδια ποσόστωση. Πέρα από αυτήν, οι ελαφριές επεξεργασίες πληρώνονται στην τιμή τους (βλ. τιμές).

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

Για μεγάλους όγκους: το { "action": "validate", "items": [ … ] } επεξεργάζεται έως 500 στοιχεία ανά κλήση, καθένα με το δικό του id συσχέτισης. Η εξαγωγή επισημαίνει με ambiguous_year τις περιπτώσεις όπου τα δύο ψηφία του έτους δεν ξεχωρίζουν τον αιώνα (1926 έναντι 2026).

Κάθε απάντηση φέρει outcome, reason, notes και comments στη γλώσσα του αιτήματος: GENERATED για generate, κενό για έγκυρο κωδικό στο validate, MATCH ή MISMATCH για compare (με differences: τα πεδία που διαφέρουν). Όταν ο κωδικός δεν περνά τους ελέγχους το αποτέλεσμα είναι ένας από τους κωδικούς TAX_CODE_* παρακάτω και το error δίνει τη σύντομη μορφή (check_digit, length, format, homocode, month, date, place, empty)· στο generate λέει ποιο στοιχείο λείπει ή δεν επιλύεται (last_name, first_name, gender, birth_date, birth_place, ambiguous_place με options, last_name_non_latin). Το suggestion φέρει τον σωστό κωδικό όταν ο έλεγχος μπορεί να τον ανασυνθέσει.

Endpoint εμπλουτισμού

Εμπλουτίζει ένα ονοματεπώνυμο: φύλο που συνάγεται από το όνομα, τύπος υποκειμένου (φυσικό ή νομικό πρόσωπο), κανονικοποιημένος τίτλος (Dr.ssa, Avv., …) και προσφωνήσεις έτοιμες για αλληλογραφία — "Egregio Sig. Rossi", "Gentile Dr.ssa Bianchi", "Spett.le" για τις εταιρείες, "Gentile Famiglia" για τα νοικοκυριά, "Caro/Cara" για το ανεπίσημο ύφος. Αναγνωρίζει επίσης τη μορφή του επωνύμου συζύγου ("Rossi in Verdi" → γυναίκα, με τη λεπτομέρεια των δύο επωνύμων). Το πεδίο gender δέχεται και γραπτές μορφές («maschio», «donna», «Sig.ra», «male»)· το X δηλώνει φορέα και το G οικογένεια ή ζευγάρι. Αν ο τίτλος λείπει, τον συνάγουμε από το profession (το επάγγελμα) ή από το education, όταν δίνεται. Τα λεξικά είναι ιταλικά.

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": "Dr.ssa",
    "formal_salutation": "Gentile Dr.ssa Rossi", "informal_salutation": "Cara Maria", … }

Σε παρτίδες: { "items": [ … ] }, έως 500 ανά κλήση. Το αποτέλεσμα είναι ENRICHED (φύλο και προσφωνήσεις ορισμένα), LEGAL_PERSON (εταιρεία ή φορέας: αντιμετωπίζεται ως επωνυμία) ή PARTIAL (λείπει το όνομα ή το φύλο δεν συνάγεται): το reason λέει γιατί, τα comments τι να προστεθεί.

Endpoint επαλήθευσης email

Επαληθεύει μια διεύθυνση email: σύνταξη, ύπαρξη του τομέα (εγγραφές MX/A), τυπογραφικά λάθη σε συνηθισμένους τομείς με προτεινόμενη διόρθωση (gmial.com → gmail.com), προσωρινοί τομείς, γενικές διευθύνσεις ρόλου (info@, accounts@: όχι ενός προσώπου). Δεν κάνουμε επαλήθευση SMTP της μεμονωμένης θυρίδας, πρακτική παρεμβατική και αναξιόπιστη. Παρτίδα items έως 500· το "dns": false παραλείπει την αναζήτηση του τομέα.

Ένα βέβαιο τυπογραφικό λάθος διορθώνεται αυτεπάγγελτα: όταν η διεύθυνση όπως είναι γραμμένη δεν είναι καν διεύθυνση (name@domain,com με το κόμμα) ή όταν η διόρθωση καταλήγει σε γνωστό πάροχο (gmai.com → gmail.com, ακόμη και με ένα γράμμα διαφορά όταν ο τομέας όπως γράφτηκε δεν λαμβάνει αλληλογραφία), το email βγαίνει διορθωμένο, το corrected_from φέρει ό,τι είχε γραφτεί και το αποτέλεσμα είναι MODIFIED EMAIL_DOMAIN. Ένα πιθανό τυπογραφικό λάθος σε οποιονδήποτε άλλο τομέα (rossi.con) παραμένει πρόταση: EMAIL_TYPO με τη διόρθωση στο suggestion, και οι έλεγχοι (domain_exists, domain_checked) γίνονται σε αυτήν· η διεύθυνση όπως είναι γραμμένη δεν επαληθεύεται.

Ένα domain που απέχει ένα πάτημα πλήκτρου από γνωστό πάροχο διορθώνεται ανάλογα με το precision (1-5, προεπιλογή 3· τα 4 και 5 μετρούν ως 3). Στο 1 μόνο αν το domain όπως γράφτηκε δεν υπάρχει (gmail.cob, hotmial.ocm)· στο 2 και αν υπάρχει αλλά δεν δέχεται αλληλογραφία (libreo.it)· στο 3 και αν δέχεται email: σταθμευμένα domain, πραγματικοί οργανισμοί (libera.it, lice.it) και γραφές «με το αυτί» (gemail.com, jmail.com). Λάθος κατάληξη σε οποιοδήποτε domain (studiorossi.con) διορθώνεται αν το σωστό domain δέχεται email. Κάτω από το επίπεδο του λάθους, που επιστρέφεται στο typo_level, η διεύθυνση μένει όπως γράφτηκε και το similar_to φέρει τη διεύθυνση που ίσως εννοούνταν, με μια σημείωση. Με "fix_typos": false, για όλη την κλήση ή για ένα μόνο στοιχείο, δεν διορθώνεται κανένα λάθος: η διεύθυνση μένει όπως γράφτηκε και η διόρθωση βγαίνει στο similar_to. Χρησιμεύει όταν το πρόσωπο έχει επιβεβαιώσει ότι θέλει ακριβώς αυτή τη διεύθυνση.

Endpoint επαλήθευσης τηλεφώνου

Ελέγχει έναν αριθμό χωρίς να καλέσει κανέναν: μορφή, κατηγορία και τύπος, μήκος σύμφωνα με το σχέδιο αριθμοδότησης, περιοχή του σταθερού και πάροχος στον οποίο αποδόθηκε αρχικά το μπλοκ. Η class είναι η ανάγνωση που χρειάζεστε για να δουλέψετε μια λίστα: mobile (μπορείτε να στείλετε SMS), landline (το καλείτε σε ώρες γραφείου), special (δεν είναι αριθμός προσώπου: έκτακτης ανάγκης, κοινής ωφέλειας, χωρίς χρέωση και με ειδική χρέωση), foreign για τους αριθμούς με διεθνές πρόθεμα. Όταν αναγνωρίζουμε και την ακριβή υπηρεσία, το type το λέει (χωρίς χρέωση, ειδική χρέωση, μερισμένο κόστος, κοινής ωφέλειας). Το ιταλικό πρόθεμα γραμμένο χωρίς το + (39347…, κλασικό λάθος των εξαγωγών) αφαιρείται όταν τα ψηφία δεν αφήνουν αμφιβολία — το 3934567890 παραμένει το κινητό που είναι. Αν το ίδιο πεδίο περιέχει περισσότερους αριθμούς («347… - 338…») τους χωρίζουμε: επιστρέφουν ως phone, phone2, phone3, και το phone δεν είναι ποτέ κενό όταν υπάρχει τουλάχιστον ένας αριθμός. Με "format": "international" ο ιταλικός αριθμός βγαίνει στη μορφή +39…· η προεπιλογή national τον αφήνει γυμνό και βάζει το πρόθεμα μόνο στους ξένους. Για τους ξένους αριθμούς επιστρέφει και το e164, η χώρα του προθέματος στο country_code, και το μηδέν του εθνικού δικτύου μετά το πρόθεμα αφαιρείται («+44 (0)20…» και «+44 20…» δίνουν τον ίδιο αριθμό). Με country_code (ή country) στην κλήση ή στο στοιχείο, ένας αριθμός γραμμένος χωρίς πρόθεμα διαβάζεται ως εθνικός αριθμός εκείνης της χώρας: το «020 7946 0958» σε μια εγγραφή του Ηνωμένου Βασιλείου είναι Λονδίνο, όχι Μιλάνο. Χωρίς χώρα παραμένει ιταλικός. Παρτίδα items έως 500.

Ένας αριθμός από την ίδια τη χώρα της εγγραφής δεν είναι «ξένος»: όπου γνωρίζουμε το σχέδιο αριθμοδότησης παίρνει την class του (mobile, landline, special), με format national μένει χωρίς κωδικό χώρας στη μορφή της χώρας του (μαζί με το μηδέν του εθνικού δικτύου), και επιστρέφει το national_number δίπλα στο e164. Τα PHONE_FOREIGN και class foreign παραμένουν για τους αριθμούς χώρας διαφορετικής από αυτή της εγγραφής.

curl -X POST https://www.radaraddress.com/api/v1/phone \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"phone":"3790328959 - 011 0000000"}'

Endpoint επαλήθευσης ιστότοπου

Ελέγχει ότι η διεύθυνση είναι σωστά γραμμένη και ότι ο ιστότοπος πράγματι αποκρίνεται: ύπαρξη του τομέα, αίτημα HTTP με παρακολούθηση των ανακατευθύνσεων, τελικός κωδικός, εγκυρότητα του πιστοποιητικού. Καμία κρίση για το περιεχόμενο. Και εδώ περισσότερες διευθύνσεις στο ίδιο πεδίο επιστρέφουν ως website, website2, website3. Με "network": false ελέγχουμε μόνο τη μορφή, χωρίς να προσπελάσουμε τον ιστότοπο. Παρτίδα items έως 100: κάθε έλεγχος ανοίγει μια σύνδεση, οπότε η παρτίδα είναι μικρότερη από τα άλλα endpoint.

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 αυτόματης συμπλήρωσης διεύθυνσης

Ξεκινάτε από το μηδέν; Το widget ra-suggerisci.js και ένας μικρός proxy στον διακομιστή σας αρκούν: το token δεν πηγαίνει ποτέ στον browser.

Προτάσεις όσο ο χρήστης πληκτρολογεί μια διεύθυνση στη φόρμα σας: ολόκληρο το ιταλικό μητρώο οδών, με το όνομα συμπληρωμένο («via verdi» → «Via Giuseppe Verdi»), δήμο και επαρχία· ο ταχυδρομικός κώδικας έρχεται με την επιλογή, στις μεγάλες πόλεις με ζώνες ο σωστός του αριθμού. Λειτουργεί ανά συνεδρία: ο client δημιουργεί ένα UUID για κάθε διεύθυνση που συμπληρώνεται, τα ερωτήματα προτάσεων είναι δωρεάν, και πληρώνετε μία επαλήθευση διεύθυνσης όταν ο χρήστης επιλέγει και τα πεδία συμπληρώνονται (ενέργεια select, που επιστρέφει την εγγραφή ήδη κανονικοποιημένη από τη μηχανή). Τα πεδία που έχουν ήδη συμπληρωθεί στη φόρμα — έστω και εν μέρει — ταξιδεύουν ως πλαίσιο και περιορίζουν τις προτάσεις.

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

Αφού επιλεγεί η οδός, συμπληρώνεται ο αριθμός: περνώντας το street_id με τον μερικό αριθμό παίρνετε τους υπάρχοντες αριθμούς εκείνης της οδού, με exists true/false για να επικυρωθεί αυτός που πληκτρολογήθηκε — και η επιλογή μπορεί να επαναληφθεί με τον αριθμό χωρίς νέα χρέωση: η χρέωση είναι ανά συνεδρία και ανά οδό, όχι ανά κλικ· άλλη οδός στην ίδια συνεδρία είναι άλλη χρέωση. Οι αριθμοί συμπληρώνονται μόνο στη συνεδρία που επέλεξε εκείνη την οδό. Στις πόλεις με ζώνες ο αριθμός είναι αυτός που καθορίζει τον ακριβή ταχυδρομικό κώδικα.

Το token του API δεν πηγαίνει ποτέ στον browser: το έτοιμο widget (ra-suggerisci.js) καλεί έναν μικρό proxy στον διακομιστή σας, που προσθέτει το token και προωθεί. Κάθε συνεδρία επιτρέπει έως 30 κλήσεις και διαρκεί 10 λεπτά· οι συνεδρίες χωρίς επιλογή είναι δωρεάν έως 200 την ημέρα ανά token, συν πέντε για κάθε επιλογή. Widget, έτοιμο proxy και δείγμα form βρίσκονται στο κιτ του Το δικό σας form.

Λειτουργεί σε κάθε χώρα σε λειτουργία (σήμερα Γαλλία, Γερμανία, Ισπανία, Κάτω Χώρες, Βέλγιο, Φινλανδία, Ελβετία, Τσεχία, Πορτογαλία, Δανία, Νορβηγία, Αυστρία, Σλοβακία, Κροατία, Ελλάδα, Ρουμανία, Ουγγαρία, Σλοβενία, Ιρλανδία, Ισλανδία, Λουξεμβούργο, Λιχτενστάιν, Άγιος Μαρίνος, Μονακό, Ανδόρα, Βατικανό· η ενημερωμένη λίστα βρίσκεται στις Χώρες): με country_code ή country οι προτάσεις προέρχονται από το μητρώο εκείνης της χώρας, και το κείμενο γράφεται όπως το γράφουν εκεί — οδός, αριθμός, ταχυδρομικός κώδικας και πόλη ακόμη και σε ένα μόνο πεδίο: «kalverstraat 92 amst», «92 rue de rivoli paris», στην Ολλανδία «1012PH 92». Κάθε απάντηση φέρει το parsed, δηλαδή πώς ο διακομιστής διάβασε την οδό (street), τον αριθμό (house_number) και τον ταχυδρομικό κώδικα (postcode): η φόρμα σας ξέρει πού βρίσκεται ο αριθμός χωρίς να γνωρίζει τους κανόνες της χώρας. Οι προτάσεις φέρουν οδό, πόλη, τοποθεσία όπου υπάρχει, και source (registry, ή osm όπου το εθνικό μητρώο δεν δημοσιεύει)· ο ταχυδρομικός κώδικας και οι αριθμοί δεν βρίσκονται ποτέ στις προτάσεις: έρχονται με την επιλογή, που περνά από τη μηχανή και επιστρέφει την ίδια εγγραφή με το /contact (postcode επιβεβαιωμένος από το μητρώο, geo στον αριθμό). Με την επιλογή μπορείτε να περάσετε και το postcode, αυτό που γράφτηκε στη φόρμα. Το attribution είναι η αναφορά πηγής που πρέπει να εμφανίζεται δίπλα στις προτάσεις: η άδεια του μητρώου το απαιτεί. Αν λείπει η χώρα θεωρείται IT· για χώρα εκτός λειτουργίας η απάντηση παραμένει HTTP 200 με supported:false και hints:[], χωρίς δημιουργία συνεδρίας και χωρίς χρέωση. Μια συνεδρία ανήκει σε μία χώρα: αν αλλάξει, ο πελάτης δημιουργεί νέο UUID (αλλιώς 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"}

Μεγάλοι όγκοι: η ασύγχρονη εργασία

Οι κανονικές κλήσεις αποκρίνονται αμέσως, και γι' αυτό έχουν ένα όριο στοιχείων — ένα αίτημα HTTP που διαρκεί λεπτά δεν χρησιμεύει σε κανέναν. Τα όρια ακολουθούν το πόσο βαριά είναι η επεξεργασία:

Πέρα από αυτούς τους αριθμούς δεν χρειάζεται να σπάσετε τη λίστα με το χέρι: προσθέτετε "async": true και η κλήση επιστρέφει αμέσως με έναν κωδικό, ενώ η επεξεργασία μπαίνει στην ίδια ουρά με τα ανεβασμένα αρχεία. Έως 100.000 στοιχεία ανά κλήση, και στις Εργασίες μου εμφανίζεται μία μόνο.

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

HTTP/1.1 202 Accepted
Location: /api/v1/contact?job=369e46e9e7bb…

{"ok":true,"job":"369e46e9e7bb…","state":"queued","rows":100000,"check":"/api/v1/contact?job=369e46e9e7bb…"}

Έπειτα το διαβάζετε όταν χρειαστεί, και το αποτέλεσμα έρχεται σε JSON ή ως 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

curl 'https://www.radaraddress.com/api/v1/contact?job=369e46e9e7bb…&format=zip' \
  -H 'Authorization: Bearer YOUR_TOKEN' -o result.zip

Με format=zip κατεβάζετε αντί γι’ αυτό όλα τα αρχεία της εργασίας σε ένα zip: το καθαρό αρχείο, με τις στήλες σας και τις διορθώσεις ήδη γραμμένες όπου είναι επιβεβαιωμένες· τις γραμμές προς έλεγχο· τι αλλάζει, κελί προς κελί· το πλήρες αποτέλεσμα· ένα README που τα εξηγεί. Με format=zip_xlsx τα ίδια αρχεία είναι σε Excel.

Κάτω από τις 5.000 γραμμές το αποτέλεσμα επιστρέφει και στο results μέσα στο JSON· από εκεί και πάνω, κατεβαίνει ως CSV. Η χρέωση γίνεται όταν η εργασία μπαίνει στην ουρά, και το μέρος που δεν επεξεργάστηκε επιστρέφει στο υπόλοιπό σας αν η εργασία σταματήσει. Το token πρέπει να ανήκει σε λογαριασμό: η εργασία καταλήγει στη δική σας ουρά.

Η κλήση που βάζει την εργασία στην ουρά απαντά με HTTP 202 και την κεφαλίδα Location, που δείχνει την εργασία. Όταν δεν χρειάζεστε πια το αποτέλεσμα, το διαγράφετε με DELETE στην ίδια διεύθυνση: η απάντηση είναι HTTP 204, και τα αρχεία και τα δεδομένα δεν υπάρχουν πια. Μια εργασία που είναι ακόμη στην ουρά ή σε επεξεργασία απαντά με 409 job_running: διαγράψτε την όταν ολοκληρωθεί. Αν δεν τη διαγράψετε, η εργασία διαγράφεται αυτόματα μετά από 30 ημέρες. Το ίδιο ισχύει και για το αποθηκευμένο αποτέλεσμα του /dedupe.

curl -X DELETE 'https://www.radaraddress.com/api/v1/contact?job=369e46e9e7bb…' \
  -H 'Authorization: Bearer YOUR_TOKEN'

HTTP/1.1 204 No Content

Κωδικοί αποτελέσματος

Κάθε απάντηση περιλαμβάνει το πεδίο outcome: μια λίστα λέξεων-κλειδιών, κενή όταν δεν υπάρχει τίποτα να αναφερθεί. Το σχήμα είναι πάντα <conditions> [MODIFIED <types>] — οι συνθήκες μπροστά, οι αλλαγές στο τέλος — και ισχύει για όλες τις υπηρεσίες. Δίπλα βρίσκετε το outcome_label (ή kind) με ok, modified, warning, error, και το reason με την εξήγηση σε μία γραμμή. Οι κωδικοί είναι αναγνωριστικά: συγκρίνονται, δεν μεταφράζονται· με "language": "it" βγαίνουν οι ιταλικοί κωδικοί (LOCALITA_NON_TROVATA MODIFICATO CAP INDIRIZZO), οι ίδιοι λέξη προς λέξη.

Διεύθυνση (επαλήθευση διευθύνσεων)

Ιταλικός φορολογικός κωδικός (codice fiscale)

Στο endpoint /tax-code οι ίδιοι έλεγχοι έχουν δικούς τους κωδικούς — 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 — επειδή εκεί ο φορολογικός κωδικός είναι το αντικείμενο του ελέγχου, όχι ένα πεδίο της εγγραφής.

Εμπλουτισμός

Email

Τηλέφωνο

Ιστότοπος

Τι καταναλώνει κάθε κλήση

Κάθε κλήση καταναλώνει επεξεργασίες από τον μετρητή της υπηρεσίας: επαλήθευση διευθύνσεων (/contact, /suggest κατά την επιλογή), αφαίρεση διπλοεγγραφών (/dedupe) και ελαφριές επεξεργασίες (/email, /phone, /website, /enrichment, /tax-code πέρα από την ποσόστωση). Οι επεξεργασίες αγοράζονται σε πακέτα που μένουν, ή με μηνιαία συνδρομή· η τιμή ανά 1.000 πέφτει με το μέγεθος και βρίσκεται στη σελίδα τιμών. Κάθε μήνα είναι δωρεάν 50 επαληθεύσεις διευθύνσεων, 100 εγγραφές σε αφαίρεση διπλοεγγραφών και 500 ελαφριές επεξεργασίες.

Κάθε απάντηση λέει τι κατανάλωσε και από πού: το πεδίο credit του JSON (counter, charged, free, subscription και packs με τις επεξεργασίες που αφαιρέθηκαν και το υπόλοιπο, available, auto_topup με τον αριθμό των πακέτων που αγοράστηκαν αυτόματα, note) και οι κεφαλίδες X-RA-Charged, X-RA-Available και, όταν παρεμβαίνει, X-RA-Auto-Topup. Αν οι διαθέσιμες επεξεργασίες δεν καλύπτουν την κλήση και η αυτόματη επαναφόρτιση του μετρητή δεν είναι ενεργή (ή αποτύχει), η απάντηση είναι 402 payment_required και δεν επεξεργάζεται τίποτα.

Το σώμα της απάντησης 402 περιέχει επίσης το credit.purchase_url: τη σελίδα Μονάδες του λογαριασμού σας, με το μικρότερο πακέτο που καλύπτει ό,τι λείπει, έτοιμη να ανοίξει.

Για να μάθετε πόσες επεξεργασίες απομένουν χωρίς να καταναλώσετε καμία υπάρχει το GET /api/v1/credit. Για καθέναν από τους τρεις μετρητές (contact, dedupe, light) επιστρέφει το available, τις δωρεάν (free) που απομένουν στον μήνα και την ημερομηνία που μηδενίζονται (η 1η), τη subscription (υπόλοιπο, μέγεθος, ανανέωση), τα ενεργά packs ένα προς ένα με ό,τι απομένει (δεν λήγουν) και πόσα αγοράσατε, το auto_topup (ενεργό, μέγεθος, όριο και δαπάνη του μήνα σε ευρώ), τη χρήση (used αυτόν τον μήνα, σύνολα, τελευταία χρήση) και προπάντων το state, γιατί ένα μηδέν από μόνο του δεν λέει αν εξαντλήσατε ή αν δεν χρησιμοποιείτε την υπηρεσία: never_used, free (ποτέ δεν αγοράσατε, εργάζεστε με τις δωρεάν του μήνα), free_used_up, active, awaiting_renewal, used_up (αγοράσατε στο παρελθόν και δεν απομένει τίποτα: χρειάζεται νέο πακέτο), με ένα warning. Στην κορυφή το needs_topup απαριθμεί τους μετρητές που χρειάζονται ενέργεια και το endpoint λέει ποιον μετρητή καταναλώνει κάθε endpoint. Απαιτεί token λογαριασμού.

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

Πληρώνετε ανά επαληθευμένο στοιχείο, όχι ανά κλήση: αν ένα πεδίο περιέχει δύο αριθμούς τηλεφώνου ή δύο email, τα επαληθεύουμε όλα (έως τρία ανά γραμμή) και καθένα καταναλώνει μία επεξεργασία. Μια κλήση παρτίδας καταναλώνει όσο οι επεξεργασίες που περιέχει. Αν οι επεξεργασίες έχουν εξαντληθεί και η αυτόματη επαναφόρτιση δεν είναι ενεργή, το API απαντά HTTP 402 (ανεπαρκείς επεξεργασίες)· μετά την υπέρβαση του ορίου ρυθμού απαντά HTTP 429 με retry_after. Αγοράζετε ένα πακέτο από τον λογαριασμό σας, ή ενεργοποιείτε μια συνδρομή για να πληρώνετε λιγότερο ανά επεξεργασία.