API Reference¶

This section of the documentation provides details about all the interfaces of BrazilCEP.

Client¶

The primary functionality of BrazilCEP can be accessed through the following function:

brazilcep.get_address_from_cep(cep, webservice=WebService.OPENCEP, timeout=5, proxies=None)[source]¶

This function queries a specified web service to retrieve address information based on the provided CEP. It supports multiple web services and allows customization of request parameters such as timeout and proxy settings.

Parameters:

cep (str) – The CEP (Brazilian postal code) to query. Must be a valid 8-digit string.
webservice (WebService, optional) – The web service to use for the query. Defaults to WebService.OPENCEP. Supported values are: - WebService.OPENCEP - WebService.VIACEP - WebService.APICEP timeout (Optional[int]): Timeout in seconds for the request. Defaults to 5 seconds.
timeout (Optional[int], optional) – The maximum time, in seconds, to wait for a response. Defaults to 5 seconds.
proxies (Optional[dict], optional) – A dictionary mapping protocols (e.g., “http”, “https”) to proxy URLs.

Raises:

ValueError – If the provided CEP is invalid (e.g., not properly formatted or not 8 digits).
KeyError – If the specified webservice is not a valid WebService enum value.

Returns:

A dictionary containing the address data corresponding to the queried CEP.

Return type:

dict

Examples

>>> address = get_address_from_cep("01001000", webservice=WebService.VIACEP)
>>> print(address)
{
    "cep": "01001000",
    "street": "Praça da Sé",
    "complement": "lado ímpar",
    "disctric": "Sé",
    "city": "São Paulo",
    "uf": "SP",
}

async brazilcep.async_get_address_from_cep(cep, webservice=WebService.OPENCEP, timeout=5, proxies=None)[source]¶

Asynchronously fetch the address associated with a given CEP (Brazilian postal code).

This function queries a specified web service to retrieve address information based on the provided CEP. It supports multiple web services and allows customization of request parameters such as timeout and proxy settings.

Parameters:

cep (str) – The CEP (Brazilian postal code) to query. Must be a valid 8-digit string.
webservice (WebService, optional) – The web service to use for the query. Defaults to WebService.OPENCEP. Supported values are: - WebService.OPENCEP - WebService.VIACEP - WebService.APICEP
timeout (Optional[int], optional) – The maximum time, in seconds, to wait for a response. Defaults to 5 seconds.
proxies (Optional[dict], optional) – A dictionary mapping protocols (e.g., “http”, “https”) to proxy URLs.

Raises:

ValueError – If the provided CEP is invalid (e.g., not properly formatted or not 8 digits).
KeyError – If the specified webservice is not a valid WebService enum value.

Returns:

A dictionary containing the address data corresponding to the queried CEP.

Return type:

dict

Examples

>>> address = await async_get_address_from_cep("01001000", webservice=WebService.VIACEP)
>>> print(address)
{
    "cep": "01001000",
    "street": "Praça da Sé",
    "complement": "lado ímpar",
    "disctric": "Sé",
    "city": "São Paulo",
    "uf": "SP",
}

Exceptions¶

The following exceptions are available in BrazilCEP:

exception brazilcep.exceptions.BrazilCEPException[source]¶: Base class for exceptions

exception brazilcep.exceptions.ConnectionError[source]¶: Exception raised by a BrazilCEP connection error

exception brazilcep.exceptions.HTTPError[source]¶: Exception raised by HTTP error

exception brazilcep.exceptions.URLRequired[source]¶: Exception raised for using an invalid URL to make a request

exception brazilcep.exceptions.TooManyRedirects[source]¶: Exception raised by too many redirects

exception brazilcep.exceptions.Timeout[source]¶: Exception raised when a request times out

exception brazilcep.exceptions.InvalidCEP[source]¶: Exception raised for invalid CEP requests

exception brazilcep.exceptions.CEPNotFound[source]¶: Exception raised when a CEP is not found

exception brazilcep.exceptions.BlockedByFlood[source]¶: Exception raised due to a flood of requests being blocked

Webservices¶

BrazilCEP supports the following webservice integrations:

brazilcep.apicep.fetch_address(cep, timeout=None, proxies=None)[source]¶

Fetch address data from the ApiCEP web service using a given CEP.

This function sends a synchronous HTTP request to the ApiCEP API to retrieve address information for the provided CEP (Brazilian postal code).

Parameters:

cep (str) – The CEP to be searched.
timeout (Union[None, int], optional) – The number of seconds to wait for the server to respond. Defaults to None.
proxies (Union[None, dict], optional) – A dictionary mapping protocol to the URL of the proxy. Defaults to None.

Raises:

exceptions.ConnectionError – Raised when a connection error occurs.
exceptions.HTTPError – Raised for HTTP errors.
exceptions.URLRequired – Raised when an invalid URL is used for the request.
exceptions.TooManyRedirects – Raised when too many redirects occur.
exceptions.Timeout – Raised when the request times out.
exceptions.InvalidCEP – Raised for invalid CEP requests.
exceptions.BlockedByFlood – Raised when the API blocks the request due to excessive usage.
exceptions.CEPNotFound – Raised when the requested CEP is not found.
exceptions.BrazilCEPException – Base class for other exceptions.

Returns:

A dictionary containing the formatted address data.

Return type:

dict

brazilcep.opencep.fetch_address(cep, timeout=None, proxies=None)[source]¶

Fetch address data from the OpenCEP API using a given CEP.

This function queries the OpenCEP REST API to retrieve address information for a given Brazilian postal code (CEP). It handles various exceptions and returns a standardized address dictionary.

Parameters:

cep (str) – The CEP to be searched.
timeout (Union[None, int], optional) – The number of seconds to wait for the server to respond. Defaults to None.
proxies (Union[None, dict], optional) – A dictionary mapping protocol to the URL of the proxy. Defaults to None.

Raises:

exceptions.ConnectionError – Raised for connection errors.
exceptions.HTTPError – Raised for HTTP errors.
exceptions.URLRequired – Raised for invalid URLs.
exceptions.TooManyRedirects – Raised for too many redirects.
exceptions.Timeout – Raised when the request times out.
exceptions.InvalidCEP – Raised for invalid CEP requests.
exceptions.CEPNotFound – Raised when the CEP is not found.
exceptions.BrazilCEPException – Base class for other exceptions.

Returns:

A dictionary containing standardized address data.

Return type:

dict

brazilcep.viacep.fetch_address(cep, timeout=None, proxies=None)[source]¶

Fetch address information for a given CEP using the ViaCEP API.

This function sends a synchronous HTTP request to the ViaCEP API to retrieve address information for the specified CEP (postal code).

Parameters:

cep (str) – The CEP to be searched.
timeout (Union[None, int], optional) – The number of seconds to wait for the server to respond. Defaults to None.
proxies (Union[None, dict], optional) – A dictionary mapping protocol to the URL of the proxy. Defaults to None.

Raises:

exceptions.ConnectionError – Raised for connection errors.
exceptions.HTTPError – Raised for HTTP errors.
exceptions.URLRequired – Raised if an invalid URL is used for the request.
exceptions.TooManyRedirects – Raised if too many redirects occur.
exceptions.Timeout – Raised if the request times out.
exceptions.InvalidCEP – Raised if the provided CEP is invalid.
exceptions.CEPNotFound – Raised if the CEP is not found in the API response.
exceptions.BrazilCEPException – Base class for other exceptions.

Returns:

A dictionary containing standardized address information.

Return type:

dict

Migration from PyCEPCorreios¶

BrazilCEP is the new name for the former PyCEPCorreios. Migrating your code is simple and requires minimal changes.

Update the import statements from:

import pycepcorreios

to:

import brazilcep

Adjust the keys in the query results returned by the get_address_from_cep function.

The keys have been translated to English. Below is an example of the old and new formats:

Old format:

get_address_from_cep('37503-130')
{
   'bairro': 'rua abc',
   'cep': '37503130',
   'cidade': 'city ABC',
   'logradouro': 'str',
   'uf': 'str',
   'complemento': 'str',
}

New format:

get_address_from_cep('37503-130')
{
   'district': 'rua abc',
   'cep': '37503130',
   'city': 'city ABC',
   'street': 'str',
   'uf': 'str',
   'complement': 'str',
}

Note that the following exception has been removed:

BaseException

API Reference¶

Client¶

Exceptions¶

Webservices¶

Migration from PyCEPCorreios¶

Table of Contents

Useful Links