Correios CEP

Find Brazilian addresses by postal code, directly from Correios API. No HTML parsers.

DEPRECATION NOTE

Correios.CEP.Address.zipcode is deprecated. Use Correios.CEP.Address.postal_code instead.

The version 0.5.1 introduces the field postal_code in Correios.CEP.Address struct with the same value of zipcode field. In the version 0.6.0 the zipcode field will be removed.

Installation

The package can be installed by adding correios_cep to your list of dependencies in mix.exs:

def deps do
  [
    {:correios_cep, "~> 0.5.1"}
  ]
end

Usage

iex> Correios.CEP.find_address("54250610")
{:ok,
 %Correios.CEP.Address{
   street: "Rua Fernando Amorim",
   neighborhood: "Cavaleiro",
   complement: "",
   city: "Jaboatão dos Guararapes",
   state: "PE",
   postal_code: "54250610",
   zipcode: "54250610"
 }}

iex> Correios.CEP.find_address("00000-000")
{:error, %Correios.CEP.Error{reason: "CEP NAO ENCONTRADO"}}

iex> Correios.CEP.find_address!("54250-610")
%Correios.CEP.Address{
  street: "Rua Fernando Amorim",
  neighborhood: "Cavaleiro",
  complement: "",
  city: "Jaboatão dos Guararapes",
  state: "PE",
  postal_code: "54250610",
  zipcode: "54250610"
}

iex> Correios.CEP.find_address!("00000-000")
** (Correios.CEP.Error) CEP NAO ENCONTRADO

Options

There are some supported options that can be added to the request, as timeouts, proxy and URL configuration.

The example below shows the use of request_timeout and proxy options:

iex> Correios.CEP.find_address("54250610", request_timeout: 3000, proxy: {"localhost", 8888})
{:ok,
 %Correios.CEP.Address{
   street: "Rua Fernando Amorim",
   neighborhood: "Cavaleiro",
   complement: "",
   city: "Jaboatão dos Guararapes",
   state: "PE",
   postal_code: "54250610",
   zipcode: "54250610"
 }}

See Correios.CEP.find_address/2 documentation to check the details of the available options.

Documentation

The full documentation is available at https://hexdocs.pm/correios_cep.

Contributing

See the contributing guide.

License

Correios CEP is released under the Apache 2.0 License. See the LICENSE file.

Copyright © 2018-2020 Fernando Hamasaki de Amorim

Author

Fernando Hamasaki de Amorim (prodis)