Awesome Open Source
Awesome Open Source

Correios CEP

Gem Version Build Status Coverage Status Code Climate GitHub license

Correios Logo

Current available solutions to find Brazilian addresses by zipcode use an HTML form from Correios web site website to perform it, instead of to use a real API.

The old solution works with an HTTP request to the form, followed by parsing HTML result page. The huge problem here is when the Correios web site development team decides to modify some HTML element in the result page, even a layout update, it will break the parser logic for result.

Correios CEP gem solves this problem, retrieving data directly from Correios database.



gem 'correios-cep'

Direct installation

$ gem install correios-cep


require 'correios-cep'

# With "get" instance method
finder =
address = finder.get('54250610')

# With "get" class method
address = Correios::CEP::AddressFinder.get('54250610')

address # =>
  :address => 'Rua Fernando Amorim',
  :neighborhood => 'Cavaleiro',
  :city => 'JaboatΓ£o dos Guararapes',
  :state => 'PE',
  :zipcode => '54250610',
  :complement => ''


All the configurations are set using Correios::CEP module.


For default, the timeout for a request to Correios Web Service is 5 seconds. If Correios Web Service does not respond, a HTTP::TimeoutError exception will be raised.

Correios::CEP.configure do |config|
  config.request_timeout = 3 # It configures timeout to 3 seconds

HTTP Proxy

If you need to use an HTTP proxy to HTTP requests, configure HTTP proxy URL.

Correios::CEP.configure do |config|
  config.proxy_url = ''


From 0.7.0 version, there is no more default logger, and the log level will be the same of the given logger.

Correios::CEP.configure do |config|
  config.logger = Rails.logger

Configuration example

Correios::CEP.configure do |config|
  config.logger = Rails.logger
  config.request_timeout = 3 # seconds



Fernando Hamasaki de Amorim (prodis)

Prodis Logo



See the contributing guide.


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

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
ruby (11,981)Β 
cep (20)Β 
correios (13)Β 

Find Open Source By Browsing 7,000 Topics Across 59 Categories