Perguntas · Moradas

Existe uma API para normalizar moradas?

O que faz a chamada

O endpoint de verificação de contacto põe a morada na forma postal do seu país, e o nome que a acompanha. Lê rua, número, código postal e cidade em conjunto, não um campo de cada vez, e declara cada correção. O país vai em country_code (ISO 3166-1) ou em country, escrito como calhar.

Um contacto de cada vez no corpo do pedido, ou uma lista no campo items, até quinhentos por chamada. Cada chamada precisa de um token, que gera na sua área pessoal depois de registado, e passa no cabeçalho Authorization: Bearer. O token pode ter uma data de validade, ou ficar válido até o revogar.

Como volta o resultado

A resposta tem duas formas da mesma morada: uma legível com os acentos, a outra na forma postal para imprimir etiquetas, em maiúsculas. Precisa das duas por motivos diferentes: a primeira para mostrar a morada a um operador ou numa interface, a segunda para a impressão propriamente dita.

Com elas vem um resultado em palavras-chave — correto, alterado com o detalhe do que mudou campo a campo, ou a verificar quando a morada não se consegue reconstruir com certeza, com o motivo em claro: rua não encontrada no município, dados insuficientes, número não encontrado. Nada é corrigido em silêncio: se mudamos alguma coisa dizemo-lo, e se não temos a certeza dizemo-lo com a mesma clareza em vez de adivinhar. Onde o registo está em serviço recebe também as coordenadas do número, o código do município e, nas cidades que o têm, o bairro.

Morada única ou trabalhos em bloco

Abaixo dos quinhentos pedidos tem a resposta logo, na mesma chamada: o caso típico de um formulário de registo ou de um checkout, onde a morada deve ser verificada no momento em que o utilizador a escreve. Para listas maiores, até cem mil moradas de uma vez, acrescenta "async": true: o pedido devolve logo um código de trabalho e o processamento entra na fila, a mesma que gere os trabalhos em bloco carregados a partir do site. Volta a ler o resultado com um GET no mesmo endpoint passando o código, em JSON ou, se precisar do ficheiro para descarregar, em CSV.

Autocompletar para os seus formulários

Se está a construir um formulário de morada, /api/v1/suggest dá-lhe o autocompletar enquanto o utilizador escreve: rua, cidade e número propostos à medida, com o campo já verificado na seleção em vez de o ter de controlar depois com uma chamada à parte. Deve usar-se a partir de um servidor seu, que faz de proxy para o endpoint: o token nunca deve aparecer no browser do utilizador final.

Quando faz sentido integrá-la

Faz sentido quando a morada entra na base de dados vezes sem conta, não uma só: um formulário de registo, um checkout de comércio eletrónico, um CRM alimentado por vários canais. Verificá-la aí, no momento em que entra, evita acumular moradas incorretas que depois têm de ser limpas em bloco antes de cada envio. Se em vez disso já tem uma lista para arrumar uma só vez, é mais simples carregá-la como ficheiro Excel ou CSV a partir do site: o mesmo motor, sem escrever uma linha de código.

Erros, limites e documentação completa

Cada resposta tem um código HTTP coerente com o que aconteceu: 401 se o token falta ou não é válido, 413 se o lote excede o limite, 429 se excedeu o número de pedidos por minuto permitido, 402 se o crédito não chega para cobrir a chamada. Uma morada que não se consegue normalizar não é um erro da API: a resposta chega na mesma, com o resultado que explica porquê.

Na página da API encontra todos os endpoints — morada, desduplicação, e-mail, telefone, sítio web, enriquecimento do nome — com os parâmetros, os exemplos curl e os códigos de erro por extenso. Se trabalha com uma ferramenta que importa especificações, há também o openapi.json.

Uma chamada mínima

A resposta completa traz também a forma postal, o detalhe de cada campo alterado, as coordenadas do número de porta e os dados tal como os mandou, para comparação.