O mesmo motor,
dentro da sua aplicação.

Um endpoint por serviço, com o mesmo nome que o serviço tem neste site: /contact, /dedupe, /email, /phone, /website, /tax-code, /enrichment. Cada um aceita um elemento no corpo do pedido ou uma lista em items, até 500 por chamada (100 para os sites, que têm de ser contactados um a um). A desduplicação é a exceção e quer sempre uma lista: compara as fichas entre si. À parte ficam /suggest, o preenchimento automático para formulários (trabalha por sessão enquanto o utilizador escreve, não em lotes), e /credit, que diz quantas operações restam e em que estado está cada contador, sem consumir nenhuma.

Autenticação

O host da API é www.radaraddress.com. Os nomes dos campos, dos endpoints e dos valores são identificadores em inglês, iguais em todas as línguas; as etiquetas, os motivos e as mensagens seguem a língua do pedido ("language": "de" ou ?language=de, ou o cabeçalho Accept-Language, ou a língua da conta). O cabeçalho Content-Language diz em que língua chegou a resposta.

Opcional: se chamar a API a partir de um formulário, pode indicar onde está com dois cabeçalhos, X-RadarAddress-Form-Page (o endereço da página do formulário) e X-RadarAddress-Form (que formulário e em que ponto, por exemplo checkout/billing). Assim cada operação pode ser associada ao formulário de onde veio. Da página guardamos apenas o domínio e o caminho, sem a parte depois do ponto de interrogação.

O acesso à API faz-se por token Bearer. A conta é gratuita: cria o token na área pessoal e inclui-o no cabeçalho de cada pedido neste formato:

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

Ao criá-lo pode dar ao token uma validade facultativa: passada essa data os pedidos recebem HTTP 401 com o código token_expired; sem validade o token vale até o revogar. Pode revogá-lo ou regenerá-lo a qualquer momento na sua área pessoal, onde vê também a última utilização e o número de pedidos servidos. Um pedido sem token ou com token inválido devolve HTTP 401.

Cada método HTTP faz o que o nome diz: GET lê e não consome operações (/credit, /countries, a releitura de um trabalho), POST processa, DELETE elimina um trabalho. Um método que o endpoint não aceita recebe HTTP 405 com o cabeçalho Allow, que enumera os corretos.

Os nomes italianos, para quem já os usa

A API tem uma única versão, em inglês. Quem integrou com os nomes italianos não precisa de mudar nada: os campos italianos são aceites em qualquer pedido, os endpoints respondem também com o nome italiano (/contatto, /deduplica, /codicefiscale, /arricchimento, /telefono, /sito, /suggerisci, /nazioni, /credito), e a resposta sai com as chaves e os códigos italianos para quem o pede com "language": "it".

A tabela completa dos 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

Também os valores das opções têm nome italiano: format nazionale/internazionale, action genera/valida/estrai/confronta/seleziona, foreign dichiarati/rileva, min_level certo/probabile/ambiguo; com "language": "it" saem assim também level, confidence, state, os códigos de outcome e os cabeçalhos dos ficheiros. Na entrada aceitam-se também sinónimos comuns (zip, surname, phone_number, date_of_birth…) e os mesmos cabeçalhos nos ficheiros dos trabalhos por lotes.

Endpoint de verificação de moradas

Arruma o contacto inteiro: a morada segundo a norma postal do seu país — em Itália e nos países com registo em serviço, a rua e o número de porta são verificados no registo nacional de moradas; nos outros a morada sai na forma postal do país —, o nome e — se o pedido o trouxer — o código fiscal italiano, que é limpo, completado se só faltar o carácter de controlo e confrontado com apelido, nome, sexo e data de nascimento. Um contacto de cada vez, ou até 500 em items: o esquema é o mesmo de todos os outros endpoints.

No mesmo registo pode passar email, phone e website: verificamo-los na mesma operação, juntamente com o nome e o tax_code. A resposta inclui email_outcome, phone_outcome, website_outcome e enrichment (sexo, título, fórmula de saudação). Os seus resultados não entram em outcome, que continua a ser o da morada e do código fiscal. Numa lista, os sites são contactados até 100 por chamada: nos restantes verifica-se apenas a forma.

Dois interruptores, ligados se não os enviares: network:false não contacta os sites e dns:false não verifica se o domínio dos emails recebe correio. Assim fica apenas o controlo da forma e é mais rápido. Valem para toda a chamada, também com async, e são os mesmos de /website e /email.

O país indica-se com country_code (ISO 3166-1: IT, DE, FR…) ou com country, escrito como calhar: «Germania», «Germany», «Deutschland», «República Federal da Alemanha», «UK», «Holanda». Se faltar, presume-se Itália. Nos países com registo em serviço — hoje França, Alemanha, Espanha, Países Baixos, Bélgica, Finlândia, Suíça, Chéquia, Portugal, Dinamarca, Noruega, Áustria, Eslováquia, Croácia, Grécia, Roménia, Hungria, Eslovénia, Irlanda, Islândia, Luxemburgo, Liechtenstein, San Marino, Mónaco, Andorra, Cidade do Vaticano, a lista atualizada está em Países — a rua e o número de porta são verificados no registo nacional de moradas como em Itália: código postal confirmado ou completado, coordenadas do número em geo, bairro ou arrondissement em district onde a cidade os tem (Hamburg-Altstadt, Paris 4e Arrondissement), código do município em territory.municipality_code. Em italiano o resultado traz FOREIGN seguido das alterações, nas outras línguas apenas as alterações; se a rua existe e o número não, HOUSE_NUMBER_NOT_FOUND. Nos outros países trabalhamos sobre a forma, e a mensagem di-lo: código postal no formato do país, abreviaturas da rua por extenso, maiúsculas e nome da cidade como os escrevem os correios desse país (Hauptstr. 5, Munique → Hauptstraße 5, MÜNCHEN), com a linha do país. Em ambos os casos volta address_key, a forma com que a desduplicação reconhece a mesma rua escrita de duas maneiras. Com "foreign": "detect" um registo sem país que não se encontra em Itália é reconhecido como estrangeiro quando o texto o diz claramente; o valor por omissão declared deixa estrangeiro só o que o declara. O catálogo completo dos países, com nome curto e oficial, em inglês e na língua do país, está disponível com GET /api/v1/countries e consulta-se com ?q=Germania, ?q=Deutschland ou ?q=DE.

Num lote de um só país não é preciso repetir o país em cada elemento: default_country ("DE", "Germany") vale para os elementos que não o indicam, na verificação de moradas, na desduplicação, no enriquecimento (escolhe o dicionário de nomes próprios) e na verificação de telefone, também nos trabalhos assíncronos. O país escrito no elemento prevalece sempre; sem nenhum dos dois, o elemento é 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 o lote, os mesmos campos dentro de items; a resposta é { count, results: [ { id, result } ] } pela mesma ordem do envio.

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

O mesmo endpoint para uma morada de outro país: basta country_code. Aqui Hamburgo, verificada no registo alemão, com o bairro e as coordenadas do número de porta.

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

Opções válidas para toda a chamada: postal_form (força também normalized na forma postal), preserve_original (mantém o nome tal como o utilizador o escreveu e expõe o canónico à parte), precision 1–5 (predefinição 3; acima de 3 a correspondência é aproximada e a fiabilidade não será high).

Os níveis de precision: cada um faz também o que fazem os anteriores.

• 1 Rigorosa: A localidade tal como está escrita; na rua, só as correções que os dados confirmam sem dúvidas.
• 2 Apertada: Além disso, corrige códigos postais e províncias errados e reconhece as localidades abreviadas.
• 3 Normal (predefinida): Além disso, encontra os nomes escritos pela metade e leva a morada para o concelho onde a rua existe de facto.
• 4 Ampla: Além disso, aceita os nomes que soam igual e, entre ruas com o mesmo nome, escolhe a mais conhecida. A fiabilidade nunca é alta.
• 5 Máxima: Tudo o que se consegue encontrar. A fiabilidade nunca é alta.

Juntamente com a morada vem city_type, que diz se o ponto de entrega está numa capital de província ou num município da província — a diferença que interessa a quem segmenta uma campanha por cidade. provincial_capital é true, false ou null quando não temos elementos para o dizer — e nesse caso não adivinhamos.

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

Ao lado do código postal vem postcode_check: de onde vem (source) e com que precisão (precision: house_number o próprio número, interpolated os números vizinhos da mesma rua, street a maioria da rua, locality, municipality), quantos números de porta o dizem (house_numbers) e com que acordo (agreement, de 0 a 1). Sem confirmação para esse número, o resultado traz POSTCODE_UNCONFIRMED e confirmed é false: o código postal fica o indicado, se for um dos da cidade, e deve ser verificado.

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

Voltam também as coordenadas em geo (latitude e longitude WGS84) e os identificadores territoriais em territory: em Itália o código ISTAT e o código cadastral do município, o CAB e o identificador nacional da rua; nos outros países country e o código do município no registo nacional (municipality_code). O campo precision diz a que nível chegámos: house_number quando o número de porta está georreferenciado, interpolated quando falta o número exato e o ponto é estimado, street quando temos o ponto da rua, municipality quando só temos o centro do município. source diz de onde vem o ponto: anncsu é o registo nacional italiano, inspire o registo nacional do país, osm o OpenStreetMap: nesse caso os dados são © OpenStreetMap contributors, licença ODbL, e a atribuição deve ser reproduzida se os publicar. Onde o registo de um país impõe uma atribuição, ela sai na mensagem. No CSV dos trabalhos em bloco são as colunas latitude, longitude, geo_precision, istat_code e 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" } }

O andar, a escada e a fração escritos no endereço voltam também como dado próprio em sub_address: uma lista de pares type e value, lidos segundo as regras postais do país (na Alemanha depois de «//», em França numa linha própria, em Portugal «3º Esq»). Os tipos são unit (fração), staircase (escada), floor (andar), block, building, building_number e block_number. A linha do endereço fica na forma do país. O que não reconhecemos fica como estava escrito e não entra na lista: não o adivinhamos. Quando a unidade indicada consta nesse número de polícia, sub_address_confirmed é true; caso contrário é null, nunca false: não a encontrar não quer dizer que esteja errada.

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

Endpoint de desduplicação

Reconhece os registos que se referem à mesma pessoa na mesma morada mesmo quando estão escritos de forma diferente: diminutivos e equivalências de nomes (Dany ≈ Daniela), apelido e nome próprio trocados, abreviaturas («V. Roma» ≈ «Via Roma»), gralhas. A comparação das moradas passa pelo motor de normalização: duas grafias diferentes da mesma rua colapsam na forma canónica antes da comparação. No máximo 500 contactos por chamada (fichas + referência); para listas maiores use o trabalho em lote a partir da área pessoal.

Agendas de contactos. Um contacto da agenda (Contactos da Apple, Google, Outlook: o modelo vCard) tem várias moradas, vários telefones e vários emails, cada um com uma etiqueta. O endpoint aceita-os assim, sem limite: addresses é uma lista de objetos com type e os campos habituais; phones e emails são listas em que cada elemento é só o dado ("340 7491386") ou {"type": "work", "value": "02 66710423"}, também misturados; os campos planos habituais continuam válidos e valem como primeira morada e primeiro contacto. Dois contactos são a mesma pessoa se qualquer par das suas moradas coincidir (o escritório de um com a única morada do outro), ou se tiverem o mesmo nome e um telefone ou um email em comum, em qualquer posição e com qualquer etiqueta. O tipo não pesa na correspondência: volta como chegou, mais type_normalized no vocabulário vCard (home, work, cell…), para que a aplicação saiba onde reescrever. Um contacto é uma operação, sejam quantas forem as moradas e os contactos que tenha.

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

A resposta agrupa os duplicados em groups: cada grupo enumera os id dos seus members, indica qual manter (main_record) e propõe o record consolidado: o melhor nome e a união de moradas e contactos (addresses, phones, emails), cada um com o tipo, com provenance (de que contactos vem) e desduplicado: a mesma rua em duas grafias é uma só morada, o mesmo número com duas etiquetas um só número. Os contactos sem correspondências estão em singles, como objetos {id, outcome}: com outcome INTERNAL_DUPLICATE o contacto não tem duplicados com outros, mas tem-nos dentro de si (morada escrita duas vezes, número repetido), e traz o seu record fundido. Reconhece a mesma rua escrita de maneiras diferentes («V. Leopardi 4» ≈ «Via Giacomo Leopardi 4»), o código postal corrigido automaticamente e apelido e nome próprio trocados.

Endpoint do código fiscal italiano

Três ações sobre o código fiscal italiano das pessoas singulares: generate a partir dos dados pessoais, validate um código existente (formato, carácter de controlo e omocodia), extract a informação que contém — data de nascimento, idade, sexo, município ou país estrangeiro de nascimento. Além disso, compare verifica que um código corresponde aos dados pessoais declarados. Cobre os códigos cadastrais de todos os municípios italianos e dos países estrangeiros. Apelido e nome próprio devem ser passados em caracteres latinos: para quem tem um nome noutro alfabeto, o código calcula-se sobre a transliteração que consta do documento, que não é única (Dmitrij/Dmitry); um nome não latino devolve cognome_non_latino ou nome_non_latino, e no compare uma diferença no nome de quem nasceu no estrangeiro traz uma nota sobre a possível transliteração diferente.

As primeiras 500 operações ligeiras por mês são gratuitas (código fiscal incluído), e a quota gratuita é uma só em todas as formas de utilização: o que faz aqui, no site e nos ficheiros em lote conta para o mesmo limite. Para além dele, as operações ligeiras pagam-se ao seu preço (ver preços).

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 os volumes: { "action": "validate", "items": [ … ] } processa até 500 elementos por chamada, cada um com o seu id de correlação. A extração assinala com ambiguous_year os casos em que os dois algarismos do ano não distinguem o século (1926 vs 2026).

Cada resposta traz outcome, reason, notes e comments na língua do pedido: GENERATED para generate, vazio para um código válido em validate, MATCH ou MISMATCH para compare (com differences: os campos que não batem certo). Quando o código não passa nos controlos, o resultado é um dos códigos TAX_CODE_* listados abaixo e error dá a forma curta (check_digit, length, format, homocode, month, date, place, empty); em generate diz que dado falta ou não se resolve (last_name, first_name, gender, birth_date, birth_place, ambiguous_place com options, last_name_non_latin). suggestion traz o código correto quando o controlo o sabe reconstruir.

Endpoint de enriquecimento

Enriquece um nome: sexo deduzido do nome próprio, tipo de sujeito (pessoa singular ou coletiva), título normalizado (Dr.ssa, Avv., …) e fórmulas de saudação prontas para a correspondência — «Egregio Sig. Rossi», «Gentile Dr.ssa Bianchi», «Spett.le» para as empresas, «Gentile Famiglia» para os agregados, «Caro/Cara» para o registo informal. Reconhece também a forma de casada no apelido («Rossi in Verdi» → mulher, com o detalhe dos dois apelidos). O campo gender aceita também as formas escritas («maschio», «donna», «Sig.ra», «male»); X indica uma entidade e G uma família ou um casal. Se o título faltar, deduzimo-lo de profession (a profissão) ou de education, quando indicam um. Os dicionários são 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": [ … ] }, até 500 por chamada. O resultado é ENRICHED (sexo e saudações definidos), LEGAL_PERSON (empresa ou entidade: tratada como razão social) ou PARTIAL (falta o nome, ou o sexo não se deduz): reason diz porquê, comments o que acrescentar para completar.

Endpoint de verificação de email

Verifica um endereço de email: sintaxe, existência do domínio (registos MX/A), gralhas nos domínios comuns com correção proposta (gmial.com → gmail.com), domínios descartáveis, endereços genéricos (info@, contabilidade@: não são de uma pessoa). Não fazemos a verificação SMTP da caixa de correio individual, prática invasiva e pouco fiável. Lote items até 500; "dns": false salta a consulta do domínio.

Uma gralha certa corrige-se de imediato: quando o endereço tal como está escrito nem sequer é um endereço (nome@dominio,pt com vírgula) ou quando a correção cai num fornecedor conhecido (gmai.com → gmail.com, também a uma letra de distância se o domínio escrito não recebe correio), email sai corrigido, corrected_from traz como estava escrito e o resultado é MODIFIED EMAIL_DOMAIN. Uma gralha possível num domínio qualquer (rossi.con) fica como proposta: EMAIL_TYPO com a correção em suggestion, e as verificações (domain_exists, domain_checked) feitas sobre ela; o endereço tal como está escrito não é verificado.

Um domínio a uma tecla de distância de um fornecedor conhecido é corrigido conforme a precision (1-5, padrão 3; 4 e 5 valem como 3). Com 1 só se o domínio escrito não existir (gmail.cob, hotmial.ocm); com 2 também se existir mas não receber correio (libreo.it); com 3 também se receber e-mail: domínios estacionados, organizações reais (libera.it, lice.it) e grafias «de ouvido» (gemail.com, jmail.com). Um sufixo errado num domínio qualquer (studiorossi.con) é corrigido se o domínio certo receber e-mail. Abaixo do nível do erro, devolvido em typo_level, o endereço fica como foi escrito e similar_to traz o endereço que talvez se pretendia, com uma nota. Com "fix_typos": false, para toda a chamada ou para um só elemento, nenhum erro é corrigido: o endereço fica como foi escrito e a correção sai em similar_to. Serve quando a pessoa confirmou que quer mesmo aquele endereço.

Endpoint de verificação de telefone

Verifica um número sem telefonar a ninguém: forma, classe e tipo, comprimento segundo o plano de numeração, área do fixo e operador a quem o bloco foi atribuído na origem. A class é a leitura de que precisa para trabalhar uma lista: mobile (pode enviar-lhe um SMS), landline (liga em horário de expediente), special (não é o contacto de uma pessoa: emergências, utilidade pública, números verdes e de tarifa majorada), foreign para os números com indicativo internacional. Quando reconhecemos também o serviço preciso, type di-lo (número verde, tarifa especial, custo partilhado, utilidade pública). O indicativo italiano escrito sem o + (39347…, gralha clássica das exportações) é retirado quando os algarismos não deixam dúvidas — 3934567890 continua a ser o telemóvel que é. Se no mesmo campo há vários números («347… - 338…») separamo-los: voltam como phone, phone2, phone3, e phone nunca fica vazio quando existe pelo menos um número. Com "format": "international" o número italiano sai na forma +39…; a predefinição national deixa-o nu e põe o indicativo só nos estrangeiros. Para os estrangeiros volta também e164, o país do indicativo em country_code, e o zero de rede depois do indicativo é retirado («+44 (0)20…» e «+44 20…» dão o mesmo número). Com country_code (ou country) na chamada ou no elemento, um número escrito sem indicativo é lido como número nacional desse país: «020 7946 0958» numa ficha do Reino Unido é Londres, não Milão. Sem país continua italiano. Lote items até 500.

Um número do país do registo não é «estrangeiro»: onde conhecemos o plano de numeração recebe a sua class (mobile, landline, special), com format national fica sem indicativo na forma do seu país (zero de rede incluído) e devolve-se também national_number ao lado de e164. PHONE_FOREIGN e class foreign ficam para os números de um país diferente do do registo.

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 verificação de site

Verifica que o endereço está bem escrito e que o site responde de facto: existência do domínio, pedido HTTP com os redirecionamentos seguidos, código final, validade do certificado. Nenhum juízo sobre o conteúdo. Também aqui vários endereços no mesmo campo voltam como website, website2, website3. Com "network": false verificamos só a forma, sem contactar o site. Lote items até 100: cada verificação abre uma ligação, por isso o lote é mais pequeno do que nos outros 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 preenchimento automático de moradas

Parte do zero? O widget ra-suggerisci.js e um pequeno proxy no seu servidor são suficientes: o token nunca chega ao navegador.

Sugestões enquanto o utilizador escreve uma morada no seu formulário: todo o registo de arruamentos italiano, com o nome completado («via verdi» → «Via Giuseppe Verdi»), município e província; o código postal chega com a seleção, nas grandes cidades com zonas postais o certo do número de porta. Funciona por sessão: o cliente gera um UUID para cada morada em preenchimento, as consultas de sugestão são gratuitas, e paga-se uma verificação de morada quando o utilizador seleciona e os campos se preenchem (ação select, que devolve o registo já normalizado pelo motor). Os campos já preenchidos no formulário — mesmo em parte — viajam como contexto e apertam as sugestões.

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

Escolhida a rua, completa-se o número de porta: passando street_id com o número parcial obtêm-se os números existentes dessa rua, com exists verdadeiro/falso para validar o que foi escrito — e a seleção pode repetir-se com o número de porta sem novo débito: o débito é por sessão e por rua, não por clique; outra rua na mesma sessão é outro débito. Os números de porta completam-se apenas na sessão que selecionou essa rua. Nas cidades com zonas postais é o número de porta que determina o código postal exato.

O token da API nunca vai para o browser: o widget pronto a usar (ra-suggerisci.js) chama um pequeno proxy no seu servidor, que acrescenta o token e reencaminha. Cada sessão admite até 30 chamadas e vale 10 minutos; as sessões sem seleção são gratuitas até 200 por dia por token, mais cinco por cada seleção. Widget, proxy pronto e formulário de exemplo estão no kit de O teu formulário.

Funciona em cada país em serviço (hoje França, Alemanha, Espanha, Países Baixos, Bélgica, Finlândia, Suíça, Chéquia, Portugal, Dinamarca, Noruega, Áustria, Eslováquia, Croácia, Grécia, Roménia, Hungria, Eslovénia, Irlanda, Islândia, Luxemburgo, Liechtenstein, San Marino, Mónaco, Andorra, Cidade do Vaticano; a lista atualizada está em Países): com country_code ou country as sugestões vêm do registo desse país, e o texto escreve-se como se escreve lá — rua, número, código postal e cidade até num só campo: «kalverstraat 92 amst», «92 rue de rivoli paris», nos Países Baixos «1012PH 92». Cada resposta traz parsed, ou seja, como o servidor leu a rua (street), o número (house_number) e o código postal (postcode): o teu formulário sabe onde fica o número sem conhecer as regras do país. As sugestões trazem rua, cidade, localidade quando existe, e source (registry, ou osm onde o registo nacional não publica); o código postal e os números de porta nunca estão nas sugestões: chegam com a seleção, que passa pelo motor e devolve o mesmo registo de /contact (postcode confirmado pelo registo, geo ao número). Com a seleção também podes passar postcode, o escrito no formulário. attribution é a menção da fonte a mostrar ao lado das sugestões: a licença do registo exige-o. Se o país faltar presume-se IT; para um país fora de serviço a resposta continua a ser HTTP 200 com supported:false e hints:[], sem criar a sessão nem cobrar nada. Uma sessão é de um país: se mudar, o cliente gera um novo UUID (senão 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"}

Grandes volumes: o trabalho assíncrono

As chamadas normais respondem de imediato, e por isso têm um limite de elementos — um pedido HTTP que dura minutos não serve a ninguém. Os limites seguem o peso da operação:

Acima desses números não é preciso partir a lista à mão: acrescenta-se "async": true e a chamada volta de imediato com um código, enquanto o processamento entra na mesma fila do carregamento de ficheiros. Até 100 000 elementos por chamada, e em Os meus trabalhos aparece um só.

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

Depois relê-se quando for preciso, e o resultado chega em JSON ou 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

Com format=zip descarrega em vez disso todos os ficheiros do trabalho num zip: o ficheiro limpo, com as suas colunas e as correções já escritas onde estão confirmadas; as linhas a verificar; o que muda, célula a célula; o resultado completo; um README que os explica. Com format=zip_xlsx os mesmos ficheiros estão em Excel.

Abaixo das 5 000 linhas o resultado volta também em results dentro do JSON; acima, descarrega-se em CSV. O débito acontece quando o trabalho é colocado em fila, e a parte não processada volta ao saldo se o trabalho parar. O token tem de estar ligado a uma conta: o trabalho fica na sua fila.

A chamada que põe o trabalho em fila responde HTTP 202 com o cabeçalho Location, que aponta para o trabalho. Quando já não precisas do resultado, eliminas com DELETE no mesmo endereço: a resposta é HTTP 204, e os ficheiros e os dados deixam de existir. Um trabalho ainda em fila ou em processamento responde 409 job_running: elimina-o quando tiver terminado. Se não o eliminares, o trabalho é eliminado automaticamente ao fim de 30 dias. O mesmo vale para o 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 resposta inclui o campo outcome: uma lista de palavras-chave, vazia quando não há nada a assinalar. O esquema é sempre <conditions> [MODIFIED <types>] — as condições à frente, as alterações no fim — e vale para todos os serviços. Ao lado encontra outcome_label (ou kind) com ok, modified, warning, error, e reason com a explicação numa linha. Os códigos são identificadores: comparam-se, não se traduzem; com "language": "it" saem os códigos italianos (LOCALITA_NON_TROVATA MODIFICATO CAP INDIRIZZO), os mesmos palavra por palavra.

Morada (verificação de moradas)

Código fiscal italiano

No endpoint /tax-code os mesmos controlos têm códigos próprios — 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 aí o código fiscal é o objeto da verificação, não um campo do registo.

Enriquecimento

Email

Telefone

Site

Quanto consome cada chamada

Cada chamada consome operações do contador do serviço: verificação de moradas (/contact, /suggest na seleção), desduplicação (/dedupe) e operações ligeiras (/email, /phone, /website, /enrichment, /tax-code para além da quota gratuita). As operações compram-se em pacotes que ficam, ou com uma subscrição mensal; o preço por 1 000 desce com o tamanho e está na página de preços. Todos os meses são gratuitas 50 verificações de moradas, 100 fichas em desduplicação e 500 operações ligeiras.

Cada resposta diz o que consumiu e de onde: o campo credit do JSON (counter, charged, free, subscription e packs com as operações retiradas e o remanescente, available, auto_topup com o número de pacotes comprados automaticamente, note) e os cabeçalhos X-RA-Charged, X-RA-Available e, quando intervém, X-RA-Auto-Topup. Se as operações disponíveis não cobrirem a chamada e a recarga automática do contador não estiver ativa (ou falhar), a resposta é 402 payment_required e nada é processado.

O corpo da resposta 402 inclui também credit.purchase_url: a página Créditos da conta, com o pacote mais pequeno que cobre o que falta, pronta a abrir.

Para saber quantas operações restam sem consumir nenhuma há GET /api/v1/credit. Para cada um dos três contadores (contact, dedupe, light) devolve available, as gratuitas (free) que restam no mês e a data em que se repõem a zero (dia 1), a subscrição (subscription: remanescente, tamanho, renovação), os pacotes ativos (packs) um a um com o que resta (não expiram) e quantos comprou, a recarga automática (auto_topup: ativa, tamanho, limite e gasto do mês em euros), a utilização (used no mês, totais, última utilização) e sobretudo o state, porque um zero sozinho não diz se esgotou ou se não usa esse serviço: never_used, free (nunca comprou, trabalha nas gratuitas do mês), free_used_up, active, awaiting_renewal, used_up (comprou no passado e não resta nada: é preciso recarregar), com um warning. No topo, needs_topup enumera os contadores em que é preciso intervir e endpoint diz que contador consome cada endpoint. Exige o token de uma conta.

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

Paga-se por elemento verificado, não por chamada: se num campo há dois números de telefone ou dois emails, verificamo-los todos (até três por linha) e cada um consome uma operação. Uma chamada em lote consome tanto quanto as operações que contém. Se o crédito estiver esgotado e não tiver a recarga automática ativa, a API responde HTTP 402 (crédito insuficiente); ultrapassado o limite de pedidos responde HTTP 429 com retry_after. Compra um pacote na área pessoal, ou ativa uma subscrição para pagar menos por operação.