mstuttgart / brazilcep

:brazil: Minimalist and easy-to-use python library designed to query CEP (Postal Address Code) data.

BrazilCEP

About | Install | How to Use | Documentation | Contribute | Credits

About

BrazilCEP is a minimalist and easy-to-use python library designed to query CEP (Postal Address Code) data.

Its objective is to provide a common query interface to all these search services, facilitating the integration of Python applications with these services.

Currently supports several CEP API's:

• ViaCEP
• ApiCEP (WideNet)

Note

BrazilCEP is the new name of former PyCEPCorreio python library. If you want to migrate the old code to the new version, please see the migrate section in docs.

Tip

CEP or Código de Endereçamento Postal (Postal Address Code), as it is also known, is a system of numeric codes, created, maintained and organized by Correios do Brazil for organizing addresses and deliveries of letters and parcels.

Install

The recommended way to get BrazilCEP is to install the latest stable release via pip:

pip install brazilcep

Important

We currently support Python 3.8+ only. Users on older interpreter versions are urged to upgrade.

How to Use

Making a request is very simple. Begin by importing the BrazilCEP module:

>>> import brazilcep

Now, call the get_address_from_cep to query any CEP:

>>> address = brazilcep.get_address_from_cep('37503-130')

Now, we have a dict object called address. We can get all the address information we need from this object:

 >>> address
{
    'district': 'rua abc',
    'cep': '37503130',
    'city': 'city ABC',
    'street': 'str',
    'uf': 'str',
    'complement': 'str',
}

The CEP always must be a string.

Tip

BrazilCEP was developed to integrate on-demand queries into web pages. Querying CEP in bulk through scripts or any other means is not recommended.

Important

BrazilCEP is not responsible for the functioning, availability and support of any of these query API's. All of them are provided by third parties, and this library just provides a handy way to centralize the CEP search on these services.

Documentation

Documentation for the current version of BrazilCEP is available from the official docs here.

Contribute

See this guideline here.

Credits

Copyright (C) 2016-2024 by Michell Stuttgart

brazilcep's Issues

Novas funcionalidade e melhorias

Adição das seguintes funcionalidades

• Testes usando template jinja para simular envio e retorno
• Adicionar funcionalidade de verificar se a estrutura do CEP é valida.

Corrigir mock para apenas comportamentos de exceção

Corrigir mock para apenas comportamentos de exceção como Timout, InternetError e etc. Para consulta de CEP correto deve-se utilizar a comunicação com o servidor de homologação.

Adicionar logging para as funcionalidades principais

Adicionar logging para as funcionalidades (pelo menos as principais):

• consultar_cep
• validar_cep
• formatar_cep

exceptions.BlockedByFlood()

Boa tarde, tudo bem?

Estou tentando utilizar essa API para pegar um serie de informações sobre alguns CEPs que tenho, porém, estou encontrando esse problema:

---

BlockedByFlood Traceback (most recent call last)
in
----> 1 endereco = pycep_correios.get_address_from_cep(cep)
2 endereco

~\AppData\Roaming\Python\Python37\site-packages\pycep_correios\client.py in get_address_from_cep(cep, webservice)
38
39 if webservice == WebService.APICEP:
---> 40 return apicep.fetch_address(cep)
41
42

~\AppData\Roaming\Python\Python37\site-packages\pycep_correios\apicep.py in fetch_address(cep)
22
23 if address['status'] == 400 and address['message'] == "Blocked by flood":
---> 24 raise exceptions.BlockedByFlood()
25
26 if address['status'] == 404:

BlockedByFlood:

O código que estou rodando é bem simples:

import pandas as pd
import pycep_correios
from geopy.geocoders import Nominatim

cep = '02538-010'

endereco = pycep_correios.get_address_from_cep(cep)
endereco

Sabe o que pode ser esse erro?

Obrigado

get_cep_from_address fora do ar

Olá 😄

Passando de novo pra reportar mais um comportamento curioso do ViaCep, não sei se tu sabe kkk, mas do nada o get_cep_from_address() fica fora do ar.

O erro levantado é o AttributeError e começou a acontecer isso hoje de tarde 😢 foi bem do nada kkk

Vi que no client.py é realizado uma requisição para a http://www.viacep.com.br/ws/{}/{}/{}/json e o site do viacep está fora do ar (no momento em que escrevo essa issue).

Isso é comum? Tem outra fonte alternativa?

Erro na consulta por cep

Olá (de novo)!

Estava fazendo uns testes aqui e me deparei com uma peculiaridade, as vezes quando consulto um cep com a função pycep_correios.get_address_from_cep(cep) ele retorna o erro AttributeError: 'ConnectionError' object has no attribute 'message'.

Isso acontece depois de um tempo consultando ceps, depois o erro some e depois o erro volta. Quando esse erro acontece eu utilizo a função antiga pycep_correios.consultar_cep(cep).

Isso já aconteceu antes? Ou é coisa nova?

CEP alterado, mas API retorna "não encontrado"

Em algumas buscas no site dos correios, temos a seguinte resposta : "ATENÇÃO! O CEP 13910-000 FOI ALTERADO CONFORME ABAIXO."
E informa o novo CEP.
Na consulta pela pycep-correios a resposta para este mesmo cep é :"CEP NÃO ENCONTRADO"

É possível um retorno onde traga a mesma resposta do site dos correios ?
Att,
André

Dúvidas / Sugestões (2018)

Este código esta funcionando em PHP 5, 5.6, 7.0, 7.1 ou até mesmo em 7.2 ?
São muitas dúvidas e nada pessoal... (Já deixo claro)
Este código esta nas normativas novas dos correios (2017) e que pelo visto já existe novas normativas em (2018)...
Bom, este não é o único que visualizamos que aparentemente esta tudo correto.
Mas, tenho que ser este USUÁRIO questionador, já que estamos enfrentando tantos problemas seja eles em PHP, AJAX ou qualquer impulso anterior á 2017.
E assim vem as dúvidas...

Gostaria de saber se podemos implementar este código em outras ferramentas e até mesmo em outas plataformas...

Espero que tenhamos uma resposta satisfatória e um UPGRADE. (O que neste notamos que o upgrade é notavel).

Php= 5.6, 7.0
S.O = Centos7 // Plesk
Plataforma = magento (se possivel)

Distritos dos bairros

Olá! Primeiramente, o projeto é massa <3

Vocês conhecem o conceito de distritos ? Eu procurei mas não achei no site dos correios informações sobre os distritos, eles só informam o bairro, e nem sempre o distrito é o bairro.

Vocês saberiam dizer, onde eu posso encontrar essa informação? (sem ser em um pdf)
Porque eu queria pesquisar por um CEP e pegar a informação de bairro e de distrito.

DeprecationWarning: defusedxml.lxml is no longer supported and will be removed in a future release.

Using pytest returns this warning, I believe it is from the zeep library used by the project

DeprecationWarning: defusedxml.lxml is no longer supported and will be removed in a future release.

can it stop working in the next version? Tks

Erro ao instalar

Linux mint 19
No BASH:
sudo python setup.py install

File "setup.py", line 15
SyntaxError: Non-ASCII character '\xc3' in file setup.py on line 15, but no encoding declared; see http://python.org/dev/peps/pep-0263/ for details

Urllib3 com warning

Olá,

ao rodar

import pycep_correios

pycep_correios.consultar_cep('69010001')

eu obtenho o warning:

/home/allex/algorithms/bml_aux_/env/lib/python3.6/site-packages/urllib3/connectionpool.py:858: InsecureRequestWarning: Unverified HTTPS request is being made. Adding certificate verification is strongly advised. See: https://urllib3.readthedocs.io/en/latest/advanced-usage.html#ssl-warnings
  InsecureRequestWarning)
INFO:pycep_correios.cliente:Consulta de CEP com sucesso!

Embora o eu consigo obter o resultado esparado, esse warning incomoda um pouco. Há alguma maneira de eu contorná-lo?

Status code equal to 200 but API return error

python version: 3.8.2

pycep-correios version: 4.0.1

Pode parecer um bug um pouco bizarro mas se você pesquisar o endereço dado o CEP 20000000 a bibloteca retorna o seguinte erro:

KeyError: 'bairro'

Fui pesquisar mais a fundo porque isso acontecia e descobri que o link que você está usando para pegar o endereço retorna o seguinte quando uso o CEP 20000000:

r = requests.get('http://www.viacep.com.br/ws/20000000/json')
print(r.status_code)
200
print(r.json())
{'erro': True}

Logo, apesar de ter ocorrido um erro no GET da API ele retorna status_code de sucesso.

Fiz um fork para tentar corrigir isso e basicamente só adiconei um if antes de testar se status_code==200 na função get_address_from_cep para checar se r.json()['error'] é verdadeiro e se for ele gera o BaseException

Initial Update

Hi 👊

This is my first visit to this fine repo, but it seems you have been working hard to keep all dependencies updated so far.

Once you have closed this issue, I'll create separate pull requests for every update as soon as I find one.

That's it for now!

Happy merging! 🤖

Substituir consulta de CEP para servidor ViaCEP

• Adicionar método consulta para 'get_address_from_cep'
  • testes
  • docs
• Adicionar chamado do novo método no init
• Definir metodo 'consultar_cep' como 'deprecated'
• Remover referências ao servidor antigo do README
• Remover referências ao servidor antigo da documentação

Criar classes de exceção

Criar classes de

• Timout
• Formato de requisição invalido
• Erro de Conexão

Melhoria no código da lib e alterações de uso

• Melhorias no código da lib e na estrutura do projeto, para uso mais intuitivo
• Melhoria na documentação dos módulos
• Utilizar TOX para testes

Substituir código de deploy do .travis.yml

No arquivo .travis.yml, substituir o código:

deploy:
  provider: pypi
  distributions: sdist bdist_wheel
  user: mstuttgart
  password:
    secure: HobE5ROuEvL6yUzb5NLvu01CAfo8oKgLZHJlP57pV8U1n1IATAd8zsX5CAb4x7GyGUwD4T1ZyK7HfgO0CDcgyWiP0V/sDRaX8Kjwo3pudhTMBDPlkhrr+/YqThD4ZMv4zc+2mLC8/eIX/MmvPcA+V4jCATwOwMzsOkVXq8tLHrBe1MjSc5F8IXtk2HfS0OCRnEpzJYjccE1lTItVP+i8QU42ggIH97sJxg4gmq3LArjozLuAdZ48EyB2ZKssZ00M1Kz01H4XeKvNonxd3aZlrcN33pcAHAy/be6zgA+3GiGGS4WtiecGKJGu4QXYPL5f9aKu/eI+1FmdB54+tYJmRjYn3HEJJYmrfcmKioavzITjrDenTJvzZpcRDeptj9EtlZ7d0Yhrh2QCPledVHeKetq+mrvfn0Kal/cWSah3CdcwOKs20hei/4eJ6SRb5+6DWOfg34WtLCaMkpdpD5C/ckdIvSiwR+tu+z9Me76LALWCylNdqTmqdoDpD0Z/bkZJSxZzNhsVnbXbHm1aQhA9lqDqGDTQ+5MYjc6UMtPbU6QewaXeBMpafKW+NFFf4MjH6et/s84QylcQoRM5gbGRSa+PnbtPO1RP7YF8TsJVWxEEmKeDv2j1zRg+yMNvrK0pvclQYZhV+u0ZtQhC0tNYNREZPwDJWH69sltbXQQwpOk=
  on:
    tags: true
    repo: mstuttgart/pycep-correios
    condition: ${TOX_ENV} == py35

por

deploy:
  provider: pypi
  distributions: "sdist bdist_wheel"
  user: mstuttgart
  password: $PYPI_PASSWORD
  on:
    tags: true
    repo: mstuttgart/pycep-correios
    condition: ${TOX_ENV} == py35

Remoção de arquivos inuteis no repositorio

Remoção dos arquivos:

• AUTHORS.rst
• HISTORY.rst

Atualizar MANIFEST.in

Portar código para python3

• Portar código do módulo para Python 3.
• O módulo suds que realiza a comunicação com o webservice dos Correios não possui versão para Python3, sendo assim, talvez seja necessário utilizar outro api. Provavelmente o módulo requests.

Can't install from pip README.md not found exception

$ pip3 install pycep-correios
Collecting pycep-correios
  Downloading pycep-correios-1.1.5.tar.gz
    Complete output from command python setup.py egg_info:
    Traceback (most recent call last):
      File "<string>", line 1, in <module>
      File "/tmp/pip-build-9wm2b1ms/pycep-correios/setup.py", line 16, in <module>
        long_description=open('README.md', 'r').read(),
    FileNotFoundError: [Errno 2] No such file or directory: 'README.md'
    
    ----------------------------------------
Command "python setup.py egg_info" failed with error code 1 in /tmp/pip-build-9wm2b1ms/pycep-correios/

Need to update MANIFEST.

Adicionar function 'get_ceps_from_address'

• Adicionar testes
• Adicionar functions
• Adicionar docs
• Adicionar function no init.py

Atualizar data de créditos para 2016-2020

Criar release 4.0.0

• Atualizar branch master
• Criar tag 4.0.0
• Atualizar historico
• Atualizar pypi
• Atualizar versão no version.py

Internacionalizar nome do método 'formatar_cep'

• Definir método como 'deprecated'
• Criar novo metodo 'format_cep'
• Adicionar testes em um arquivo separado
• Atualizar documentação

Adicionar testes com pytest

• Adicionar lib no requirements.txt
• Adicionar teste no .travis.yml
• Adicionar lib no setup.py
• Atualizar testes

Internacionalizar exceptions

• Atualizar nome do arquivo para 'exceptions.py'
• Internacionalizar nome da classe de exception
• Atualiazar init com os imports

jinja2.exceptions.TemplateNotFound: consultacep.xml

Error in version 1.1.6

Remoção do suporte para Python 3.3

Limiter o escopo de suporte apenas para versões recentes do Python evitando incompatibilidades ocasionais

• python 3.3

Utilizar .rst ao inves de .md no README

A mudança permite que o README seja utilizado na documentação e na página do modulo no PyPI.

CEP inválido retornar staus code

Fiz uma busca por um CEP inválido e recebi uma exception. Que tal retornar um status code, ou um dicionário com a mensgem de CEP INVÁLIDO ?

Consultas bem sucedidas podem retornar um status code = 200, caso contrário um status code diferente disso.

Utilizar comunicação com zeep

Utilizar a lib python-zeep para comunicação com webservice substituindo o modo atual de requisição por uma ferramenta mais madura e com amior base de usuários.

raise exceptions.BaseException(message=e.message)

Boa tarde, tudo bem? Vê se voce consegue me ajudar, por favor.

Estou utilizando o pycep_correios.get_address_from_cep no Windows 10 com o seguinte código:

pycep_correios.get

E estou encontrando o seguinte erro:

Obrigado desde já.

Adicionar ambiente de produção e homologação

Adicionar ambiente de produção e homologação para a lib. O ambiente deve ser passado como parâmetro para o método consultar_cep e deve ser uma constante.

URLS = {
    HOMOLOGACAO: 'https://apphom.correios.com.br/SigepMasterJPA/AtendeClienteService/AtendeCliente?wsdl',  #noqa
    PRODUCAO: 'https://apps.correios.com.br/SigepMasterJPA/AtendeClienteService/AtendeCliente?wsdl',  #noqa
}

Erro de "Split" no cep 999999999

Ao passar o cep '99999999' para a função abaixo, retorna o :

``
def validate_cep(cep):
try:
address = pycep_correios.get_address_from_cep(cep)
return [True, address]

except exceptions.InvalidCEP as eic:
    print(eic)

except exceptions.CEPNotFound as ecnf:
    print(ecnf)

except exceptions.ConnectionError as errc:
    print(errc)

except exceptions.Timeout as errt:
    print(errt)

except exceptions.HTTPError as errh:
    print(errh)

except exceptions.BaseException as e:
    print(e)

return [True, None]

``

File "C:\Users\evelyn.santos_saudei\Documents\projetos_python_saudeid\orcamento_exames_front\venv\lib\site-packages\pycep_correios\client.py", line 40, in get_address_from_cep
return apicep.fetch_address(cep)
File "C:\Users\evelyn.santos_saudei\Documents\projetos_python_saudeid\orcamento_exames_front\venv\lib\site-packages\pycep_correios\apicep.py", line 30, in fetch_address
'logradouro': address.get('address', '').split(' - até')[0],
AttributeError: 'NoneType' object has no attribute 'split'

Create English and others language versions of README.md and Docs

• English version of README.MD
• English version of documentation. The docs are build using sphinx. Create a en-US directory in docs folder and add docs pages translated to this folder.

Remoção do suporte para Python 2.7

São planejadas as seguintes novidades para a versão 3.0.0 da PyCEPCorreios:

• Remoção do suporte para Python 2.7

Remover testes com tox

• Remover .tox
• Remover dependência do requirements.txt
• Simplificar .travis.yml

Automatizar deploy para o PyPi

• Automatizar deploy para o PyPi
• Atualizar versão do Python para 3.5 na descrição do pacote.

API não retorna algumas localizações

como podemos melhorar a base, considerando que existem alguns ceps que os dados não são retornados?

Add support to proxy setting

Sometimes is necessary to add proxies different than the local ones. I would like to be able to set this while requesting to the correios API. Thanks!

Internacionalizar nome do método 'validar_cep'

• Definir método como 'deprecated'
• Criar novo metodo 'is_valid'
• Adicionar testes em um arquivo separado
• Atualizar documentação

Adicionar suporte para python 3.7

• Adicionar nova versão no setup.py
• Adicionar nova versão no .travis.yml

get_address_from_cep com erro para o cep 13866042

Quando utilizo a get_address_from_cep para o CEP 13866042, recebo o erro : pycep_correios.exceptions.BaseException: Other error

Quando utilizo a consultar_cep, não obtenho erro, e o endereço é retornado.

Suporte para Python 2.7

Adicionar suporte para Python 2.7 usando six. Para utilização de sistemas que ainda não podem ser migrados para Python 3 e para fins de estudo.

ValueError: CEP must be a non-empty string containing only numbers

Estou tentando obter endereços (Logradouros) a partir de uma lista de CEPs de uma base de dados. Porém está ocorrendo o erro descrito no título, mesmo a coluna em questão sendo do tipo integer e não contém valores nulos.

from geopy.geocoders import Nominatim
from geopy.extra.rate_limiter import RateLimiter
import pycep_correios
import pandas as pd
import psycopg2

conexao = psycopg2.connect(host='meuhost', database='table', user='user', password='password')
cursor = conexao.cursor()
cursor.execute('SELECT cep FROM tb_loja')
result = cursor.fetchall()
df = pd.DataFrame(result)
df.columns = [columns[0] for columns in cursor.description]

def get_adress(cep):
    end = pycep_correios.get_address_from_cep(cep)
    return end['logradouro']

geolocator = Nominatim(user_agent='cep_lat_long')
geocode = RateLimiter(geolocator.geocode, min_delay_seconds=1)
df['address'] = df['cep'].apply(get_adress)
print(df)

ERRO:

Traceback (most recent call last):
  File "C:/Users/linol/Documents/parquet/cep_test.py", line 21, in <module>
    df['address'] = df['cep'].apply(get_adress)
  File "C:\Users\linol\Documents\parquet\venv\lib\site-packages\pandas\core\series.py", line 4213, in apply
    mapped = lib.map_infer(values, f, convert=convert_dtype)
  File "pandas\_libs\lib.pyx", line 2403, in pandas._libs.lib.map_infer
  File "C:/Users/linol/Documents/parquet/cep_test.py", line 15, in get_adress
    end = pycep_correios.get_address_from_cep(cep)
  File "C:\Users\linol\Documents\parquet\venv\lib\site-packages\pycep_correios\client.py", line 31, in get_address_from_cep
    cep = _format_cep(cep)
  File "C:\Users\linol\Documents\parquet\venv\lib\site-packages\pycep_correios\client.py", line 54, in _format_cep
    raise ValueError('CEP must be a non-empty string containing only numbers')  # noqa
ValueError: CEP must be a non-empty string containing only numbers

Process finished with exit code 1

Criar documentação com sphinx

• Criar documentação com sphinx
• Hospedar documentação em readthedocs