brazilcep

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
• ApiCEP (WideNet)
• OpenCEP

[!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.

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

pip install brazilcep

Quick Start

Making a request is straightforward. Start by importing the BrazilCEP module:

>>> import brazilcep

Next, use the get_address_from_cep function to query any CEP:

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

The result is a dictionary containing the address details:

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

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.

Contribute

To contribute, follow the guidelines outlined here.

Credits

Copyright (C) 2016-2024 by Michell Stuttgart