El mismo motor,
dentro de tu aplicación.

Un endpoint por servicio, con el mismo nombre que el servicio tiene en este sitio: /contact, /dedupe, /email, /phone, /website, /tax-code, /enrichment. Cada uno acepta un elemento en el cuerpo de la petición o una lista en items, hasta 500 por llamada (100 para los sitios web, que hay que contactar uno a uno). La deduplicación es la excepción y siempre quiere una lista: compara los registros entre sí. Aparte quedan /suggest, el autocompletado para formularios (trabaja por sesión mientras el usuario teclea, no por lotes), y /credit, que dice cuántas operaciones quedan y en qué estado está cada contador, sin consumir ninguna.

Autenticación

El host de la API es www.radaraddress.com. Los nombres de los campos, de los endpoints y de los valores son identificadores en inglés, iguales en todos los idiomas; las etiquetas, los motivos y los mensajes siguen el idioma de la petición ("language": "de" o ?language=de, o la cabecera Accept-Language, o el idioma de la cuenta). La cabecera Content-Language dice en qué idioma ha llegado la respuesta.

Opcional: si llamas a la API desde un formulario, puedes indicar dónde está con dos cabeceras, X-RadarAddress-Form-Page (la dirección de la página del formulario) y X-RadarAddress-Form (qué formulario y en qué punto, por ejemplo checkout/billing). Así cada operación se puede relacionar con el formulario del que llegó. De la página guardamos solo el dominio y la ruta, sin la parte después del signo de interrogación.

El acceso a la API se hace con un token Bearer. La cuenta es gratuita: creas el token desde el área personal y lo incluyes en la cabecera de cada petición con este formato:

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

Al crearlo puedes darle al token una caducidad opcional: pasada esa fecha las peticiones reciben HTTP 401 con el código token_expired; sin caducidad el token vale hasta que lo revoques. Puedes revocarlo o regenerarlo en cualquier momento desde tu área personal, donde también ves el último uso y el número de peticiones atendidas. Una petición sin token o con un token no válido devuelve HTTP 401.

Cada método HTTP hace lo que dice su nombre: GET lee y no consume operaciones (/credit, /countries, la relectura de un trabajo), POST procesa, DELETE elimina un trabajo. Un método que el endpoint no acepta recibe HTTP 405 con la cabecera Allow, que enumera los correctos.

Los nombres italianos, para quien ya los usa

La API tiene una sola versión, en inglés. Quien integró con los nombres italianos no tiene que cambiar nada: los campos italianos se aceptan en cualquier petición, los endpoints responden también con su nombre italiano (/contatto, /deduplica, /codicefiscale, /arricchimento, /telefono, /sito, /suggerisci, /nazioni, /credito), y la respuesta sale con las claves y los códigos italianos para quien lo pide con "language": "it".

La tabla completa de los campos: inglés → italiano

inglés	italiano	inglés	italiano
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

También los valores de las opciones tienen nombre italiano: format nazionale/internazionale, action genera/valida/estrai/confronta/seleziona, foreign dichiarati/rileva, min_level certo/probabile/ambiguo; con "language": "it" salen así también level, confidence, state, los códigos de outcome y las cabeceras de los archivos. En la entrada se aceptan también sinónimos habituales (zip, surname, phone_number, date_of_birth…) y las mismas cabeceras en los archivos de los trabajos por lotes.

Endpoint de verificación de direcciones

Arregla el contacto entero: la dirección según el estándar postal de su país — en Italia y en los países con registro en servicio, la vía y el número se verifican en el registro nacional de direcciones; en los demás la dirección sale en la forma postal del país —, el nombre y — si la petición lo trae — el código fiscal italiano, que se limpia, se completa si solo falta el carácter de control y se contrasta con apellido, nombre, sexo y fecha de nacimiento. Un contacto cada vez, o hasta 500 en items: el esquema es el mismo que en todos los demás endpoints.

En el mismo registro puedes pasar email, phone y website: los comprobamos en la misma operación, junto con el nombre y el tax_code. La respuesta incluye email_outcome, phone_outcome, website_outcome y enrichment (sexo, título, fórmula de saludo). Sus resultados no entran en outcome, que sigue siendo el de la dirección y el código fiscal. En una lista los sitios web se contactan hasta 100 por llamada: en los demás solo se comprueba la forma.

Dos interruptores, activados si no los envías: network:false no contacta con los sitios y dns:false no comprueba si el dominio de los correos recibe mensajes. Así queda solo el control de la forma y es más rápido. Valen para toda la llamada, también con async, y son los mismos de /website y /email.

El país se indica con country_code (ISO 3166-1: IT, DE, FR…) o con country, escrito como venga: «Germania», «Germany», «Deutschland», «República Federal de Alemania», «UK», «Holanda». Si falta, se presume Italia. En los países con registro en servicio — hoy Francia, Alemania, España, Países Bajos, Bélgica, Finlandia, Suiza, Chequia, Portugal, Dinamarca, Noruega, Austria, Eslovaquia, Croacia, Grecia, Rumanía, Hungría, Eslovenia, Irlanda, Islandia, Luxemburgo, Liechtenstein, San Marino, Mónaco, Andorra, Ciudad del Vaticano, la lista actualizada está en Países — la vía y el número se verifican en el registro nacional de direcciones como en Italia: código postal confirmado o completado, coordenadas del número en geo, barrio o distrito en district donde la ciudad los tiene (Hamburg-Altstadt, Paris 4e Arrondissement), código del municipio en territory.municipality_code. En italiano el resultado lleva FOREIGN seguido de los cambios, en los demás idiomas solo los cambios; si la vía existe y el número no, HOUSE_NUMBER_NOT_FOUND. En los demás países trabajamos sobre la forma, y el mensaje lo dice: código postal en el formato del país, abreviaturas de la vía desarrolladas, mayúsculas y nombre de la ciudad como los escribe el correo de ese país (Hauptstr. 5, Múnich → Hauptstraße 5, MÜNCHEN), con la línea del país. En ambos casos vuelve address_key, la forma con la que la deduplicación reconoce la misma vía escrita de dos maneras. Con "foreign": "detect" un registro sin país que no se encuentra en Italia se reconoce como extranjero cuando el texto lo dice claramente; el valor por defecto declared deja como extranjero solo lo que lo declara. El catálogo completo de países, con nombre corto y oficial, en inglés y en la lengua del país, está disponible con GET /api/v1/countries y se consulta con ?q=Germania, ?q=Deutschland o ?q=DE.

Para un lote de un solo país no hace falta repetir el país en cada elemento: default_country ("DE", "Germany") vale para los elementos que no lo indican, en la verificación de direcciones, la deduplicación, el enriquecimiento (elige el diccionario de nombres) y la verificación de teléfono, también en los trabajos asíncronos. El país escrito en el elemento gana siempre; sin ninguno de los dos, el elemento es italiano.

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

Para el lote, los mismos campos dentro de items; la respuesta es { count, results: [ { id, result } ] } en el mismo orden del envío.

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

El mismo endpoint para una dirección de otro país: basta country_code. Aquí Hamburgo, verificada en el registro alemán, con el barrio y las coordenadas del número.

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

Opciones válidas para toda la llamada: postal_form (fuerza también normalized a la forma postal), preserve_original (conserva el nombre tal como lo escribió el usuario y expone el canónico aparte), precision 1–5 (predeterminado 3; por encima de 3 la coincidencia es aproximada y la fiabilidad no será high).

Los niveles de precision: cada uno hace también lo de los anteriores.

• 1 Estricta: La localidad tal como está escrita; en la calle, solo las correcciones que los datos confirman sin dudas.
• 2 Ajustada: Además corrige códigos postales y provincias erróneos y reconoce las localidades abreviadas.
• 3 Normal (predeterminada): Además encuentra los nombres escritos a medias y lleva la dirección al municipio donde la calle existe de verdad.
• 4 Amplia: Además acepta los nombres que suenan igual y, entre calles con el mismo nombre, elige la más conocida. La fiabilidad nunca es alta.
• 5 Máxima: Todo lo que se puede encontrar. La fiabilidad nunca es alta.

Junto con la dirección vuelve city_type, que dice si el punto de entrega está en una capital de provincia o en un municipio de la provincia — la diferencia que necesita quien segmenta una campaña por ciudad. provincial_capital es true, false o null cuando no tenemos elementos para decirlo — y en ese caso no lo adivinamos.

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

Junto al código postal llega postcode_check: de dónde viene (source) y con qué precisión (precision: house_number el propio número, interpolated los números vecinos de la misma calle, street la mayoría de la calle, locality, municipality), cuántos números lo dicen (house_numbers) y con qué acuerdo (agreement, de 0 a 1). Si falta confirmación para ese número el resultado lleva POSTCODE_UNCONFIRMED y confirmed es false: el código postal se mantiene como se indicó, si es uno de los de la ciudad, y conviene comprobarlo.

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

Vuelven también las coordenadas en geo (latitud y longitud WGS84) y los identificadores territoriales en territory: en Italia el código ISTAT y el código catastral del municipio, el CAB y el identificador nacional de la vía; en los demás países country y el código del municipio en el registro nacional (municipality_code). El campo precision dice a qué nivel hemos llegado: house_number cuando el número está georreferenciado, interpolated cuando falta el número exacto y el punto es estimado, street cuando tenemos el punto de la vía, municipality cuando solo tenemos el centro del municipio. source dice de dónde viene el punto: anncsu es el registro nacional italiano, inspire el registro nacional del país, osm OpenStreetMap: en ese caso los datos son © OpenStreetMap contributors, licencia ODbL, y la atribución debe reproducirse si los publicas. Donde el registro de un país impone una atribución, sale en el mensaje. En el CSV de los trabajos por lotes son las columnas latitude, longitude, geo_precision, istat_code y 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" } }

El piso, la escalera y la puerta escritos en la dirección vuelven también como dato propio en sub_address: una lista de pares type y value, leídos con las reglas postales del país (en Alemania tras «//», en Francia en una línea propia, en Portugal «3º Esq»). Los tipos son unit (puerta), staircase (escalera), floor (piso), block, building, building_number y block_number. La línea de la dirección se queda en la forma del país. Lo que no reconocemos se queda como estaba escrito y no entra en la lista: no lo adivinamos. Cuando la unidad indicada consta en ese número, sub_address_confirmed es true; si no, null, nunca false: no encontrarla no quiere decir que esté mal.

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

Endpoint de deduplicación

Reconoce los registros que se refieren a la misma persona en la misma dirección aunque estén escritos de forma distinta: diminutivos y equivalencias de nombres (Dany ≈ Daniela), apellidos y nombre invertidos, abreviaturas ("V. Roma" ≈ "Via Roma"), erratas de tecleo. La comparación de direcciones pasa por el motor de normalización: dos grafías distintas de la misma calle colapsan en la forma canónica antes de la comparación. Máximo 500 contactos por llamada (registros + referencia); para listas más grandes usa el trabajo por lotes desde el área personal.

Agendas de contactos. Un contacto de la agenda (Contactos de Apple, Google, Outlook: el modelo vCard) tiene varias direcciones, varios teléfonos y varios emails, cada uno con una etiqueta. El endpoint los acepta así, sin tope: addresses es una lista de objetos con type y los campos de siempre; phones y emails son listas en las que cada elemento es el dato solo ("340 7491386") o {"type": "work", "value": "02 66710423"}, incluso mezclados; los campos planos de siempre siguen siendo válidos y cuentan como primera dirección y primer dato de contacto. Dos contactos son la misma persona si cualquier pareja de sus direcciones coincide (la oficina de uno con la única dirección del otro), o si tienen el mismo nombre y un teléfono o un email en común, en cualquier posición y con cualquier etiqueta. La etiqueta no pesa en el emparejamiento: vuelve tal como llegó, más type_normalized en el vocabulario vCard (home, work, cell…), para que la aplicación sepa dónde reescribir. Un contacto es una operación, tenga las direcciones y los datos de contacto que tenga.

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 respuesta agrupa los duplicados en groups: cada grupo enumera los id de sus members, indica cuál conservar (main_record) y propone el record consolidado: el mejor nombre y la unión de direcciones y datos de contacto (addresses, phones, emails), cada uno con su tipo, con provenance (de qué contactos viene) y deduplicado: la misma calle con dos grafías es una sola dirección, el mismo número con dos etiquetas un solo número. Los contactos sin coincidencias están en singles, como objetos {id, outcome}: con outcome INTERNAL_DUPLICATE el contacto no tiene duplicados con otros pero sí en su interior (dirección escrita dos veces, número repetido), y lleva su record fusionado. Reconoce la misma calle escrita de distintas maneras ("V. Leopardi 4" ≈ "Via Giacomo Leopardi 4"), el código postal corregido automáticamente y apellidos y nombre invertidos.

Endpoint del código fiscal italiano

Tres acciones sobre el código fiscal italiano de las personas físicas: generate a partir de los datos personales, validate un código existente (formato, carácter de control y omocodia), extract la información que contiene — fecha de nacimiento, edad, sexo, municipio o país extranjero de nacimiento. Además, compare comprueba que un código corresponde a los datos personales declarados. Cubre los códigos catastrales de todos los municipios italianos y de los países extranjeros. Apellidos y nombre deben pasarse en caracteres latinos: para quien tiene un nombre en otro alfabeto, el código se calcula sobre la transliteración que figura en el documento, que no es única (Dmitrij/Dmitry); un nombre no latino devuelve cognome_non_latino o nome_non_latino, y en compare una diferencia en el nombre de quien nació en el extranjero lleva una nota sobre la posible transliteración distinta.

Las primeras 500 operaciones ligeras al mes son gratuitas (código fiscal incluido), y el cupo es uno solo en todas las modalidades de uso: lo que haces aquí, en la web y en los archivos por lotes cuenta sobre el mismo cupo. Más allá, se paga el precio de las operaciones ligeras (ver precios).

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

Para los volúmenes: { "action": "validate", "items": [ … ] } procesa hasta 500 elementos por llamada, cada uno con su propio id de correlación. La extracción señala con ambiguous_year los casos en que las dos cifras del año no distinguen el siglo (1926 frente a 2026).

Cada respuesta lleva outcome, reason, notes y comments en el idioma de la petición: GENERATED para generate, vacío para un código válido en validate, MATCH o MISMATCH para compare (con differences: los campos que no cuadran). Cuando el código no supera los controles, el resultado es uno de los códigos TAX_CODE_* listados abajo y error da su forma corta (check_digit, length, format, homocode, month, date, place, empty); en generate dice qué dato falta o no se resuelve (last_name, first_name, gender, birth_date, birth_place, ambiguous_place con options, last_name_non_latin). suggestion lleva el código correcto cuando el control sabe reconstruirlo.

Endpoint de enriquecimiento

Enriquece un nombre: sexo deducido del nombre de pila, tipo de sujeto (persona física o jurídica), título normalizado (Dr.ssa, Avv., …) y fórmulas de saludo listas para la correspondencia — "Egregio Sig. Rossi", "Gentile Dr.ssa Bianchi", "Spett.le" para las empresas, "Gentile Famiglia" para las familias, "Caro/Cara" para el registro informal. Reconoce también la forma de casada en el apellido ("Rossi in Verdi" → mujer, con el detalle de los dos apellidos). El campo gender acepta también las formas escritas («maschio», «donna», «Sig.ra», «male»); X indica una entidad y G una familia o una pareja. Si falta el título, lo obtenemos de profession (la profesión) o de education, cuando se indica alguno. Los diccionarios son italianos.

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

Por lotes: { "items": [ … ] }, hasta 500 por llamada. El resultado es ENRICHED (sexo y saludos establecidos), LEGAL_PERSON (empresa o entidad: se trata como razón social) o PARTIAL (falta el nombre, o el sexo no se deduce): reason dice por qué, comments qué añadir para completar.

Endpoint de verificación de email

Verifica una dirección de email: sintaxis, existencia del dominio (registros MX/A), erratas en los dominios comunes con corrección propuesta (gmial.com → gmail.com), dominios desechables, direcciones genéricas (info@, administracion@: no son de una persona). No hacemos la verificación SMTP del buzón concreto, una práctica invasiva y poco fiable. Lote items hasta 500; "dns": false omite la consulta del dominio.

Una errata segura se corrige de oficio: cuando la dirección tal como está escrita ni siquiera es una dirección (nombre@dominio,es con coma) o cuando la corrección cae en un proveedor conocido (gmai.com → gmail.com, también a una letra de distancia si el dominio escrito no recibe correo), email sale corregido, corrected_from lleva cómo estaba escrito y el resultado es MODIFIED EMAIL_DOMAIN. Una errata posible en un dominio cualquiera (rossi.con) sigue siendo una propuesta: EMAIL_TYPO con la corrección en suggestion, y las comprobaciones (domain_exists, domain_checked) hechas sobre ella; la dirección tal como está escrita no se verifica.

Un dominio a una pulsación de un proveedor conocido se corrige según la precision (1-5, por defecto 3; 4 y 5 valen como 3). Con 1 solo si el dominio escrito no existe (gmail.cob, hotmial.ocm); con 2 también si existe pero no recibe correo (libreo.it); con 3 también si recibe correo: dominios aparcados, organizaciones reales (libera.it, lice.it) y grafías «de oído» (gemail.com, jmail.com). Una extensión equivocada en un dominio cualquiera (studiorossi.con) se corrige si el dominio correcto recibe correo. Por debajo del nivel de la errata, que se devuelve en typo_level, la dirección queda tal como está escrita y similar_to lleva la dirección que probablemente se quería, con una nota. Con "fix_typos": false, para toda la llamada o para un solo elemento, no se corrige ninguna errata: la dirección queda tal como está escrita y la corrección sale en similar_to. Sirve cuando la persona ha confirmado que quiere justo esa dirección.

Endpoint de verificación de teléfono

Comprueba un número sin llamar a nadie: forma, clase y tipo, longitud según el plan de numeración, distrito del fijo y operador al que se asignó el bloque en origen. La class es la lectura que hace falta para trabajar una lista: mobile (le mandas un SMS), landline (lo llamas en horario de oficina), special (no es el número de una persona: emergencias, utilidad pública, números gratuitos y de tarificación especial), foreign para los números con prefijo internacional. Cuando reconocemos también el servicio concreto, type lo dice (número gratuito, tarificación especial, coste compartido, utilidad pública). El prefijo italiano escrito sin el + (39347…, errata clásica de las exportaciones) lo quitamos cuando las cifras no dejan lugar a dudas — 3934567890 sigue siendo el móvil que es. Si en el mismo campo hay varios números («347… - 338…») los separamos: vuelven como phone, phone2, phone3, y phone nunca está vacío cuando hay al menos un número. Con "format": "international" el número italiano sale en la forma +39…; el valor predeterminado national lo deja sin prefijo y se lo pone solo a los extranjeros. Para los extranjeros vuelve también e164, el país del prefijo en country_code, y el cero de red después del prefijo se quita («+44 (0)20…» y «+44 20…» dan el mismo número). Con country_code (o country) en la llamada o en el elemento, un número escrito sin prefijo se lee como número nacional de ese país: «020 7946 0958» en una ficha del Reino Unido es Londres, no Milán. Sin país sigue siendo italiano. Lote items hasta 500.

Un número del país del registro no es «extranjero»: donde conocemos el plan de numeración recibe su class (mobile, landline, special), con format national queda sin prefijo en la forma de su país (cero de red incluido) y se devuelve también national_number junto a e164. PHONE_FOREIGN y class foreign quedan para los números de un país distinto del registro.

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 de verificación de sitio web

Comprueba que la dirección esté bien escrita y que el sitio responda de verdad: existencia del dominio, petición HTTP siguiendo las redirecciones, código final, validez del certificado. Ningún juicio sobre el contenido. También aquí varias direcciones en el mismo campo vuelven como website, website2, website3. Con "network": false comprobamos solo la forma, sin contactar con el sitio. Lote items hasta 100: cada verificación abre una conexión, así que el lote es más pequeño que en los demás 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 de autocompletado de direcciones

¿Empiezas desde cero? Con el widget ra-suggerisci.js y un pequeño proxy en tu servidor es suficiente: el token nunca llega al navegador.

Sugerencias mientras el usuario teclea una dirección en tu formulario: todo el callejero nacional italiano, con el nombre completado («via verdi» → «Via Giuseppe Verdi»), municipio y provincia; el código postal llega con la selección, en las grandes ciudades con zonas postales el correcto del número. Funciona por sesión: el cliente genera un UUID por cada dirección que se está rellenando, las consultas de sugerencia son gratuitas, y se paga una verificación de dirección cuando el usuario selecciona y los campos se rellenan (acción select, que devuelve el registro ya normalizado por el motor). Los campos ya rellenados en el formulario — aunque sea en parte — viajan como contexto y afinan las sugerencias.

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

Elegida la calle, se completa el número: pasando street_id con el número parcial se obtienen los números existentes de esa calle, con exists verdadero/falso para validar el que se ha teclado — y la selección se puede repetir con el número sin nuevo cargo: el cargo es por sesión y por calle, no por clic; otra calle en la misma sesión es otro cargo. Los números se completan solo en la sesión que ha seleccionado esa calle. En las ciudades con zonas postales es el número el que determina el código postal exacto.

El token de la API nunca va al navegador: el widget listo para usar (ra-suggerisci.js) llama a un pequeño proxy en tu servidor, que añade el token y reenvía la petición. Cada sesión admite hasta 30 llamadas y dura 10 minutos; las sesiones sin selección son gratuitas hasta 200 al día por token, más cinco por cada selección. El widget, el proxy listo y el formulario de ejemplo están en el kit de Tu formulario.

Funciona en cada país en servicio (hoy Francia, Alemania, España, Países Bajos, Bélgica, Finlandia, Suiza, Chequia, Portugal, Dinamarca, Noruega, Austria, Eslovaquia, Croacia, Grecia, Rumanía, Hungría, Eslovenia, Irlanda, Islandia, Luxemburgo, Liechtenstein, San Marino, Mónaco, Andorra, Ciudad del Vaticano; la lista actualizada está en Países): con country_code o country las sugerencias vienen del registro de ese país, y el texto se escribe como se escribe allí — calle, número, código postal y ciudad incluso en un solo campo: «kalverstraat 92 amst», «92 rue de rivoli paris», en los Países Bajos «1012PH 92». Cada respuesta lleva parsed, es decir, cómo el servidor ha leído la calle (street), el número (house_number) y el código postal (postcode): tu formulario sabe dónde va el número sin conocer las reglas del país. Las sugerencias llevan calle, ciudad, localidad si la hay, y source (registry, u osm donde el registro nacional no publica); el código postal y los números nunca están en las sugerencias: llegan con la selección, que pasa por el motor y devuelve el mismo registro que /contact (postcode confirmado por el registro, geo en el número). Con la selección también puedes pasar postcode, el escrito en el formulario. attribution es la mención de la fuente que hay que mostrar junto a las sugerencias: la licencia del registro lo exige. Si falta el país se presume IT; para un país fuera de servicio la respuesta sigue siendo HTTP 200 con supported:false y hints:[], sin crear la sesión ni cobrar nada. Una sesión es de un país: si cambia, el cliente genera un nuevo UUID (si no, 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"}

Volúmenes grandes: el trabajo asíncrono

Las llamadas normales responden al instante, y por eso tienen un tope de elementos — una petición HTTP que dura minutos no le sirve a nadie. Los topes siguen lo que pesa la operación:

Por encima de esos números no hace falta partir la lista a mano: se añade "async": true y la llamada vuelve al instante con un código, mientras el procesamiento entra en la misma cola que la carga de archivos. Hasta 100.000 elementos por llamada, y en Mis trabajos aparece uno solo.

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

Luego se relee cuando hace falta, y el resultado llega en JSON o como 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

Con format=zip descargas en cambio todos los archivos del trabajo en un zip: el archivo limpio, con tus columnas y las correcciones ya escritas donde están confirmadas; las filas por comprobar; qué cambia, celda por celda; el resultado completo; un README que los explica. Con format=zip_xlsx los mismos archivos están en Excel.

Por debajo de las 5.000 filas el resultado vuelve también en results dentro del JSON; por encima, se descarga en CSV. El cargo se hace cuando el trabajo entra en la cola, y la parte no procesada vuelve a tu saldo si el trabajo se detiene. El token debe estar vinculado a una cuenta: el trabajo acaba en tu cola.

La llamada que pone el trabajo en cola responde HTTP 202 con la cabecera Location, que apunta al trabajo. Cuando ya no necesitas el resultado, lo eliminas con DELETE en la misma dirección: la respuesta es HTTP 204, y los archivos y los datos ya no existen. Un trabajo todavía en cola o en proceso responde 409 job_running: elimínalo cuando haya terminado. Si no lo eliminas tú, el trabajo se elimina solo pasados 30 días. Vale también para el resultado guardado 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

Códigos de resultado

Cada respuesta incluye el campo outcome: una lista de palabras clave, vacía cuando no hay nada que señalar. El esquema es siempre <conditions> [MODIFIED <types>] — las condiciones delante, los cambios al final — y vale para todos los servicios. Al lado encuentras outcome_label (o kind) con ok, modified, warning, error, y reason con la explicación en una línea. Los códigos son identificadores: se comparan, no se traducen; con "language": "it" salen los códigos italianos (LOCALITA_NON_TROVATA MODIFICATO CAP INDIRIZZO), los mismos palabra por palabra.

Dirección (verificación de direcciones)

Código fiscal italiano

En el endpoint /tax-code los mismos controles tienen códigos propios — 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 — porque allí el código fiscal es el objeto de la verificación, no un campo del registro.

Enriquecimiento

Email

Teléfono

Sitio web

Cuánto consume cada llamada

Cada llamada consume operaciones del contador del servicio: verificación de direcciones (/contact, /suggest en la selección), deduplicación (/dedupe) y operaciones ligeras (/email, /phone, /website, /enrichment, /tax-code más allá del cupo gratuito). Las operaciones se compran en paquetes que no caducan, o con una suscripción mensual; el precio por 1.000 baja con el tamaño y está en la página de precios. Cada mes son gratuitas 50 verificaciones de direcciones, 100 registros en deduplicación y 500 operaciones ligeras.

Cada respuesta dice qué ha consumido y de dónde: el campo credit del JSON (counter, charged, free, subscription y packs con las operaciones descontadas y el resto, available, auto_topup con el número de paquetes comprados automáticamente, note) y las cabeceras X-RA-Charged, X-RA-Available y, cuando interviene, X-RA-Auto-Topup. Si las operaciones disponibles no cubren la llamada y la recarga automática del contador no está activa (o falla), la respuesta es 402 payment_required y no se procesa nada.

El cuerpo del 402 incluye también credit.purchase_url: la página Créditos de tu cuenta, con el paquete más pequeño que cubre lo que falta, lista para abrir.

Para saber cuántas operaciones quedan sin consumir ninguna está GET /api/v1/credit. Para cada uno de los tres contadores (contact, dedupe, light) devuelve available, las gratuitas (free) que quedan en el mes y la fecha en que se ponen a cero (el día 1), la suscripción (subscription: resto, tamaño, renovación), los paquetes (packs) activos uno por uno con lo que queda (no caducan) y cuántos has comprado, la recarga automática (auto_topup: activa, tamaño, tope y gasto del mes en euros), el uso (used en el mes, totales, último uso) y sobre todo el state, porque un cero a solas no dice si has agotado el saldo o si ese servicio no lo usas: never_used, free (nunca has comprado, trabajas con las gratuitas del mes), free_used_up, active, awaiting_renewal, used_up (compraste en el pasado y no queda nada: hay que recargar), con un warning. Arriba, needs_topup enumera los contadores en los que intervenir y endpoint dice qué contador consume cada endpoint. Requiere el token de una cuenta.

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

Se paga por elemento verificado, no por llamada: si en un campo hay dos números de teléfono o dos emails, los verificamos todos (hasta tres por fila) y cada uno consume una operación. Una llamada por lotes consume tanto como las operaciones que contiene. Si el crédito se ha agotado y no tienes activa la recarga automática, la API responde HTTP 402 (crédito insuficiente); superado el límite de peticiones responde HTTP 429 con retry_after. Compras un paquete desde el área personal, o activas una suscripción para pagar menos por operación.