Le même moteur,
dans votre application.

Un endpoint par service, avec le même nom que le service porte sur ce site : /contact, /dedupe, /email, /phone, /website, /tax-code, /enrichment. Chacun accepte un élément dans le corps de la requête ou une liste dans items, jusqu'à 500 par appel (100 pour les sites web, qu'il faut contacter un par un). Le dédoublonnage fait exception et veut toujours une liste : il compare les fiches entre elles. À part se tiennent /suggest, l'autocomplétion pour les formulaires (elle travaille par session pendant que l'utilisateur tape, pas par lots), et /credit, qui dit combien d'opérations il reste et dans quel état est chaque compteur, sans en consommer.

Authentification

L'hôte de l'API est www.radaraddress.com. Les noms des champs, des points de terminaison et des valeurs sont des identifiants anglais, identiques dans toutes les langues ; les libellés, les motifs et les messages suivent la langue de la requête ("language": "de" ou ?language=de, ou l'en-tête Accept-Language, ou la langue du compte). L'en-tête Content-Language indique dans quelle langue la réponse est arrivée.

Facultatif : si vous appelez l'API depuis un formulaire, vous pouvez indiquer où il se trouve avec deux en-têtes, X-RadarAddress-Form-Page (l'adresse de la page du formulaire) et X-RadarAddress-Form (quel formulaire et à quel endroit, par exemple checkout/billing). Chaque opération se retrouve ainsi avec le formulaire d'où elle vient. De la page, nous ne gardons que le domaine et le chemin, sans la partie après le point d'interrogation.

L'accès à l'API se fait par token Bearer. Le compte est gratuit : vous créez le token depuis l'espace personnel et vous l'incluez dans l'en-tête de chaque requête sous la forme :

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

À la création, vous pouvez donner au token une date d'expiration facultative : passée cette date, les requêtes reçoivent HTTP 401 avec le code token_expired ; sans expiration, le token vaut tant que vous ne le révoquez pas. Vous pouvez le révoquer ou le régénérer à tout moment depuis votre espace personnel, où vous voyez aussi la dernière utilisation et le nombre de requêtes servies. Une requête sans token ou avec un token non valide renvoie HTTP 401.

Chaque méthode HTTP fait ce que dit son nom : GET lit et ne consomme aucune opération (/credit, /countries, la relecture d'un traitement), POST traite, DELETE supprime un traitement. Une méthode que l'endpoint n'accepte pas reçoit HTTP 405 avec l'en-tête Allow, qui liste les bonnes.

Les noms italiens, pour ceux qui les utilisent déjà

L'API n'a qu'une version, en anglais. Qui avait intégré avec les noms italiens n'a rien à changer : les champs italiens sont acceptés dans chaque requête, les points de terminaison répondent aussi sous leur nom italien (/contatto, /deduplica, /codicefiscale, /arricchimento, /telefono, /sito, /suggerisci, /nazioni, /credito), et la réponse ressort avec les clés et les codes italiens pour qui le demande avec "language": "it".

Le tableau complet des champs : anglais → italien

anglais	italien	anglais	italien
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

Les valeurs des options ont aussi un nom italien : format nazionale/internazionale, action genera/valida/estrai/confronta/seleziona, foreign dichiarati/rileva, min_level certo/probabile/ambiguo ; avec "language": "it" ressortent ainsi aussi level, confidence, state, les codes de outcome et les en-têtes des fichiers. En entrée, les synonymes courants sont aussi acceptés (zip, surname, phone_number, date_of_birth…), ainsi que les mêmes en-têtes dans les fichiers des traitements par lots.

Endpoint vérification d'adresse

Met en ordre le contact entier : l'adresse selon le standard postal de son pays — en Italie et dans les pays dont le référentiel est en service, la voie et le numéro sont vérifiés dans le référentiel national des adresses ; ailleurs l'adresse sort dans la forme postale du pays —, le nom et — si la requête le porte — le code fiscal italien, nettoyé, complété s'il ne manque que le caractère de contrôle et confronté au nom, au prénom, au sexe et à la date de naissance. Un contact à la fois, ou jusqu'à 500 dans items : le schéma est le même pour tous les autres endpoints.

Dans la même fiche, vous pouvez passer email, phone et website : nous les contrôlons dans la même opération, avec le nom et le tax_code. La réponse contient email_outcome, phone_outcome, website_outcome et enrichment (sexe, titre, formule d'appel). Leurs résultats n'entrent pas dans outcome, qui reste celui de l'adresse et du codice fiscale. Dans une liste, les sites sont contactés jusqu'à 100 par appel : au-delà, seule la forme est contrôlée.

Deux interrupteurs, activés si vous ne les envoyez pas : network:false ne contacte pas les sites et dns:false ne vérifie pas si le domaine des e-mails reçoit du courrier. Il ne reste alors que le contrôle de la forme, et c'est plus rapide. Ils valent pour tout l'appel, y compris avec async, et ce sont les mêmes que sur /website et /email.

Le pays s'indique avec country_code (ISO 3166-1 : IT, DE, FR…) ou avec country, écrit comme il vient : « Germania », « Germany », « Deutschland », « République fédérale d'Allemagne », « UK », « Hollande ». S'il manque, l'Italie est présumée. Dans les pays dont le référentiel est en service — aujourd'hui France, Allemagne, Espagne, Pays-Bas, Belgique, Finlande, Suisse, Tchéquie, Portugal, Danemark, Norvège, Autriche, Slovaquie, Croatie, Grèce, Roumanie, Hongrie, Slovénie, Irlande, Islande, Luxembourg, Liechtenstein, Saint-Marin, Monaco, Andorre, Cité du Vatican, la liste à jour est dans Pays — la voie et le numéro sont vérifiés dans le référentiel national des adresses comme en Italie : code postal confirmé ou complété, coordonnées du numéro dans geo, quartier ou arrondissement dans district là où la ville en a (Hamburg-Altstadt, Paris 4e Arrondissement), code de la commune dans territory.municipality_code. En italien le résultat porte FOREIGN suivi des modifications, dans les autres langues seulement les modifications ; si la voie existe et pas le numéro, HOUSE_NUMBER_NOT_FOUND. Dans les autres pays nous travaillons sur la forme, et le message le dit : code postal au format du pays, abréviations de la voie développées, majuscules et nom de la ville tels que la poste de ce pays les écrit (Hauptstr. 5, Munich → Hauptstraße 5, MÜNCHEN), avec la ligne du pays. Dans les deux cas revient address_key, la forme avec laquelle la déduplication reconnaît la même voie écrite de deux façons. Avec "foreign": "detect", un enregistrement sans pays introuvable en Italie est reconnu comme étranger quand le texte le dit clairement ; la valeur par défaut declared ne laisse étranger que ce qui le déclare. Le catalogue complet des pays, avec nom court et officiel, en anglais et dans la langue du pays, est disponible avec GET /api/v1/countries et s'interroge avec ?q=Germania, ?q=Deutschland ou ?q=DE.

Pour un lot d'un seul pays, vous n'avez pas besoin de répéter le pays dans chaque élément : default_country ("DE", "Germany") s'applique aux éléments qui ne l'indiquent pas, dans la vérification d'adresse, le dédoublonnage, l'enrichissement (il choisit le dictionnaire des prénoms) et la vérification de téléphone, tâches asynchrones comprises. Le pays écrit dans l'élément l'emporte toujours ; sans l'un ni l'autre, l'élément est italien.

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

Pour le lot, les mêmes champs dans items ; la réponse est { count, results: [ { id, result } ] } dans le même ordre que l'envoi.

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

Le même endpoint pour une adresse d'un autre pays : country_code suffit. Ici Hambourg, vérifiée dans le référentiel allemand, avec le quartier et les coordonnées du numéro.

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

Options valables pour l'appel entier : postal_form (force aussi normalized dans la forme postale), preserve_original (garde le nom tel que l'utilisateur l'a écrit et expose le canonique à part), precision 1–5 (3 par défaut ; au-delà de 3, la correspondance est approximative et la fiabilité ne sera pas high).

Les niveaux de precision : chacun fait aussi ce que font les précédents.

• 1 Stricte: La localité telle qu'elle est écrite ; dans la voie, seulement les corrections que les données confirment sans aucun doute.
• 2 Étroite: Corrige en plus les codes postaux et provinces erronés et reconnaît les localités abrégées.
• 3 Normale (par défaut): Retrouve en plus les noms écrits à moitié et place l'adresse dans la commune où la voie existe vraiment.
• 4 Large: Accepte en plus les noms qui se prononcent de la même façon et, parmi des voies homonymes, choisit la plus connue. La fiabilité n'est jamais élevée.
• 5 Maximale: Tout ce qui peut être retrouvé. La fiabilité n'est jamais élevée.

Avec l'adresse revient city_type, qui dit si le point de distribution est dans un chef-lieu de province ou dans une commune de la province — la différence qui compte pour qui segmente une campagne par ville. provincial_capital vaut true, false ou null quand nous n'avons pas d'éléments pour le dire — et dans ce cas nous ne devinons pas.

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

À côté du code postal vient postcode_check : d'où il vient (source) et avec quelle précision (precision : house_number le numéro lui-même, interpolated les numéros voisins de la même rue, street la majorité de la rue, locality, municipality), combien de numéros le disent (house_numbers) et avec quel accord (agreement, de 0 à 1). Sans confirmation pour ce numéro, le résultat porte POSTCODE_UNCONFIRMED et confirmed vaut false : le code postal reste celui indiqué, s'il fait partie de ceux de la ville, et doit être vérifié.

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

Reviennent aussi les coordonnées dans geo (latitude et longitude WGS84) et les identifiants territoriaux dans territory : en Italie le code ISTAT et le code cadastral de la commune, le CAB et l'identifiant national de la voie ; dans les autres pays country et le code de la commune dans le référentiel national (municipality_code). Le champ precision dit à quel niveau nous sommes arrivés : house_number quand le numéro est géoréférencé, interpolated quand le numéro exact manque et que le point est estimé, street quand nous avons le point de la voie, municipality quand nous n'avons que le centre de la commune. source dit d'où vient le point : anncsu est le référentiel national italien, inspire le référentiel national du pays, osm OpenStreetMap : dans ce cas les données sont © OpenStreetMap contributors, licence ODbL, et l'attribution doit être reproduite si vous les publiez. Là où le référentiel d'un pays impose une attribution, elle sort dans le message. Dans le CSV des travaux en bloc ce sont les colonnes latitude, longitude, geo_precision, istat_code et 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" } }

L'étage, l'escalier et l'appartement écrits dans l'adresse reviennent aussi comme données à part dans sub_address : une liste de paires type et value, lues selon les règles postales du pays (en Allemagne après « // », en France sur une ligne à part, au Portugal « 3º Esq »). Les types sont unit (appartement), staircase (escalier), floor (étage), block, building, building_number et block_number. La ligne d'adresse reste dans la forme du pays. Ce que nous ne reconnaissons pas reste tel qu'il était écrit et n'entre pas dans la liste : nous ne le devinons pas. Quand l'unité indiquée figure à ce numéro, sub_address_confirmed vaut true ; sinon null, jamais false : ne pas la trouver ne veut pas dire qu'elle est fausse.

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

Endpoint dédoublonnage

Reconnaît les fiches qui désignent la même personne à la même adresse même quand elles sont écrites différemment : diminutifs et équivalences de prénoms (Dany ≈ Daniela), nom et prénom inversés, abréviations ("V. Roma" ≈ "Via Roma"), fautes de frappe. La comparaison des adresses passe par le moteur de normalisation : deux graphies différentes de la même voie se rabattent sur la forme canonique avant la comparaison. Au maximum 500 contacts par appel (fiches + référence) ; pour des listes plus grandes, utilisez le traitement par lots depuis l'espace personnel.

Carnets d'adresses. Un contact d'un carnet d'adresses (Contacts d'Apple, Google, Outlook : le modèle vCard) a plusieurs adresses, plusieurs téléphones et plusieurs e-mails, chacun avec une étiquette. L'endpoint les accepte tels quels, sans plafond : addresses est une liste d'objets avec type et les champs habituels ; phones et emails sont des listes dont chaque élément est la donnée seule ("340 7491386") ou {"type": "work", "value": "02 66710423"}, même mélangés ; les champs plats habituels restent valables et valent comme première adresse et première coordonnée. Deux contacts sont la même personne si n'importe quelle paire de leurs adresses coïncide (le bureau de l'un avec l'unique adresse de l'autre), ou s'ils ont le même nom et un téléphone ou un e-mail en commun, à n'importe quelle position et sous n'importe quelle étiquette. Le type ne pèse pas sur le rapprochement : il revient tel qu'il est arrivé, plus type_normalized dans le vocabulaire vCard (home, work, cell…), pour que l'application sache où réécrire. Un contact est une opération, quel que soit le nombre d'adresses et de coordonnées.

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

La réponse regroupe les doublons dans groups : chaque groupe énumère les id de ses members, indique laquelle garder (main_record) et propose le record consolidé : le meilleur nom et l'union des adresses et des coordonnées (addresses, phones, emails), chacune avec son type, avec provenance (de quels contacts elle vient) et dédoublonnée : la même voie en deux graphies est une seule adresse, le même numéro sous deux étiquettes un seul numéro. Les contacts sans correspondance sont dans singles, sous forme d'objets {id, outcome} : avec outcome INTERNAL_DUPLICATE, le contact n'a pas de doublon avec d'autres mais en a en son sein (adresse écrite deux fois, numéro répété), et porte son record fusionné. Il reconnaît la même voie écrite de différentes façons ("V. Leopardi 4" ≈ "Via Giacomo Leopardi 4"), le code postal remis d'aplomb automatiquement et nom et prénom inversés.

Endpoint codice fiscale

Trois actions sur le codice fiscale (identifiant fiscal italien) des personnes physiques : generate à partir des données d'état civil, validate un code existant (format, caractère de contrôle et omocodia), extract les informations qu'il contient — date de naissance, âge, sexe, commune ou pays étranger de naissance. En plus, compare vérifie qu'un code correspond aux données déclarées. Il couvre les codes cadastraux de toutes les communes italiennes et des pays étrangers. Le nom et le prénom doivent être passés en caractères latins : pour une personne dont le nom est dans un autre alphabet, le code se calcule sur la translittération figurant sur le document, qui n'est pas unique (Dmitrij/Dmitry) ; un nom non latin renvoie cognome_non_latino ou nome_non_latino, et dans compare une différence sur le nom d'une personne née à l'étranger porte une note sur une possible translittération différente.

Les 500 premières opérations légères par mois sont gratuites (codice fiscale compris), et le quota est unique quel que soit le mode d'utilisation : ce que vous faites ici, sur le site et dans les fichiers par lots compte sur le même plafond. Au-delà, les opérations légères se paient à leur prix (voir tarifs).

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

Pour les volumes : { "action": "validate", "items": [ … ] } traite jusqu'à 500 éléments par appel, chacun avec son propre id de corrélation. L'extraction signale avec ambiguous_year les cas où les deux chiffres de l'année ne permettent pas de distinguer le siècle (1926 ou 2026).

Chaque réponse porte outcome, reason, notes et comments dans la langue de la requête : GENERATED pour generate, vide pour un code valide dans validate, MATCH ou MISMATCH pour compare (avec differences : les champs qui ne concordent pas). Quand le code échoue aux contrôles, le résultat est l'un des codes TAX_CODE_* listés ci-dessous et error en donne la forme courte (check_digit, length, format, homocode, month, date, place, empty) ; sur generate il dit quelle donnée manque ou ne se résout pas (last_name, first_name, gender, birth_date, birth_place, ambiguous_place avec options, last_name_non_latin). suggestion porte le code correct quand le contrôle sait le reconstruire.

Endpoint enrichissement

Enrichit un nom : sexe déduit du prénom, type de sujet (personne physique ou morale), titre normalisé (Dr.ssa, Avv., …) et formules d'appel prêtes pour la correspondance — "Egregio Sig. Rossi", "Gentile Dr.ssa Bianchi", "Spett.le" pour les entreprises, "Gentile Famiglia" pour les foyers, "Caro/Cara" pour le registre familier. Il reconnaît aussi la forme d'épouse dans le nom ("Rossi in Verdi" → femme, avec le détail des deux noms). Le champ gender accepte aussi les formes écrites (« maschio », « donna », « Sig.ra », « male ») ; X désigne un organisme et G une famille ou un couple. Si le titre manque, nous le déduisons de profession (la profession) ou de education, quand l'un des deux est renseigné. Les dictionnaires sont italiens.

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

Par lots : { "items": [ … ] }, jusqu'à 500 par appel. Le résultat est ENRICHED (sexe et formules d'appel définis), LEGAL_PERSON (société ou organisme : traité comme raison sociale) ou PARTIAL (prénom absent, ou sexe non déductible) : reason dit pourquoi, comments quoi ajouter pour compléter.

Endpoint vérification d'e-mail

Vérifie une adresse e-mail : syntaxe, existence du domaine (enregistrements MX/A), fautes de frappe des domaines courants avec correction proposée (gmial.com → gmail.com), domaines jetables, adresses génériques (info@, comptabilite@ : pas celles d'une personne). Nous ne faisons pas de vérification SMTP de la boîte elle-même, pratique intrusive et peu fiable. Lot items jusqu'à 500 ; "dns": false saute la consultation du domaine.

Une faute de frappe certaine est corrigée d'office : quand l'adresse telle qu'elle est écrite n'est même pas une adresse (nom@domaine,fr avec une virgule) ou quand la correction aboutit à un fournisseur connu (gmai.com → gmail.com, y compris à une lettre près si le domaine écrit ne reçoit pas de courrier), email ressort corrigé, corrected_from garde ce qui était écrit et le résultat est MODIFIED EMAIL_DOMAIN. Une faute possible sur un domaine quelconque (rossi.con) reste une proposition : EMAIL_TYPO avec la correction dans suggestion, et les contrôles (domain_exists, domain_checked) portent sur elle ; l'adresse telle qu'elle est écrite n'est pas vérifiée.

Un domaine à une frappe d'un fournisseur connu est corrigé selon la precision (1-5, 3 par défaut ; 4 et 5 valent 3). À 1 seulement si le domaine écrit n'existe pas (gmail.cob, hotmial.ocm) ; à 2 aussi s'il existe mais ne reçoit pas de courrier (libreo.it) ; à 3 aussi s'il reçoit des e-mails : domaines parqués, organisations réelles (libera.it, lice.it) et graphies « à l'oreille » (gemail.com, jmail.com). Une extension erronée sur un domaine quelconque (studiorossi.con) est corrigée si le bon domaine reçoit des e-mails. En dessous du niveau de la faute, renvoyé dans typo_level, l'adresse reste telle qu'écrite et similar_to donne l'adresse probablement voulue, avec une note. Avec "fix_typos": false, pour tout l'appel ou pour un seul élément, aucune faute n'est corrigée : l'adresse reste telle qu'écrite et la correction sort dans similar_to. Utile quand la personne a confirmé vouloir précisément cette adresse.

Endpoint vérification de téléphone

Contrôle un numéro sans appeler personne : forme, classe et type, longueur selon le plan de numérotation, zone du fixe et opérateur auquel la tranche a été attribuée à l'origine. La class est la lecture qui sert à travailler une liste : mobile (vous pouvez lui envoyer un SMS), landline (vous l'appelez aux heures de bureau), special (ce n'est pas la coordonnée d'une personne : urgences, utilité publique, numéros verts et à tarif majoré), foreign pour les numéros avec indicatif international. Quand nous reconnaissons aussi le service précis, type le dit (numéro vert, tarif spécial, coût partagé, utilité publique). L'indicatif italien écrit sans le + (39347…, coquille classique des exports), nous l'enlevons quand les chiffres ne laissent aucun doute — 3934567890 reste le mobile qu'il est. Si le même champ contient plusieurs numéros (« 347… - 338… »), nous les séparons : ils reviennent comme phone, phone2, phone3, et phone n'est jamais vide quand il y a au moins un numéro. Avec "format": "international", le numéro italien sort sous la forme +39… ; la valeur par défaut national le laisse nu et ne met l'indicatif que sur les numéros étrangers. Pour les étrangers reviennent aussi e164, le pays de l'indicatif dans country_code, et le zéro de réseau après l'indicatif est enlevé (« +44 (0)20… » et « +44 20… » donnent le même numéro). Avec country_code (ou country) dans l'appel ou dans l'élément, un numéro écrit sans indicatif est lu comme numéro national de ce pays : « 020 7946 0958 » dans une fiche du Royaume-Uni, c'est Londres, pas Milan. Sans pays, il reste italien. Lot items jusqu'à 500.

Un numéro du pays de la fiche n'est pas « étranger » : là où nous connaissons le plan de numérotation, il reçoit sa class (mobile, landline, special), avec format national il reste sans indicatif dans la forme de son pays (zéro de réseau compris), et national_number est renvoyé à côté de e164. PHONE_FOREIGN et class foreign restent pour les numéros d'un pays autre que celui de la fiche.

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 vérification de site web

Vérifie que l'adresse est bien écrite et que le site répond vraiment : existence du domaine, requête HTTP avec suivi des redirections, code final, validité du certificat. Aucun jugement sur le contenu. Ici aussi, plusieurs adresses dans le même champ reviennent comme website, website2, website3. Avec "network": false, nous contrôlons seulement la forme, sans contacter le site. Lot items jusqu'à 100 : chaque vérification ouvre une connexion, le lot est donc plus petit que sur les autres endpoints.

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

Endpoint autocomplétion d'adresse

Vous partez de zéro ? Le widget ra-suggerisci.js et un petit proxy sur votre serveur suffisent : le jeton ne va jamais dans le navigateur.

Des suggestions pendant que l'utilisateur tape une adresse dans votre formulaire : tout le référentiel des voies italien, avec le nom complété (« via verdi » → « Via Giuseppe Verdi »), commune et province ; le code postal arrive avec la sélection, dans les grandes villes à zones postales le bon code du numéro. Cela fonctionne par session : le client génère un UUID pour chaque adresse en cours de saisie, les requêtes de suggestion sont gratuites, et vous payez une vérification d'adresse quand l'utilisateur sélectionne et que les champs se remplissent (action select, qui renvoie la fiche déjà normalisée par le moteur). Les champs déjà remplis dans le formulaire — même en partie — voyagent comme contexte et resserrent les suggestions.

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

Une fois la voie choisie, le numéro se complète : en passant street_id avec le numéro partiel, vous obtenez les numéros existants de cette voie, avec exists vrai/faux pour valider celui qui a été tapé — et la sélection peut se répéter avec le numéro sans nouveau débit : le débit est par session et par voie, pas par clic ; une autre voie dans la même session est un autre débit. Les numéros ne se complètent que dans la session qui a sélectionné cette voie. Dans les villes à zones postales, c'est le numéro qui détermine le code postal exact.

Le token API ne va jamais dans le navigateur : le widget prêt à l'emploi (ra-suggerisci.js) appelle un petit proxy sur votre serveur, qui ajoute le token et transmet. Chaque session admet jusqu'à 30 appels et vaut 10 minutes ; les sessions sans sélection sont gratuites jusqu'à 200 par jour et par token, plus cinq par sélection. Widget, proxy prêt et formulaire d'exemple se trouvent dans le kit de Votre formulaire.

Fonctionne dans chaque pays en service (aujourd'hui France, Allemagne, Espagne, Pays-Bas, Belgique, Finlande, Suisse, Tchéquie, Portugal, Danemark, Norvège, Autriche, Slovaquie, Croatie, Grèce, Roumanie, Hongrie, Slovénie, Irlande, Islande, Luxembourg, Liechtenstein, Saint-Marin, Monaco, Andorre, Cité du Vatican ; la liste à jour est dans Pays) : avec country_code ou country, les suggestions viennent du registre de ce pays, et le texte s'écrit comme on l'écrit là-bas — rue, numéro, code postal et ville même dans un seul champ : «kalverstraat 92 amst», «92 rue de rivoli paris», aux Pays-Bas «1012PH 92». Chaque réponse porte parsed, c'est-à-dire comment le serveur a lu la rue (street), le numéro (house_number) et le code postal (postcode) : votre formulaire sait où se trouve le numéro sans connaître les règles du pays. Les suggestions portent la rue, la ville, la localité s'il y en a une, et source (registry, ou osm là où le registre national ne publie pas) ; le code postal et les numéros ne figurent jamais dans les suggestions : ils arrivent avec la sélection, qui passe par le moteur et renvoie le même enregistrement que /contact (postcode confirmé par le registre, geo au numéro). Avec la sélection vous pouvez aussi passer postcode, celui écrit dans le formulaire. attribution est la mention de source à afficher à côté des suggestions : la licence du registre l'exige. Si le pays manque, IT est présumé ; pour un pays hors service la réponse reste HTTP 200 avec supported:false et hints:[], sans créer la session ni rien facturer. Une session appartient à un pays : s'il change, le client génère un nouvel UUID (sinon 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"}

Gros volumes : le traitement asynchrone

Les appels normaux répondent tout de suite, et c'est pourquoi ils ont un plafond d'éléments — une requête HTTP qui dure des minutes ne sert à personne. Les plafonds suivent le poids de l'opération :

Au-delà de ces nombres, pas besoin de découper la liste à la main : on ajoute "async": true et l'appel revient tout de suite avec un code, pendant que le traitement rejoint la même file d'attente que le chargement de fichiers. Jusqu'à 100 000 éléments par appel, et dans Mes traitements il n'en apparaît qu'un seul.

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

Ensuite, vous le relisez quand il le faut, et le résultat arrive en JSON ou en 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

Avec format=zip, vous téléchargez à la place tous les fichiers du traitement dans un zip : le fichier nettoyé, avec vos colonnes et les corrections déjà écrites là où elles sont confirmées ; les lignes à contrôler ; ce qui change, cellule par cellule ; le résultat complet ; un README qui les explique. Avec format=zip_xlsx, les mêmes fichiers sont en Excel.

Sous 5 000 lignes, le résultat revient aussi dans results à l'intérieur du JSON ; au-dessus, il se télécharge en CSV. Le débit a lieu quand le traitement est mis en file d'attente, et la partie non traitée revient sur votre solde si le traitement s'arrête. Le token doit être lié à un compte : le traitement finit dans votre file.

L'appel qui met le traitement en file d'attente répond HTTP 202 avec l'en-tête Location, qui pointe vers le traitement. Quand vous n'avez plus besoin du résultat, vous le supprimez avec DELETE à la même adresse : la réponse est HTTP 204, et les fichiers et les données n'existent plus. Un traitement encore en file d'attente ou en cours répond 409 job_running : supprimez-le une fois terminé. Si vous ne le supprimez pas, le traitement est supprimé automatiquement au bout de 30 jours. Cela vaut aussi pour le résultat enregistré de /dedupe.

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

HTTP/1.1 204 No Content

Codes de statut

Chaque réponse contient le champ outcome : une liste de mots-clés, vide quand il n'y a rien à signaler. Le schéma est toujours <conditions> [MODIFIED <types>] — les conditions devant, les modifications à la fin — et vaut pour tous les services. À côté, vous trouvez outcome_label (ou kind) avec ok, modified, warning, error, et reason avec l'explication en une ligne. Les codes sont des identifiants : ils se comparent, ils ne se traduisent pas ; avec "language": "it" ressortent les codes italiens (LOCALITA_NON_TROVATA MODIFICATO CAP INDIRIZZO), les mêmes mot pour mot.

Adresse (vérification d'adresse)

Codice fiscale italien

Sur l'endpoint /tax-code, les mêmes contrôles ont leurs propres codes — 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 — parce que là, le codice fiscale est l'objet de la vérification, pas un champ de la fiche.

Enrichissement

E-mail

Téléphone

Site web

Ce que consomme chaque appel

Chaque appel consomme des opérations du compteur du service : vérification d'adresse (/contact, /suggest à la sélection), dédoublonnage (/dedupe) et opérations légères (/email, /phone, /website, /enrichment, /tax-code au-delà du quota gratuit). Les opérations s'achètent par packs qui restent, ou avec un abonnement mensuel ; le prix pour 1 000 baisse avec la taille et se trouve sur la page tarifs. Chaque mois, 50 vérifications d'adresse, 100 fiches en dédoublonnage et 500 opérations légères sont gratuites.

Chaque réponse dit ce qu'elle a consommé et d'où : le champ credit du JSON (counter, charged, free, subscription et packs avec les opérations prélevées et le reste, available, auto_topup avec le nombre de packs achetés automatiquement, note) et les en-têtes X-RA-Charged, X-RA-Available et, quand elle intervient, X-RA-Auto-Topup. Si les opérations disponibles ne couvrent pas l'appel et que la recharge automatique du compteur n'est pas active (ou échoue), la réponse est 402 payment_required et rien n'est traité.

Le corps de la réponse 402 contient aussi credit.purchase_url : la page Crédits de votre compte, avec le plus petit pack qui couvre ce qui manque, prête à ouvrir.

Pour savoir combien d'opérations il reste sans en consommer aucune, il y a GET /api/v1/credit. Pour chacun des trois compteurs (contact, dedupe, light), il renvoie available, les gratuites (free) restantes dans le mois et la date à laquelle elles se remettent à zéro (le 1er), l'subscription (reste, taille, renouvellement), les packs actifs un par un avec ce qu'il en reste (ils n'expirent pas) et combien vous en avez achetés, l'auto_topup (active, taille, plafond et dépense du mois en euros), l'utilisation (used dans le mois, totaux, dernière utilisation) et surtout le state, parce qu'un zéro tout seul ne dit pas si vous avez tout épuisé ou si vous n'utilisez pas ce service : never_used, free (jamais acheté, vous travaillez dans les gratuites du mois), free_used_up, active, awaiting_renewal, used_up (vous avez acheté par le passé et il ne reste rien : à recharger), avec un warning. En tête, needs_topup énumère les compteurs sur lesquels intervenir et endpoint dit quel compteur consomme chaque endpoint. Il exige le token d'un compte.

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

Vous payez par élément vérifié, pas par appel : si un champ contient deux numéros de téléphone ou deux e-mails, nous les vérifions tous (jusqu'à trois par ligne) et chacun consomme une opération. Un appel par lot consomme autant que les opérations qu'il contient. Si le crédit est épuisé et que la recharge automatique n'est pas active, l'API répond HTTP 402 (crédit insuffisant) ; au-delà de la limite de requêtes, elle répond HTTP 429 avec retry_after. Vous achetez un pack depuis l'espace personnel, ou activez un abonnement pour payer l'opération moins cher.