https://github.com/mstuttgart/brazilcep

:brazil: Minimalist and easy-to-use python library designed to query CEP (Postal Address Code) data.
https://github.com/mstuttgart/brazilcep

address api apicep brazil buscacep cep correios python viacep widenet

Last synced: 4 days ago
JSON representation

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

• Host: GitHub
• URL: https://github.com/mstuttgart/brazilcep
• Owner: mstuttgart
• License: mit
• Created: 2015-09-05T13:38:24.000Z (about 9 years ago)
• Default Branch: main
• Last Pushed: 2024-05-10T18:50:39.000Z (6 months ago)
• Last Synced: 2024-05-19T07:28:12.270Z (6 months ago)
• Topics: address, api, apicep, brazil, buscacep, cep, correios, python, viacep, widenet
• Language: Python
• Homepage: https://brazilcep.readthedocs.io/en/latest/
• Size: 1.28 MB
• Stars: 191
• Watchers: 18
• Forks: 54
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • Contributing: CONTRIBUTING.md
  • Funding: .github/FUNDING.yml
  • License: LICENSE

Awesome Lists containing this project

• starred-awesome - pycep-correios - Busca CEP utilizando webservice SIGEPWEB dos Correios (Python)

README

        



  

    

  

  


      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](https://viacep.com.br)

- [ApiCEP (WideNet)](https://apicep.com)

- [OpenCEP](https://opencep.com/)

> [!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](https://brazilcep.readthedocs.io/en/latest/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](http://pip-installer.org>):

```sh

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:

```python

>>> import brazilcep

```

Now, call the `get_address_from_cep` to query any CEP:

```python

>>> 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:

```python

 >>> 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](https://brazilcep.readthedocs.io/).

## Contribute

See this *guideline* [here](https://github.com/mstuttgart/brazilcep/blob/develop/CONTRIBUTING.md).

## Credits

Copyright (C) 2016-2024 by Michell Stuttgart