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: 3 months 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 (almost 10 years ago)
- Default Branch: main
- Last Pushed: 2024-05-10T18:50:39.000Z (about 1 year ago)
- Last Synced: 2024-05-19T07:28:12.270Z (about 1 year 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 |
Quick Start |
Documentation |
Contribute |
Credits
## About
**BrazilCEP** is a minimalist and easy-to-use Python library designed to query CEP (Postal Address Code) data.
Its goal is to provide a unified query interface for multiple search services, simplifying the integration of Python applications with these services.
Currently, it supports several CEP APIs:
- [ViaCEP](https://viacep.com.br)
- [ApiCEP (WideNet)](https://apicep.com)
- [OpenCEP](https://opencep.com)
> [!NOTE]
> **BrazilCEP** is the new name of the former **PyCEPCorreio** Python library.
> To migrate your old code to the new version, refer to the [migration guide](https://brazilcep.readthedocs.io/api.html#migrate-from-pycepcorreios).
> [!TIP]
> **CEP** or **Código de Endereçamento Postal** (_Postal Address Code_) is a system of numeric codes created, maintained, and organized by _Correios do Brasil_ to streamline address organization and delivery of letters and parcels.
## Install
To install the latest stable release of BrazilCEP, use [pip](http://pip-installer.org):
```sh
pip install brazilcep
```
## Quick Start
Making a request is straightforward. Start by importing the BrazilCEP module:
```python
>>> import brazilcep
```
Next, use the `get_address_from_cep` function to query any CEP:
```python
>>> address = brazilcep.get_address_from_cep('37503-130')
```
The result is a dictionary containing the address details:
```python
>>> address
{
'district': 'rua abc',
'cep': '37503130',
'city': 'city ABC',
'street': 'str',
'uf': 'str',
'complement': 'str',
}
```
The CEP must always be provided as a string.
> [!TIP]
> BrazilCEP is designed for on-demand queries in web applications. Bulk querying through scripts or other means is discouraged.
> [!IMPORTANT]
> BrazilCEP does not guarantee the availability or support of any third-party query APIs. This library serves as a convenient interface for accessing these services.
#### Asynchronous Requests with BrazilCEP
BrazilCEP (version >= 7.0.0) also supports asynchronous operations , allowing you to retrieve address information for a given CEP without blocking your application. This is particularly useful for web applications or services that require high responsiveness.
To perform an asynchronous request, use the `async_get_address_from_cep` function:
```python
import asyncio
import brazilcep
async def main():
address = await brazilcep.async_get_address_from_cep('37503-130')
print(address)
asyncio.run(main())
```
> [!NOTE]
> This function is asynchronous and must be awaited when called.
> Ensure that your environment supports asynchronous programming before using this function.
## Documentation
Comprehensive documentation for BrazilCEP is available on [ReadTheDocs](https://brazilcep.readthedocs.io/).
## Contribute
To contribute, follow the guidelines outlined [here](https://brazilcep.readthedocs.io/contributing.html).
## Credits
Copyright (C) 2016-2024 by Michell Stuttgart