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.

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.

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" o llama a www.radaraddress.it sin indicar el idioma.

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

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

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 contacto

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.

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, Chequia, Portugal, Dinamarca, Noruega, Austria, Suiza, Eslovaquia, Croacia, 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.

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

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 (Dott.ssa, Avv., …) y fórmulas de saludo listas para la correspondencia — "Egregio Sig. Rossi", "Gentile Dott.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": "Dott.ssa",
    "formal_salutation": "Gentile Dott.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.

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

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 contacto 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, Chequia, Portugal, Dinamarca, Noruega, Austria, Suiza, Eslovaquia, Croacia, 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 cuesta 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 … ]}'

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

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

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.

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

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 contacto (/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 contacto, 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.

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 paga su precio. 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.