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.

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.

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" ou chama www.radaraddress.it sem indicar a língua.

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

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 contacto

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.

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, Chéquia, Portugal, Dinamarca, Noruega, Áustria, Suíça, Eslováquia, Croá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.

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

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 (Dott.ssa, Avv., …) e fórmulas de saudação prontas para a correspondência — «Egregio Sig. Rossi», «Gentile Dott.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": "Dott.ssa",
    "formal_salutation": "Gentile Dott.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.

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

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 contacto 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, Chéquia, Portugal, Dinamarca, Noruega, Áustria, Suíça, Eslováquia, Croá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 custo 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 … ]}'

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

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

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.

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

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

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 paga o seu preç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.