Consulta de CEP e Preenchimento Automático de Endereço em Python via API ViaCEP

A integração de serviços de geolocalização e consulta de endereços é uma funcionalidade indispensável em formulários de cadastro, sistemas de e-commerce e rotinas de logística. O preenchimento automático de campos de endereço a partir do Código de Endereçamento Postal (CEP) reduz a taxa de erro de digitação por parte do usuário e otimiza o fluxo de captura de dados. No ecossistema Python, essa tarefa pode ser realizada de forma direta e eficiente utilizando bibliotecas padrão e de comunicação HTTP para consumir serviços Web gratuitos, como a API do ViaCEP.

1. Arquitetura da API ViaCEP e Estrutura da Resposta

A API do ViaCEP é um web service gratuito voltado para a consulta de CEPs do território brasileiro. A comunicação com o serviço é feita via requisições HTTP GET enviadas a uma URL padronizada que encadeia o CEP pesquisado ao formato de resposta desejado.

O formato do endpoint adotado pelo serviço estrutura a requisição no caminho viacep.com.br/ws/{cep}/json/, onde o parâmetro de busca é inserido diretamente na URL. Quando uma consulta é bem-sucedida, a API retorna um objeto JSON que é traduzido em um dicionário de dados contendo os atributos do endereço correspondente.

A tabela abaixo descreve as principais chaves retornadas pelo serviço ViaCEP e seu mapeamento para os campos de endereço tradicionais:

2. Implementação Prática com requests e json

Para realizar a integração do serviço ViaCEP em um script Python, utiliza-se a biblioteca requests para gerenciar a conexão HTTP e o módulo json para realizar a conversão do conteúdo bruto recebido no formato de dicionário Python.

Conforme demonstrado nos guias de integração de CEP em Python, a função é estruturada capturando a entrada do usuário, montando a URL de consulta dinâmica e extraindo o conteúdo da resposta HTTP. A leitura do fluxo de dados é realizada acessando o atributo .content da requisição e convertendo a sequência binária ou textual com a função json.loads().

O código a seguir apresenta a implementação funcional para buscar e exibir os dados de endereço no terminal:

import requests
import json

def busca_cep():
    try:
        cep = input('Digite o cep: ')
        domain = 'viacep.com.br'
        url = requests.get(f'https://{domain}/ws/{cep}/json/').content
        dic = json.loads(url)

        print(f'Logradouro: {dic["logradouro"]}')
        print(f'Bairro: {dic["bairro"]}')
        print(f'Cidade: {dic["localidade"]}')
        print(f'UF: {dic["uf"]}')
    except:
        print('Verifique se o cep foi digitado corretamente e tente novamente')

if __name__ == '__main__':
    busca_cep()

3. Fluxo de Execução e Tratamento de Exceções

A estabilidade da integração com webservices externos depende do tratamento adequado de falhas. Em sistemas de produção ou scripts interativos, a entrada do usuário pode conter caracteres inválidos, formatações fora do padrão ou CEPs inexistentes na base dos Correios.

Como estabelecido no modelo de consulta, o uso do bloco try/except garante que caso haja falha no transporte HTTP, na decodificação do objeto JSON ou no acesso às chaves do dicionário, o programa não interrompa sua execução de forma abrupta com um rastreamento de pilha (traceback). Em vez disso, o fluxo desvia para o bloco except, exibindo uma mensagem orientativa para que o usuário verifique o código digitado e repita a operação.

1. Captura da Entrada: O programa solicita a digitação do CEP por meio da função input().
2. Requisição HTTP: A biblioteca requests dispara uma requisição GET para o endpoint da API viacep.com.br/ws/{cep}/json/.
3. Conversão JSON: O conteúdo bruto retornado em .content é processado por json.loads(), gerando um dicionário nativo.
4. Exibição dos Dados: Os atributos logradouro, bairro, localidade e uf são acessados via chave de dicionário e formatados na saída do terminal.
5. Captura de Erro: Caso ocorra alguma inconsistência na entrada ou na resposta da rede, a mensagem de exceção do bloco except é exibida de maneira amigável.