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.

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.

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" ou appelle www.radaraddress.it sans indiquer de langue.

Le tableau complet des champs : anglais → italien

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

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 de contact

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.

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, Tchéquie, Portugal, Danemark, Norvège, Autriche, Suisse, Slovaquie, Croatie, 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.

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).

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é (Dott.ssa, Avv., …) et formules d'appel prêtes pour la correspondance — "Egregio Sig. Rossi", "Gentile Dott.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": "Dott.ssa",
    "formal_salutation": "Gentile Dott.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.

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":"3470328959 - 011 1253265"}'

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 de contact 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, Tchéquie, Portugal, Danemark, Norvège, Autriche, Suisse, Slovaquie, Croatie, 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 coût 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 … ]}'

{"ok":true,"job":"369e46e9e7bb…","state":"queued","rows":100000}

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

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.

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 de contact)

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 de contact (/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 de contact, 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é.

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 paie son prix. 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.