If you want to install BrazilCEP from the source code (for example, to use the latest development version or for contributing), follow these steps:

1. Clone the repository or download the tarball.
2. Navigate into the project directory.
3. Install the package in editable mode using pip install -e ..

git clone https://github.com/mstuttgart/brazilcep.git
cd brazilcep
pip install -e .

BrazilCEP requires Python 3.9 or higher. You can install it using pip or poetry.

pip install brazilcep

Or using poetry

poetry add brazilcep

For version >= 7.0.0, you can use async_get_address_from_cep to perform non-blocking requests. This is ideal for high-responsiveness applications like web services. This function must be awaited.

import asyncio
import brazilcep

async def main():
    address = await brazilcep.async_get_address_from_cep('37503-130')
    print(address)

asyncio.run(main())

BrazilCEP is a minimalist Python library used to query CEP (Postal Address Code) data. It provides a unified interface to search multiple services like ViaCEP, ApiCEP (WideNet), and OpenCEP.

Starting from version 7.0.0, the library supports both synchronous and asynchronous operations.

import brazilcep

# Query an address using a CEP string
address = brazilcep.get_address_from_cep('37503-130')
print(address)

To install the stable version of BrazilCEP using pip, run the following command in your terminal:

pip install brazilcep

By default, BrazilCEP uses the OpenCEP service. You can switch to other providers by importing the WebService class and passing the desired provider to the webservice parameter in get_address_from_cep.

from brazilcep import get_address_from_cep, WebService

# Example using APICEP
address = get_address_from_cep('37503-130', webservice=WebService.APICEP)

Use brazilcep.get_address_from_cep(cep) to perform a synchronous lookup. It returns a dictionary containing address details.

import brazilcep

# Query a CEP
address = brazilcep.get_address_from_cep('37503-130')

print(address)
# Output:
# {
#     'cep': '37503-130',
#     'street': 'Rua Geraldino Campista',
#     'district': 'Santo Antônio',
#     'city': 'Itajubá',
#     'uf': 'MG',
#     'complement': 'até 214/215'
# }

Use brazilcep.async_get_address_from_cep(cep) within an async function to perform asynchronous lookups. This is useful for concurrent operations.

import asyncio
import brazilcep

async def main():
    address = await brazilcep.async_get_address_from_cep('37503-130')
    print(address)

asyncio.run(main())

Use the get_address_from_cep function to retrieve address information for a specific CEP. The CEP must be provided as a string. The function returns a dict containing the address details.

import brazilcep

address = brazilcep.get_address_from_cep('37503-130')
print(address)
# Output example:
# {
#     'district': 'rua abc',
#     'cep': '37503130',
#     'city': 'city ABC',
#     'street': 'str',
#     'uf': 'str',
#     'complement': 'str',
# }

To prevent your application from hanging, you can specify a timeout parameter in your requests. You can also configure proxies using a dictionary following the requests library pattern.

from brazilcep import get_address_from_cep

proxies = {
    'https': '00.00.00.000',
    'http': '00.00.00.000',
}

# Using proxies and (optionally) a timeout
address = get_address_from_cep('37503-130', proxies=proxies, timeout=5)

To optimize performance when querying multiple addresses, use the asynchronous API with asyncio.gather to run requests in parallel.

import asyncio
from brazilcep import async_get_address_from_cep, WebService, exceptions

async def fetch_multiple_ceps():
    """Fetch multiple CEPs concurrently."""
    ceps = ['37503-130', '01310-100', '20040-020']

    tasks = [
        async_get_address_from_cep(cep, webservice=WebService.OPENCEP)
        for cep in ceps
    ]

    try:
        addresses = await asyncio.gather(*tasks)
        for cep, address in zip(ceps, addresses):
            print(f"\nCEP {cep}:")
            print(f"  Street: {address['street']}")
            print(f"  City: {address['city']}/{address['uf']}")
    except exceptions.BrazilCEPException as e:
        print(f"Error fetching addresses: {e}")

asyncio.run(fetch_multiple_ceps())