Consulta de CEP com PyCEPCorreios

Meus Projetos
, ,

Boa tarde, pessoal. Tudo certo?

Atualização do post antigo. Neste post irei falar um pouco sobre a nova versão da PyCEP Correios.

O PyCEPCorreios é uma api desenvolvida em Python que realiza a busca dos dados de um dado CEP diretamente no webservice dos Correios, sendo essa a principal diferença em relação a outras api’s de consulta de CEP. O retorno dessa consulta é um dict contendo os dados do endereço pertencente ao CEP. Este projeto foi iniciado por mim para fins de estudo, porém ele pode ser utilizado normalmente em projetos mais sérios.

UPDATE: A versão 2.0.0 trouxe melhorias consideráveis no código com o objetivo de tornar a API mais
fácil de ser utilizada. Porém, ela é incompatível com as versões anteriores. Houve
grandes melhorias na documentação, código e testes da API. Sendo assim,
decidi republicar esse post com novas informações sobre a lib.

UPDATE: A versão 2.1.0 trouxe suporte para python 2.7+

Instalação

O PyCEP Correios pode ser facilmente instalado com o comando a seguir:

1
pip install pycep-correios

UPDATE: Atualmente, a PyCEPCorreios possui suporte para Python 2.7+ e 3.3+.

Como usar

Consultar o endereço de um CEP é muito simples com a PyCEPCorreios. Não importa se o CEP fornecido possui hífen ou ponto. A PyCEPCorreios trata a entrada garantindo uma entrada válida para o webservice dos Correios.

Veja os exemplos a seguir:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
>>> import pycep_correios

>>> endereco = pycep_correios.consultar_cep('37503130')
>>> print(endereco)
{
    'bairro': 'Santo Antônio',
    'cep': '37503130',
    'cidade': 'Itajubá',
    'end': 'Rua Geraldino Campista',
    'id': '0',
    'uf': 'MG',
    'complemento': '',
    'complemento2': '- até 214/215',
}

Um exemplo alternativo, enviamos um CEP incorreto, com a quantidade de dígitos inferior a 8.

1
2
3
4
5
6
7
8
from pycep_correios
from pycep_correios.excecao import CEPInvalido

try:
    endereco = pycep_correios.consultar_cep('00000000')
except CEPInvalido as exc:
    print(exc)

Para outras exceções devemos utilizar as exceções da biblioteca requests, no qual a
PyCEPCorreios faz uso para comunicação com o webservice. As antigas exceções da biblioteca também foram removidas a fim de evitar redundância com as exceções da requests e toda a API agora possui comandos e documentação em postuguês.

A PyCEPCorreios também possui funções para validar e formatar números de CEP. Para mais exemplos, veja a documentação aqui. Abaixo, segue alguns links úteis.

Se deseja contribuir, por favor dê uma olhada na documentação aqui. Contribuições são sempre bem-vindas.

Conclusão

É isso pessoal. Este post foi feito simplesmente para apresentação da PyCEP Correios e mostrar exemplos
de utilização da versão 2.0.0 da API. Espero que o módulo seja útil a vocês. Se alguém possuir alguma crítica ou sugestão sinta-se livre para comentar.

Obrigado por ler até aqui! Até o próximo post.