Wolfram Function Repository

Instant-use add-on functions for the Wolfram Language

Function Repository Resource:

 BrazilPostcodeLookup

Source Notebook

Find information and address details for a Brazilian postal code

Contributed by: Daniel de Souza Carvalho

ResourceFunction["BrazilPostcodeLookup"][code]

returns a Dataset of address data for a given Brazilian postal code code.

Details and Options

Brazilian postal codes are called CEPs ("Código de Endereçamento Postal") in Portuguese and are eight-digit numbers.
Postal codes should be input as hyphenated strings (e.g. "03819-250").
Some condos, government buildings, colleges, factories, etc can have a unique code.
By default, the Dataset returned has the following keys:

"cep"Brazilian zip code number (CEP - Código de Endereçamento Postal)
"logradouro"street or avenue name
"complemento"additional optional data
"bairro"neighborhood or city name
"localidade"county
"uf"state name code (acronym)
"ibge"official geographical brazilian id (IBGE - Instituto Brasileiro de Geografia e Estatística )
"gia"Brazilian regional tax code
"ddd"local area phone code
"siafi"another IBGE code

ResourceFunction["BrazilPostcodeLookup"] takes an option "ServiceSource" indicating where to obtain its data. The default value is "Viacep"; also accepted is the value "Brazilapi".

Examples

Basic Examples (3) 

Lookup data for a given postal code from downtown São Paulo downtown:

In[1]:=
ResourceFunction["BrazilPostcodeLookup"]["01037-010"]
Out[1]=

Get data for MASP (Museu de Arte de São Paulo):

In[2]:=
ResourceFunction["BrazilPostcodeLookup"]["01310-200"]
Out[2]=

Get CEP data for the capital Brazilia (Palácio do Planalto region):

In[3]:=
ResourceFunction["BrazilPostcodeLookup"]["70150-900"]
Out[3]=

Scope (1) 

Get address data for UNICAMP (Universidade Estadual de Campinas):

In[4]:=
ResourceFunction["BrazilPostcodeLookup"]["13083-970", "ServiceSource" -> "Brazilapi"]
Out[4]=

Options (5) 

The default web service used is ViaCEP; fields are returned in Brazilian Portuguese:

In[5]:=
ResourceFunction["BrazilPostcodeLookup"]["03819250"]
Out[5]=

Specifying the WEB Service BrazilAPI returns less data but we get the geo location:

In[6]:=
address = ResourceFunction["BrazilPostcodeLookup"]["01007-040", "ServiceSource" -> "Brazilapi"]
Out[6]=

Show the geo location:

In[7]:=
address["location"]
Out[7]=

Convert the geo location from a string to numbers:

In[8]:=
ToExpression@{address["location"]["coordinates"]["latitude"], address["location"]["coordinates"]["longitude"]}
Out[8]=

View as a GeoGraphics:

In[9]:=
GeoGraphics[GeoDisk[GeoPosition[%], Quantity[1, "Kilometers"]], GeoProjection -> "Robinson"]

Possible Issues (1) 

For incorrect or unknown CEP numbers an error is returned:

In[10]:=
ResourceFunction["BrazilPostcodeLookup"]["99900011", "ServiceSource" -> "Brazilapi"]
Out[10]=
In[11]:=
ResourceFunction["BrazilPostcodeLookup"]["99999999"]
Out[11]=

Neat Examples (2) 

Get the Insper college address from Open Street Map:

In[12]:=
insper = Dataset[Import[ "https://nominatim.openstreetmap.org/search.php?format=jsonv2&q=Insper", "RawJSON"]]
Out[12]=

Get the full address:

In[13]:=
insper[1, "display_name"]
Out[13]=

Look for the CEP number by pattern:

In[14]:=
StringCases[%, RegularExpression["\\d{5}-\\d{3}"]]
Out[14]=

Finally, get the CEP info:

In[15]:=
ResourceFunction["BrazilPostcodeLookup"][First[%]]
Out[15]=

Display the region within 1km of USP (Universidade de São Paulo) college:

In[16]:=
GeoGraphics[ GeoDisk[GeoPosition[ ToExpression[ Normal[Sort[ Values[ResourceFunction["BrazilPostcodeLookup"]["05508220", "ServiceSource" -> "Brazilapi"]["location"][ "coordinates"]]]]]], Quantity[1, "Kilometers"]]]

Publisher

Daniel de Souza Carvalho

Version History

  • 1.0.0 – 14 June 2023

Source Metadata

Related Resources

Author Notes

Address data is obtained from experimental web APIs. Be gentle with the number of consecutive requests; if identified as SPAM your IP address can be blocked.

License Information